file-organization

File Organization and Subscriber Context Types

Core Principles

1. File Organization: Group files by common prefixes infinitely until only one file with unique name remains in each directory
2. One File Per Entity: 1 file = 1 class/interface/type/enum
3. Index Exports: Every directory with 2+ files must have index.ts
4. Typed DATA Interfaces: All execution contexts must have typed DATA interfaces to provide autocomplete and type safety
5. Helper Types: Create helper types that require only the Entity generic parameter

DATA Interface Structure

Function Context DATA

Base interface for function subscriber execution contexts:

export interface IApiSubscriberFunctionExecutionContextData<E extends IApiBaseEntity> {
  readonly eventManager?: EntityManager;
  readonly repository: Repository<E>;
}

Route Context DATA

Two interfaces for route subscriber execution contexts:

• IApiSubscriberRouteExecutionContextData<E> - for before hooks (basic metadata)
• IApiSubscriberRouteExecutionContextDataExtended<E> - for after/error hooks (includes headers, ip, authenticationRequest)

Helper Type Pattern

Create helper types that encapsulate all generic parameters except Entity:

// Instead of requiring 3 generics:
IApiSubscriberFunctionExecutionContext<User, TApiFunctionCreateProperties<User>, IApiSubscriberFunctionExecutionContextData<User>>

// Provide a helper with just 1 generic:
export type TApiSubscriberFunctionBeforeCreateContext<E extends IApiBaseEntity> = 
  IApiSubscriberFunctionExecutionContext<E, TApiFunctionCreateProperties<E>, IApiSubscriberFunctionExecutionContextData<E>>;

File Organization Rules (Universal)

These rules apply to ALL files in the project, not just subscribers.

Principle: Infinite Grouping by Common Prefixes

Files with common prefixes MUST be grouped into directories. Continue grouping recursively until each directory contains only files with unique names (after removing the common prefix).