@venizia/ignis-docs 0.0.2 → 0.0.4-0

package/wiki/{get-started/best-practices → best-practices}/code-style-standards.md

@@ -115,7 +115,56 @@ Use the centralized TypeScript configs:
 - `strict: true` - Strict type checking with selective relaxations
 - `skipLibCheck: true` - Faster compilation
 
-See [`@venizia/dev-configs` documentation](../../references/src-details/dev-configs.md) for full details.
+See [`@venizia/dev-configs` documentation](../references/src-details/dev-configs.md) for full details.
+
+## Directory Structure
+
+### Component Organization
+
+```
+src/components/[feature]/
+├── index.ts              # Barrel exports
+├── component.ts          # IoC binding setup
+├── controller.ts         # Route handlers
+└── common/
+    ├── index.ts          # Barrel exports
+    ├── keys.ts           # Binding key constants
+    ├── types.ts          # Interfaces and types
+    └── rest-paths.ts     # Route path constants
+```
+
+### Complex Component (with multiple features)
+
+```
+src/components/auth/
+├── index.ts
+├── authenticate/
+│   ├── index.ts
+│   ├── component.ts
+│   ├── common/
+│   ├── controllers/
+│   ├── services/
+│   └── strategies/
+└── models/
+    ├── entities/         # Database models
+    └── requests/         # Request schemas
+```
+
+### Barrel Exports
+
+Every folder should have an `index.ts` that re-exports its contents:
+
+```typescript
+// components/health-check/index.ts
+export * from './common';
+export * from './component';
+export * from './controller';
+
+// components/health-check/common/index.ts
+export * from './keys';
+export * from './rest-paths';
+export * from './types';
+```
 
 ## Naming Conventions
 
@@ -184,53 +233,357 @@ export class SocketIOBindingKeys {
 }
 ```
 
-## Directory Structure
+## Private Field Naming Convention
 
-### Component Organization
+Use underscore prefix (`_`) for private and protected class fields to distinguish them from public fields and method parameters.
 
+```typescript
+class MyRepository extends BaseRepository {
+  // Private fields with underscore prefix
+  private _dataSource: IDataSource;
+  private _entity: BaseEntity;
+  private _hiddenProperties: Set<string> | null = null;
+
+  // Protected fields also use underscore prefix
+  protected _schemaFactory?: ReturnType<typeof createSchemaFactory>;
+
+  constructor(dataSource: IDataSource) {
+    // 'dataSource' (param) vs '_dataSource' (field)
+    this._dataSource = dataSource;
+  }
+}
 ```
-src/components/[feature]/
-├── index.ts              # Barrel exports
-├── component.ts          # IoC binding setup
-├── controller.ts         # Route handlers
-└── common/
-    ├── index.ts          # Barrel exports
-    ├── keys.ts           # Binding key constants
-    ├── types.ts          # Interfaces and types
-    └── rest-paths.ts     # Route path constants
+
+**Benefits:**
+- Clear distinction between fields and parameters
+- Avoids naming conflicts in constructors
+- Consistent with TypeScript community conventions
+
+## Sentinel Value Pattern for Caching
+
+Use `null` to distinguish "not computed" from "computed as undefined" for lazy-initialized cached values.
+
+```typescript
+class Repository {
+  // null = not computed yet, undefined = computed but no value
+  private _visibleProperties: Record<string, any> | null | undefined = null;
+
+  get visibleProperties(): Record<string, any> | undefined {
+    if (this._visibleProperties !== null) {
+      return this._visibleProperties;
+    }
+    // Compute once and cache (may be undefined)
+    this._visibleProperties = this.computeVisibleProperties();
+    return this._visibleProperties;
+  }
+}
 ```
 
-### Complex Component (with multiple features)
+**Why not just `undefined`?**
+- `undefined` can be a valid computed result
+- `null` clearly indicates "never computed"
+- Prevents redundant re-computation
+
+## Type Safety
+
+To ensure long-term maintainability and catch errors at compile-time, Ignis enforces strict type safety.
+
+### Avoid `any` and `unknown`
+
+**Never use `any` or `unknown` as much as possible.** You must specify clear, descriptive types for all variables, parameters, and return values.
+
+-   **`any`**: Bypasses all type checking and leads to "runtime surprises". It is strictly discouraged.
+-   **`unknown`**: While safer than `any`, it still forces consumers to perform manual type checking. Prefer using generics or specific interfaces.
 
+**Why?**
+- **Maintenance**: Developers reading your code in the future will know exactly what the data structure is.
+- **Refactoring**: Changing an interface automatically highlights all broken code across the monorepo.
+- **Documentation**: Types act as a self-documenting contract for your APIs and services.
+
+## Type Definitions
+
+### Explicit Return Types
+Always define explicit return types for **public methods** and **API handlers**.
+
+**Why?**
+- **Compiler Performance:** Speeds up TypeScript type checking in large projects.
+- **Safety:** Prevents accidental exposure of internal types or sensitive data.
+
+```typescript
+// ✅ GOOD
+public async findUser(id: string): Promise<User | null> { ... }
+
+// ❌ BAD (Implicit inference)
+public async findUser(id: string) { ... }
 ```
-src/components/auth/
-├── index.ts
-├── authenticate/
-│   ├── index.ts
-│   ├── component.ts
-│   ├── common/
-│   ├── controllers/
-│   ├── services/
-│   └── strategies/
-└── models/
-    ├── entities/         # Database models
-    └── requests/         # Request schemas
+
+## Type Inference Patterns
+
+### Zod Schema to Type
+
+```typescript
+// Define schema
+export const SignInRequestSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+
+// Infer type from schema
+export type TSignInRequest = z.infer<typeof SignInRequestSchema>;
 ```
 
-### Barrel Exports
+### Const Assertion for Literal Types
 
-Every folder should have an `index.ts` that re-exports its contents:
+```typescript
+const RouteConfigs = {
+  GET_USERS: { method: 'GET', path: '/users' },
+  GET_USER_BY_ID: { method: 'GET', path: '/users/:id' },
+} as const;
+
+// Type is now narrowed to literal values
+type RouteKey = keyof typeof RouteConfigs; // 'GET_USERS' | 'GET_USER_BY_ID'
+```
+
+### Generic Type Constraints
 
 ```typescript
-// components/health-check/index.ts
-export * from './common';
-export * from './component';
-export * from './controller';
+export class DefaultCRUDRepository<
+  Schema extends TTableSchemaWithId = TTableSchemaWithId
+> {
+  // Schema is constrained to have an 'id' column
+}
 
-// components/health-check/common/index.ts
-export * from './keys';
-export * from './rest-paths';
-export * from './types';
+export interface IAuthService<
+  SIRQ extends TSignInRequest = TSignInRequest,
+  SIRS = AnyObject,
+> {
+  signIn(context: Context, opts: SIRQ): Promise<SIRS>;
+}
+```
+
+### Method Overloading for Conditional Returns
+
+Use TypeScript method overloads when return types depend on input options:
+
+```typescript
+class Repository<T, R> {
+  // Overload 1: shouldReturn: false → data is null
+  create(opts: { data: T; options: { shouldReturn: false } }): Promise<{ count: number; data: null }>;
+  // Overload 2: shouldReturn: true (default) → data is R
+  create(opts: { data: T; options?: { shouldReturn?: true } }): Promise<{ count: number; data: R }>;
+  // Implementation signature
+  create(opts: { data: T; options?: { shouldReturn?: boolean } }): Promise<{ count: number; data: R | null }> {
+    // implementation
+  }
+}
+
+// Usage
+const result1 = await repo.create({ data: user, options: { shouldReturn: false } });
+// result1.data is typed as null
+
+const result2 = await repo.create({ data: user });
+// result2.data is typed as R (the entity type)
+```
+
+**When to use:**
+- Return type varies based on boolean flag
+- API with optional "return data" behavior
+- Methods with conditional processing
+
+## Module Exports
+
+### Prefer Named Exports
+Avoid `export default` except for configuration files (e.g., `eslint.config.mjs`) or lazy-loaded components. Use named exports for all classes, functions, and constants.
+
+**Why?**
+- **Refactoring:** Renaming a symbol automatically updates imports across the monorepo.
+- **Consistency:** Enforces consistent naming across all files importing the module.
+
+```typescript
+// ✅ GOOD
+export class UserController { ... }
+
+// ❌ BAD
+export default class UserController { ... }
+```
+
+## Function Signatures
+
+### The Options Object Pattern
+Prefer using a single object parameter (`opts`) over multiple positional arguments, especially for constructors and public methods with more than 2 arguments.
+
+**Why?**
+- **Extensibility:** You can add new properties without breaking existing calls.
+- **Readability:** Named keys act as documentation at the call site.
+
+```typescript
+// ✅ GOOD
+class UserService {
+  createUser(opts: { name: string; email: string; role?: string }) { ... }
+}
+// Usage: service.createUser({ name: 'John', email: 'john@example.com' });
+
+// ❌ BAD
+class UserService {
+  createUser(name: string, email: string, role?: string) { ... }
+}
+// Usage: service.createUser('John', 'john@example.com');
+```
+
+## Function Naming Conventions
+
+Use consistent prefixes based on function purpose:
+
+| Prefix | Purpose | Examples |
+|--------|---------|----------|
+| `generate*` | Create column definitions / schemas | `generateIdColumnDefs()`, `generateTzColumnDefs()` |
+| `build*` | Construct complex objects | `buildPrimitiveCondition()`, `buildJsonOrderBy()` |
+| `to*` | Convert/transform data | `toCamel()`, `toBoolean()`, `toStringDecimal()` |
+| `is*` | Boolean validation/check | `isWeekday()`, `isInt()`, `isFloat()`, `isPromiseLike()` |
+| `extract*` | Pull out specific parts | `extractTimestamp()`, `extractWorkerId()`, `extractSequence()` |
+| `enrich*` | Enhance with additional data | `enrichUserAudit()`, `enrichWithMetadata()` |
+| `get*` | Retrieve/fetch data | `getSchema()`, `getConnector()`, `getError()` |
+| `resolve*` | Determine/compute value | `resolveValue()`, `resolvePath()` |
+
+**Examples:**
+
+```typescript
+// Generators - create schema definitions
+const idCols = generateIdColumnDefs({ id: { dataType: 'string' } });
+const tzCols = generateTzColumnDefs();
+
+// Builders - construct complex query objects
+const condition = buildPrimitiveCondition(column, operator, value);
+const orderBy = buildJsonOrderBy(schema, path, direction);
+
+// Converters - transform data types
+const camelCase = toCamel('snake_case');
+const bool = toBoolean('true');
+const decimal = toStringDecimal(123.456, 2);
+
+// Validators - boolean checks
+if (isWeekday(date)) { /* ... */ }
+if (isInt(value)) { /* ... */ }
+if (isPromiseLike(result)) { /* ... */ }
+
+// Extractors - pull specific data
+const timestamp = extractTimestamp(snowflakeId);
+const workerId = extractWorkerId(snowflakeId);
+```
+
+## Route Definition Patterns
+
+Ignis supports three methods for defining routes. Choose based on your needs:
+
+### Method 1: Config-Driven Routes
+
+Define route configurations as constants with UPPER_CASE names:
+
+```typescript
+// common/rest-paths.ts
+export class UserRestPaths {
+  static readonly ROOT = '/';
+  static readonly BY_ID = '/:id';
+  static readonly PROFILE = '/profile';
+}
+
+// common/route-configs.ts
+export const RouteConfigs = {
+  GET_USERS: {
+    method: HTTP.Methods.GET,
+    path: UserRestPaths.ROOT,
+    responses: jsonResponse({
+      [HTTP.ResultCodes.RS_2.Ok]: UserListSchema,
+    }),
+  },
+  GET_USER_BY_ID: {
+    method: HTTP.Methods.GET,
+    path: UserRestPaths.BY_ID,
+    request: {
+      params: z.object({ id: z.string() }),
+    },
+    responses: jsonResponse({
+      [HTTP.ResultCodes.RS_2.Ok]: UserSchema,
+      [HTTP.ResultCodes.RS_4.NotFound]: ErrorSchema,
+    }),
+  },
+} as const;
+```
+
+### Method 2: Using `@api` Decorator
+
+```typescript
+@controller({ path: '/users' })
+export class UserController extends BaseController {
+
+  @api({ configs: RouteConfigs.GET_USERS })
+  list(context: TRouteContext<typeof RouteConfigs.GET_USERS>) {
+    return context.json({ users: [] }, HTTP.ResultCodes.RS_2.Ok);
+  }
+
+  @api({ configs: RouteConfigs.GET_USER_BY_ID })
+  getById(context: TRouteContext<typeof RouteConfigs.GET_USER_BY_ID>) {
+    const { id } = context.req.valid('param');
+    return context.json({ id, name: 'User' }, HTTP.ResultCodes.RS_2.Ok);
+  }
+}
+```
+
+### Method 3: Using `bindRoute` (Programmatic)
+
+```typescript
+@controller({ path: '/health' })
+export class HealthCheckController extends BaseController {
+  constructor() {
+    super({ scope: HealthCheckController.name });
+
+    this.bindRoute({ configs: RouteConfigs.GET_HEALTH }).to({
+      handler: context => context.json({ status: 'ok' }),
+    });
+  }
+}
+```
+
+### Method 4: Using `defineRoute` (Inline)
+
+```typescript
+@controller({ path: '/health' })
+export class HealthCheckController extends BaseController {
+  constructor() {
+    super({ scope: HealthCheckController.name });
+
+    this.defineRoute({
+      configs: RouteConfigs.POST_PING,
+      handler: context => {
+        const { message } = context.req.valid('json');
+        return context.json({ echo: message }, HTTP.ResultCodes.RS_2.Ok);
+      },
+    });
+  }
+}
+```
+
+### OpenAPI Schema Integration
+
+Use Zod with `.openapi()` for automatic documentation:
+
+```typescript
+const CreateUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+}).openapi({
+  description: 'Create user request body',
+  example: { email: 'user@example.com', name: 'John Doe' },
+});
+
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  name: z.string(),
+  createdAt: z.string().datetime(),
+}).openapi({
+  description: 'User response',
+});
 ```
 
 ## Constants Pattern
@@ -427,6 +780,28 @@ constructor(options: IJWTTokenServiceOptions) {
 }
 ```
 
+## Environment Variables Management
+
+Avoid using `process.env` directly in your business logic. Instead, use the `applicationEnvironment` helper and define your keys as constants. This ensures type safety and centralized management.
+
+**Define Keys (`src/common/environments.ts`):**
+```typescript
+export class EnvironmentKeys {
+  static readonly APP_ENV_STRIPE_KEY = 'APP_ENV_STRIPE_KEY';
+  static readonly APP_ENV_MAX_RETRIES = 'APP_ENV_MAX_RETRIES';
+}
+```
+
+**Usage:**
+```typescript
+import { applicationEnvironment } from '@venizia/ignis';
+import { EnvironmentKeys } from '@/common/environments';
+
+// Correct usage
+const stripeKey = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_STRIPE_KEY);
+const retries = applicationEnvironment.get<number>(EnvironmentKeys.APP_ENV_MAX_RETRIES);
+```
+
 ## Logging Patterns
 
 ### Method Context Prefix
@@ -451,46 +826,6 @@ this.logger.info('[create] User created | ID: %s | Email: %s', user.id, user.ema
 this.logger.debug('[config] Server options: %j', this.serverOptions);
 ```
 
-## Scope Naming
-
-Every class extending a base class should set its scope using `ClassName.name`:
-
-```typescript
-export class JWTTokenService extends BaseService {
-  constructor() {
-    super({ scope: JWTTokenService.name });
-  }
-}
-
-export class UserController extends BaseController {
-  constructor() {
-    super({ scope: UserController.name });
-  }
-}
-```
-
-## Environment Variables Management
-
-Avoid using `process.env` directly in your business logic. Instead, use the `applicationEnvironment` helper and define your keys as constants. This ensures type safety and centralized management.
-
-**Define Keys (`src/common/environments.ts`):**
-```typescript
-export class EnvironmentKeys {
-  static readonly APP_ENV_STRIPE_KEY = 'APP_ENV_STRIPE_KEY';
-  static readonly APP_ENV_MAX_RETRIES = 'APP_ENV_MAX_RETRIES';
-}
-```
-
-**Usage:**
-```typescript
-import { applicationEnvironment } from '@venizia/ignis';
-import { EnvironmentKeys } from '@/common/environments';
-
-// Correct usage
-const stripeKey = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_STRIPE_KEY);
-const retries = applicationEnvironment.get<number>(EnvironmentKeys.APP_ENV_MAX_RETRIES);
-```
-
 ## Standardized Error Handling
 
 Use the `getError` helper and `HTTP` constants to throw consistent, formatted exceptions that the framework's error handler can process correctly.
@@ -551,163 +886,285 @@ constructor(options: IServiceOptions) {
 | Not Found | `HTTP.ResultCodes.RS_4.NotFound` | Resource not found |
 | Internal Error | `HTTP.ResultCodes.RS_5.InternalServerError` | Server errors |
 
-## Route Definition Patterns
-
-Ignis supports three methods for defining routes. Choose based on your needs:
+## Control Flow Patterns
 
-### Method 1: Config-Driven Routes
+### Mandatory Braces
 
-Define route configurations as constants:
+**Always use braces for `if`, `for`, `while`, and `do-while` statements**, even for single-line bodies. Never use inline statements.
 
 ```typescript
-// common/rest-paths.ts
-export class UserRestPaths {
-  static readonly ROOT = '/';
-  static readonly BY_ID = '/:id';
-  static readonly PROFILE = '/profile';
+// ✅ GOOD - Always use braces
+if (condition) {
+  doSomething();
 }
 
-// common/route-configs.ts
-export const ROUTE_CONFIGS = {
-  [UserRestPaths.ROOT]: {
-    method: HTTP.Methods.GET,
-    path: UserRestPaths.ROOT,
-    responses: jsonResponse({
-      [HTTP.ResultCodes.RS_2.Ok]: UserListSchema,
-    }),
-  },
-  [UserRestPaths.BY_ID]: {
-    method: HTTP.Methods.GET,
-    path: UserRestPaths.BY_ID,
-    request: {
-      params: z.object({ id: z.string().uuid() }),
-    },
-    responses: jsonResponse({
-      [HTTP.ResultCodes.RS_2.Ok]: UserSchema,
-      [HTTP.ResultCodes.RS_4.NotFound]: ErrorSchema,
-    }),
-  },
-} as const;
+for (const item of items) {
+  process(item);
+}
+
+while (running) {
+  tick();
+}
+
+do {
+  attempt();
+} while (retrying);
+
+// ❌ BAD - Never inline without braces
+if (condition) doSomething();
+for (const item of items) process(item);
+while (running) tick();
 ```
 
-### Method 2: Using `@api` Decorator
+**Why braces are mandatory:**
+- Prevents bugs when adding statements later
+- Clearer code structure at a glance
+- Consistent formatting across codebase
 
-```typescript
-@controller({ path: '/users' })
-export class UserController extends BaseController {
+### Switch Statement Requirements
 
-  @api({ configs: ROUTE_CONFIGS[UserRestPaths.ROOT] })
-  list(context: TRouteContext<typeof ROUTE_CONFIGS[typeof UserRestPaths.ROOT]>) {
-    return context.json({ users: [] }, HTTP.ResultCodes.RS_2.Ok);
-  }
+**All switch statements must:**
+1. Use braces `{}` for each case block
+2. Include a `default` case (even if it throws)
 
-  @api({ configs: ROUTE_CONFIGS[UserRestPaths.BY_ID] })
-  getById(context: TRouteContext<typeof ROUTE_CONFIGS[typeof UserRestPaths.BY_ID]>) {
-    const { id } = context.req.valid('param');
-    return context.json({ id, name: 'User' }, HTTP.ResultCodes.RS_2.Ok);
+```typescript
+// ✅ GOOD - Braces and default case
+switch (status) {
+  case 'active': {
+    activateUser();
+    break;
+  }
+  case 'inactive': {
+    deactivateUser();
+    break;
+  }
+  case 'pending': {
+    notifyAdmin();
+    break;
+  }
+  default: {
+    throw getError({
+      statusCode: HTTP.ResultCodes.RS_4.BadRequest,
+      message: `Unknown status: ${status}`,
+    });
   }
 }
+
+// ❌ BAD - Missing braces and default case
+switch (status) {
+  case 'active':
+    activateUser();
+    break;
+  case 'inactive':
+    deactivateUser();
+    break;
+  // Missing default case!
+}
 ```
 
-### Method 3: Using `bindRoute` (Programmatic)
+**Why these rules:**
+- Braces prevent variable scoping issues between cases
+- Default case ensures all values are handled
+- Throwing in default catches unexpected values early
+
+## Scope Naming
+
+Every class extending a base class should set its scope using `ClassName.name`:
 
 ```typescript
-@controller({ path: '/health' })
-export class HealthCheckController extends BaseController {
+export class JWTTokenService extends BaseService {
   constructor() {
-    super({ scope: HealthCheckController.name });
+    super({ scope: JWTTokenService.name });
+  }
+}
 
-    this.bindRoute({ configs: ROUTE_CONFIGS['/'] }).to({
-      handler: context => context.json({ status: 'ok' }),
-    });
+export class UserController extends BaseController {
+  constructor() {
+    super({ scope: UserController.name });
   }
 }
 ```
 
-### Method 4: Using `defineRoute` (Inline)
+## Code Organization
+
+### Section Separator Comments
+
+Use visual separators for major code sections in long files:
 
 ```typescript
-@controller({ path: '/health' })
-export class HealthCheckController extends BaseController {
-  constructor() {
-    super({ scope: HealthCheckController.name });
+// ---------------------------------------------------------------------------
+// Type Definitions
+// ---------------------------------------------------------------------------
 
-    this.defineRoute({
-      configs: ROUTE_CONFIGS['/ping'],
-      handler: context => {
-        const { message } = context.req.valid('json');
-        return context.json({ echo: message }, HTTP.ResultCodes.RS_2.Ok);
-      },
-    });
-  }
+type TMyType = { /* ... */ };
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_OPTIONS = { /* ... */ };
+
+// ---------------------------------------------------------------------------
+// Main Implementation
+// ---------------------------------------------------------------------------
+
+export class MyClass {
+  // ...
 }
 ```
 
-### OpenAPI Schema Integration
+**Guidelines:**
+- Use for files > 200 lines with distinct sections
+- Use 75-character wide separator lines
+- Descriptive section names (2-4 words)
 
-Use Zod with `.openapi()` for automatic documentation:
+### Import Organization Order
+
+Organize imports in this order:
 
 ```typescript
-const CreateUserSchema = z.object({
-  email: z.string().email(),
-  name: z.string().min(1).max(100),
-}).openapi({
-  description: 'Create user request body',
-  example: { email: 'user@example.com', name: 'John Doe' },
-});
+// 1. Node built-ins (with 'node:' prefix)
+import fs from 'node:fs';
+import path from 'node:path';
+
+// 2. Third-party packages (alphabetical)
+import { z } from '@hono/zod-openapi';
+import dayjs from 'dayjs';
+
+// 3. Internal absolute imports (by domain/package)
+import { getError } from '@venizia/ignis-helpers';
+import { BaseEntity } from '@/base/models';
+import { UserService } from '@/services';
+
+// 4. Relative imports (same feature) - LAST
+import { AbstractRepository } from './base';
+import { QueryBuilder } from '../query';
+```
 
-const UserSchema = z.object({
-  id: z.string().uuid(),
-  email: z.string().email(),
-  name: z.string(),
-  createdAt: z.string().datetime(),
-}).openapi({
-  description: 'User response',
+**Rules:**
+- Blank line between each group
+- Alphabetical within each group
+- `node:` prefix for Node.js built-ins
+- Relative imports only for same feature/module
+
+## Performance Logging Pattern
+
+Use `performance.now()` for timing critical operations:
+
+```typescript
+const t = performance.now();
+
+// ... operation to measure ...
+
+this.logger.info('[methodName] DONE | Took: %s (ms)', performance.now() - t);
+```
+
+**With the helper utility:**
+
+```typescript
+import { executeWithPerformanceMeasure } from '@venizia/ignis';
+
+await executeWithPerformanceMeasure({
+  logger: this.logger,
+  scope: 'DataSync',
+  description: 'Sync user records',
+  task: async () => {
+    await syncAllUsers();
+  },
 });
+// Logs: [DataSync] Sync user records | Took: 1234.56 (ms)
 ```
 
-## Type Inference Patterns
+## Advanced Patterns
 
-### Zod Schema to Type
+### Mixin Pattern
+
+Create reusable class extensions without deep inheritance:
 
 ```typescript
-// Define schema
-export const SignInRequestSchema = z.object({
-  email: z.string().email(),
-  password: z.string().min(8),
-});
+import { TMixinTarget } from '@venizia/ignis';
 
-// Infer type from schema
-export type TSignInRequest = z.infer<typeof SignInRequestSchema>;
+export const LoggableMixin = <BaseClass extends TMixinTarget<Base>>(
+  baseClass: BaseClass,
+) => {
+  return class extends baseClass {
+    protected logger = LoggerFactory.getLogger(this.constructor.name);
+
+    log(message: string): void {
+      this.logger.info(message);
+    }
+  };
+};
+
+// Usage
+class MyService extends LoggableMixin(BaseService) {
+  doWork(): void {
+    this.log('Work started');  // Method from mixin
+  }
+}
 ```
 
-### Const Assertion for Literal Types
+### Factory Pattern with Dynamic Class
+
+Generate classes dynamically with configuration:
 
 ```typescript
-const ROUTE_CONFIGS = {
-  '/users': { method: 'GET', path: '/users' },
-  '/users/:id': { method: 'GET', path: '/users/:id' },
-} as const;
+class ControllerFactory {
+  static defineCrudController<Schema extends TTableSchemaWithId>(
+    opts: ICrudControllerOptions<Schema>,
+  ) {
+    return class extends BaseController {
+      constructor(repository: AbstractRepository<Schema>) {
+        super({ scope: opts.controller.name });
+        this.repository = repository;
+        this.setupRoutes();
+      }
+
+      private setupRoutes(): void {
+        // Dynamically bind CRUD routes
+      }
+    };
+  }
+}
 
-// Type is now narrowed to literal values
-type RouteKey = keyof typeof ROUTE_CONFIGS; // '/users' | '/users/:id'
+// Usage
+const UserCrudController = ControllerFactory.defineCrudController({
+  controller: { name: 'UserController', basePath: '/users' },
+  repository: { name: UserRepository.name },
+  entity: () => User,
+});
+
+@controller({ path: '/users' })
+export class UserController extends UserCrudController {
+  // Additional custom routes
+}
 ```
 
-### Generic Type Constraints
+### Value Resolver Pattern
+
+Support multiple input types that resolve to a single value:
 
 ```typescript
-export class DefaultCRUDRepository<
-  Schema extends TTableSchemaWithId = TTableSchemaWithId
-> {
-  // Schema is constrained to have an 'id' column
-}
+export type TValueOrResolver<T> = T | TResolver<T> | TConstructor<T>;
 
-export interface IAuthService<
-  SIRQ extends TSignInRequest = TSignInRequest,
-  SIRS = AnyObject,
-> {
-  signIn(context: Context, opts: SIRQ): Promise<SIRS>;
+export const resolveValue = <T>(valueOrResolver: TValueOrResolver<T>): T => {
+  if (typeof valueOrResolver !== 'function') {
+    return valueOrResolver;  // Direct value
+  }
+  if (isClassConstructor(valueOrResolver)) {
+    return valueOrResolver as T;  // Class constructor (return as-is)
+  }
+  return (valueOrResolver as TResolver<T>)();  // Function resolver
+};
+
+// Usage
+interface IOptions {
+  entity: TValueOrResolver<typeof User>;
 }
+
+// All valid:
+const opts1: IOptions = { entity: User };           // Direct class
+const opts2: IOptions = { entity: () => User };     // Resolver function
 ```
 
 ## Summary Table
@@ -718,11 +1175,19 @@ export interface IAuthService<
 | Type alias prefix | `T` (e.g., `TUserRequest`) |
 | Class naming | PascalCase with suffix (e.g., `UserController`) |
 | File naming | kebab-case (e.g., `user.controller.ts`) |
+| Private fields | Underscore prefix (`_dataSource`) |
 | Binding keys | `@app/[component]/[feature]` |
 | Constants | Static readonly class (not enums) |
 | Barrel exports | `index.ts` at every folder level |
 | Error format | `[ClassName][method] Message` |
 | Logging format | `[method] Message \| Key: %s` |
 | Default options | `DEFAULT_OPTIONS` constant |
+| Type safety | No `any` or `unknown` allowed |
 | Scope naming | `ClassName.name` |
-
+| Arguments | Options object (`opts`) |
+| Exports | Named exports only |
+| Return types | Explicitly defined |
+| Control flow | Always use braces (`{}`) |
+| Switch statements | Braces + default case required |
+| Imports | Node → Third-party → Internal → Relative |
+| Function naming | `generate*`, `build*`, `to*`, `is*`, `extract*` |