@venizia/ignis-docs 0.0.3 → 0.0.4-0

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

@@ -115,7 +115,7 @@ 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
 
@@ -233,6 +233,57 @@ export class SocketIOBindingKeys {
 }
 ```
 
+## Private Field Naming Convention
+
+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;
+  }
+}
+```
+
+**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;
+  }
+}
+```
+
+**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.
@@ -284,13 +335,13 @@ export type TSignInRequest = z.infer<typeof SignInRequestSchema>;
 ### Const Assertion for Literal Types
 
 ```typescript
-const ROUTE_CONFIGS = {
-  '/users': { method: 'GET', path: '/users' },
-  '/users/:id': { method: 'GET', path: '/users/:id' },
+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 ROUTE_CONFIGS; // '/users' | '/users/:id'
+type RouteKey = keyof typeof RouteConfigs; // 'GET_USERS' | 'GET_USER_BY_ID'
 ```
 
 ### Generic Type Constraints
@@ -310,6 +361,35 @@ export interface IAuthService<
 }
 ```
 
+### 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
@@ -350,13 +430,54 @@ class UserService {
 // 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:
+Define route configurations as constants with UPPER_CASE names:
 
 ```typescript
 // common/rest-paths.ts
@@ -367,19 +488,19 @@ export class UserRestPaths {
 }
 
 // common/route-configs.ts
-export const ROUTE_CONFIGS = {
-  [UserRestPaths.ROOT]: {
+export const RouteConfigs = {
+  GET_USERS: {
     method: HTTP.Methods.GET,
     path: UserRestPaths.ROOT,
     responses: jsonResponse({
       [HTTP.ResultCodes.RS_2.Ok]: UserListSchema,
     }),
   },
-  [UserRestPaths.BY_ID]: {
+  GET_USER_BY_ID: {
     method: HTTP.Methods.GET,
     path: UserRestPaths.BY_ID,
     request: {
-      params: z.object({ id: z.string().uuid() }),
+      params: z.object({ id: z.string() }),
     },
     responses: jsonResponse({
       [HTTP.ResultCodes.RS_2.Ok]: UserSchema,
@@ -395,13 +516,13 @@ export const ROUTE_CONFIGS = {
 @controller({ path: '/users' })
 export class UserController extends BaseController {
 
-  @api({ configs: ROUTE_CONFIGS[UserRestPaths.ROOT] })
-  list(context: TRouteContext<typeof ROUTE_CONFIGS[typeof UserRestPaths.ROOT]>) {
+  @api({ configs: RouteConfigs.GET_USERS })
+  list(context: TRouteContext<typeof RouteConfigs.GET_USERS>) {
     return context.json({ users: [] }, HTTP.ResultCodes.RS_2.Ok);
   }
 
-  @api({ configs: ROUTE_CONFIGS[UserRestPaths.BY_ID] })
-  getById(context: TRouteContext<typeof ROUTE_CONFIGS[typeof UserRestPaths.BY_ID]>) {
+  @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);
   }
@@ -416,7 +537,7 @@ export class HealthCheckController extends BaseController {
   constructor() {
     super({ scope: HealthCheckController.name });
 
-    this.bindRoute({ configs: ROUTE_CONFIGS['/'] }).to({
+    this.bindRoute({ configs: RouteConfigs.GET_HEALTH }).to({
       handler: context => context.json({ status: 'ok' }),
     });
   }
@@ -432,7 +553,7 @@ export class HealthCheckController extends BaseController {
     super({ scope: HealthCheckController.name });
 
     this.defineRoute({
-      configs: ROUTE_CONFIGS['/ping'],
+      configs: RouteConfigs.POST_PING,
       handler: context => {
         const { message } = context.req.valid('json');
         return context.json({ echo: message }, HTTP.ResultCodes.RS_2.Ok);
@@ -765,6 +886,87 @@ constructor(options: IServiceOptions) {
 | Not Found | `HTTP.ResultCodes.RS_4.NotFound` | Resource not found |
 | Internal Error | `HTTP.ResultCodes.RS_5.InternalServerError` | Server errors |
 
+## Control Flow Patterns
+
+### Mandatory Braces
+
+**Always use braces for `if`, `for`, `while`, and `do-while` statements**, even for single-line bodies. Never use inline statements.
+
+```typescript
+// ✅ GOOD - Always use braces
+if (condition) {
+  doSomething();
+}
+
+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();
+```
+
+**Why braces are mandatory:**
+- Prevents bugs when adding statements later
+- Clearer code structure at a glance
+- Consistent formatting across codebase
+
+### Switch Statement Requirements
+
+**All switch statements must:**
+1. Use braces `{}` for each case block
+2. Include a `default` case (even if it throws)
+
+```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!
+}
+```
+
+**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`:
@@ -783,6 +985,188 @@ export class UserController extends BaseController {
 }
 ```
 
+## Code Organization
+
+### Section Separator Comments
+
+Use visual separators for major code sections in long files:
+
+```typescript
+// ---------------------------------------------------------------------------
+// Type Definitions
+// ---------------------------------------------------------------------------
+
+type TMyType = { /* ... */ };
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_OPTIONS = { /* ... */ };
+
+// ---------------------------------------------------------------------------
+// Main Implementation
+// ---------------------------------------------------------------------------
+
+export class MyClass {
+  // ...
+}
+```
+
+**Guidelines:**
+- Use for files > 200 lines with distinct sections
+- Use 75-character wide separator lines
+- Descriptive section names (2-4 words)
+
+### Import Organization Order
+
+Organize imports in this order:
+
+```typescript
+// 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';
+```
+
+**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)
+```
+
+## Advanced Patterns
+
+### Mixin Pattern
+
+Create reusable class extensions without deep inheritance:
+
+```typescript
+import { TMixinTarget } from '@venizia/ignis';
+
+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
+  }
+}
+```
+
+### Factory Pattern with Dynamic Class
+
+Generate classes dynamically with configuration:
+
+```typescript
+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
+      }
+    };
+  }
+}
+
+// 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
+}
+```
+
+### Value Resolver Pattern
+
+Support multiple input types that resolve to a single value:
+
+```typescript
+export type TValueOrResolver<T> = T | TResolver<T> | TConstructor<T>;
+
+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
 
 | Aspect | Standard |
@@ -791,6 +1175,7 @@ export class UserController extends BaseController {
 | 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 |
@@ -801,4 +1186,8 @@ export class UserController extends BaseController {
 | Scope naming | `ClassName.name` |
 | Arguments | Options object (`opts`) |
 | Exports | Named exports only |
-| Return types | Explicitly defined |
+| 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*` |

package/wiki/{get-started/best-practices → best-practices}/common-pitfalls.md

@@ -125,14 +125,119 @@ APP_ENV_POSTGRES_DATABASE=db
 
 ## 5. Not Using `as const` for Route Definitions
 
-**Pitfall:** When using the decorator-based routing with a shared `ROUTE_CONFIGS` object, you forget to add `as const` to the object definition. TypeScript will infer the types too broadly, and you will lose the benefits of type-safe contexts (`TRouteContext`).
+**Pitfall:** When using the decorator-based routing with a shared `RouteConfigs` object, you forget to add `as const` to the object definition. TypeScript will infer the types too broadly, and you will lose the benefits of type-safe contexts (`TRouteContext`).
 
 **Solution:** Always use `as const` when exporting a shared route configuration object.
 
 **Example (`src/controllers/test/definitions.ts`):**
 ```typescript
-export const ROUTE_CONFIGS = {
-  // ... your route definitions
+export const RouteConfigs = {
+  GET_USERS: { /* ... */ },
+  GET_USER_BY_ID: { /* ... */ },
 } as const; // <-- This is crucial!
 ```
-This ensures that `TRouteContext<typeof ROUTE_CONFIGS['/path']>` has the precise types for request body, params, and response.
+This ensures that `TRouteContext<typeof RouteConfigs.GET_USERS>` has the precise types for request body, params, and response.
+
+## 6. Bulk Operations Without WHERE Clause
+
+**Problem:** Attempting to update or delete all records without an explicit `where` condition.
+
+**Solution:** Ignis prevents accidental bulk data destruction. You must either provide a `where` condition or explicitly set `force: true`.
+
+```typescript
+// ❌ BAD - Will throw error
+await userRepository.updateBy({
+  data: { status: 'INACTIVE' },
+  where: {},  // Empty where = targets ALL records
+});
+// Error: [updateBy] DENY to perform updateBy | Empty where condition
+
+// ✅ GOOD - Explicit where condition
+await userRepository.updateBy({
+  data: { status: 'INACTIVE' },
+  where: { lastLoginAt: { lt: new Date('2024-01-01') } },
+});
+
+// ✅ GOOD - Intentionally affect all records with force flag
+await userRepository.updateBy({
+  data: { status: 'INACTIVE' },
+  where: {},
+  options: { force: true },  // Explicitly allow empty where
+});
+```
+
+> [!WARNING]
+> The `force: true` flag bypasses the safety check. Only use when you intentionally want to affect ALL records in the table.
+
+## 7. Schema Key Mismatch
+
+**Problem:** Entity name doesn't match the table name registered in the DataSource's schema.
+
+**Error Message:**
+```
+[UserRepository] Schema key mismatch | Entity name 'User' not found in connector.query | Available keys: [Configuration, Post]
+```
+
+**Solution:** Ensure your entity class name matches the table name in `pgTable()`:
+
+```typescript
+// ❌ BAD - Class name 'User' doesn't match table name 'users'
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = pgTable('users', { /* ... */ });  // Lowercase 'users'
+}
+
+// ✅ GOOD - Class name matches table name
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = pgTable('User', { /* ... */ });  // Matches class name
+}
+```
+
+**Why this matters:** The framework uses `entity.name` (class name) to look up the query interface in `connector.query`. If they don't match, the repository can't find its table.
+
+## 8. Validation Error Response Structure
+
+**Problem:** Client receives validation errors but doesn't know how to parse them.
+
+**Solution:** Understand the Zod validation error response format:
+
+```json
+{
+  "statusCode": 422,
+  "message": "ValidationError",
+  "requestId": "abc123",
+  "details": {
+    "cause": [
+      {
+        "path": "email",
+        "message": "Invalid email",
+        "code": "invalid_string",
+        "expected": "email",
+        "received": "string"
+      },
+      {
+        "path": "age",
+        "message": "Expected number, received string",
+        "code": "invalid_type",
+        "expected": "number",
+        "received": "string"
+      }
+    ]
+  }
+}
+```
+
+**Client-side handling:**
+```typescript
+try {
+  await api.post('/users', data);
+} catch (error) {
+  if (error.response?.status === 422) {
+    const errors = error.response.data.details.cause;
+    errors.forEach(err => {
+      console.log(`Field '${err.path}': ${err.message}`);
+    });
+  }
+}
+```

package/wiki/{get-started/best-practices → best-practices}/contribution-workflow.md

@@ -40,6 +40,32 @@ make install
 git remote add upstream https://github.com/VENIZIA-AI/ignis.git
 ```
 
+## Package Build Order
+
+Ignis is a monorepo with interdependent packages. Understanding the dependency chain is critical for development:
+
+```
+dev-configs → inversion → helpers → boot → core
+     ↓            ↓           ↓        ↓      ↓
+  @venizia/   @venizia/   @venizia/  @venizia/  @venizia/
+  dev-configs ignis-      ignis-     ignis-     ignis
+              inversion   helpers    boot       (core)
+```
+
+**Dependency meanings:**
+| Package | Depends On | Purpose |
+|---------|------------|---------|
+| `dev-configs` | - | Shared ESLint, TypeScript configs |
+| `inversion` | dev-configs | IoC container, DI primitives |
+| `helpers` | inversion | Utilities, loggers, crypto |
+| `boot` | helpers | Application bootstrapping |
+| `core` | boot | Full framework (controllers, repos, etc.) |
+
+**Why this matters:**
+- If you modify `helpers`, you must rebuild `boot` and `core`
+- If you modify `inversion`, you must rebuild `helpers`, `boot`, and `core`
+- The Makefile handles this automatically with dependencies
+
 ## Makefile Commands
 
 The project uses a Makefile for common development tasks:
@@ -53,14 +79,15 @@ The project uses a Makefile for common development tasks:
 | `make lint` | Lint all packages |
 | `make help` | Show all available commands |
 
-**Individual package builds:**
+**Individual package builds** (dependencies are automatically resolved):
 ```bash
-make core          # Build @venizia/ignis (after dependencies)
-make boot          # Build @venizia/ignis-boot
-make helpers       # Build @venizia/ignis-helpers
-make inversion     # Build @venizia/ignis-inversion
-make dev-configs   # Build @venizia/dev-configs
-make docs          # Build documentation
+make core          # Build @venizia/ignis (builds dev-configs → inversion → helpers → boot → core)
+make boot          # Build @venizia/ignis-boot (builds dev-configs → inversion → helpers → boot)
+make helpers       # Build @venizia/ignis-helpers (builds dev-configs → inversion → helpers)
+make inversion     # Build @venizia/ignis-inversion (builds dev-configs → inversion)
+make dev-configs   # Build @venizia/dev-configs only
+make docs          # Build VitePress documentation (independent)
+make docs-mcp      # Build MCP documentation server
 ```
 
 **Force update individual packages:**