file-organization

File Organization

Guidelines for organizing code into files following single responsibility principle.

actions:

• type: suggest message: | When organizing code into files, follow these rules:

  1. Single Definition Per File:

     • Each class should be in its own file
     • Each standalone function should be in its own file
     • Each complex type/interface (more than one line) should be in its own file Example:

     // Bad: Multiple definitions in one file
     // user-types.ts
     interface UserCredentials {
       username: string;
       password: string;
     }
     interface UserProfile {
       id: string;
       name: string;
       email: string;
     }
     class UserService {
       // ...
     }
     
     // Good: Separate files for each definition
     // user-credentials.ts
     interface UserCredentials {
       username: string;
       password: string;
     }
     
     // user-profile.ts
     interface UserProfile {
       id: string;
       name: string;
       email: string;
     }
     
     // user-service.ts
     class UserService {
       // ...
     }
     

  2. File Naming Conventions:

     • Use kebab-case for filenames
     • Name files after their primary export
     • Use suffixes to indicate type: .interface.ts, .type.ts, .service.ts, etc. Example:

     // Good file names:
     user-credentials.interface.ts
     user-profile.interface.ts
     user-service.ts
     create-user.function.ts
     

  3. Simple Type Exceptions:

     • Single-line type aliases and interfaces can be co-located if they're tightly coupled Example:

     // Acceptable in the same file:
     type UserId = string;
     type UserRole = 'admin' | 'user';
     interface BasicUser { id: string; role: UserRole; }
     

  4. Barrel File Usage:

     • Use index.ts files to re-export related components
     • Keep barrel files simple - export only, no implementations Example:

     // users/index.ts
     export * from './user-credentials.interface';
     export * from './user-profile.interface';
     export * from './user-service';
     

  5. Directory Structure:

     • Group related files in directories
     • Use feature-based organization Example:

     src/
     ├── users/
     │   ├── interfaces/
     │   │   ├── user-credentials.interface.ts
     │   │   └── user-profile.interface.ts
     │   ├── services/
     │   │   └── user-service.ts
     │   └── index.ts
     └── ...
     

  6. Import Organization:

     • Keep imports organized by type (external, internal, relative)
     • Use explicit imports over namespace imports Example:

     // External imports
     import { Injectable } from '@nestjs/common';
     import { v4 as uuid } from 'uuid';
     
     // Internal imports (from your app)
     import { UserProfile } from '@/users/interfaces';
     import { DatabaseService } from '@/database';
     
     // Relative imports (same feature)
     import { UserCredentials } from './user-credentials.interface';
     

examples:

• input: | // Bad: Multiple concerns in one file interface UserData { id: string; name: string; }

  class UserService { getUser(id: string) { } }

  function validateUser(user: UserData) { } output: | // user-data.interface.ts interface UserData { id: string; name: string; }