@venizia/ignis-docs 0.0.4-0 → 0.0.4-2

package/wiki/best-practices/code-style-standards/naming-conventions.md

@@ -0,0 +1,174 @@
+# Naming Conventions
+
+Consistent naming improves code readability and maintainability.
+
+## 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';
+```
+
+## Class Names
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Components | `[Feature]Component` | `HealthCheckComponent`, `AuthComponent` |
+| Controllers | `[Feature]Controller` | `UserController`, `AuthController` |
+| Services | `[Feature]Service` | `JWTTokenService`, `PaymentService` |
+| Repositories | `[Feature]Repository` | `UserRepository`, `OrderRepository` |
+| Strategies | `[Feature]Strategy` | `JWTAuthenticationStrategy` |
+| Factories | `[Feature]Factory` | `UIProviderFactory` |
+
+## File Names
+
+Both styles are acceptable: `[type].ts` or `[name].[type].ts`
+
+| Type | Single File | Multiple Files |
+|------|-------------|----------------|
+| Components | `component.ts` | `auth.component.ts` |
+| Controllers | `controller.ts` | `user.controller.ts` |
+| Services | `service.ts` | `jwt-token.service.ts` |
+| Repositories | `repository.ts` | `user.repository.ts` |
+| Types/Interfaces | `types.ts` | `user.types.ts` |
+| Constants | `constants.ts` | `keys.ts`, `rest-paths.ts` |
+| Schemas | `schema.ts` | `sign-in.schema.ts` |
+
+**Guidelines:**
+- Use `[type].ts` when there's only one file of that type in the folder
+- Use `[name].[type].ts` when there are multiple files of the same type
+- Use kebab-case for multi-word names: `jwt-token.service.ts`
+
+## Type and Interface Prefixes
+
+```typescript
+// Interfaces use 'I' prefix
+interface IHealthCheckOptions {
+  restOptions: { path: string };
+}
+
+interface IAuthService {
+  signIn(context: Context): Promise<void>;
+}
+
+// Type aliases use 'T' prefix
+type TSignInRequest = z.infer<typeof SignInRequestSchema>;
+type TRouteContext = Context<Env, Path, Input>;
+
+// Generic constraints
+type TTableSchemaWithId = { id: PgColumn };
+```
+
+## Binding Keys
+
+Use static class with `@app/[component]/[feature]` format:
+
+```typescript
+export class HealthCheckBindingKeys {
+  static readonly HEALTH_CHECK_OPTIONS = '@app/health-check/options';
+}
+
+export class SocketIOBindingKeys {
+  static readonly SOCKET_IO_INSTANCE = '@app/socket-io/instance';
+  static readonly SERVER_OPTIONS = '@app/socket-io/server-options';
+}
+```
+
+## Private Field Naming
+
+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
+
+## See Also
+
+- [Type Safety](./type-safety) - Type naming and constraints
+- [Function Patterns](./function-patterns) - Function naming conventions
+- [Constants & Configuration](./constants-configuration) - Constant naming

package/wiki/best-practices/code-style-standards/route-definitions.md

@@ -0,0 +1,150 @@
+# Route Definitions
+
+Ignis supports multiple 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);
+      },
+    });
+  }
+}
+```
+
+## Comparison
+
+| Method | Use Case | Pros | Cons |
+|--------|----------|------|------|
+| `@api` decorator | Most routes | Clean, declarative | Requires decorator support |
+| `bindRoute` | Dynamic routes | Programmatic control | More verbose |
+| `defineRoute` | Simple inline routes | Quick setup | Less reusable |
+
+## 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',
+});
+```
+
+## Request Validation
+
+```typescript
+export const RouteConfigs = {
+  CREATE_USER: {
+    method: HTTP.Methods.POST,
+    path: '/',
+    request: {
+      body: jsonContent({
+        schema: CreateUserSchema,
+        description: 'User data',
+      }),
+    },
+    responses: jsonResponse({
+      [HTTP.ResultCodes.RS_2.Created]: UserSchema,
+      [HTTP.ResultCodes.RS_4.BadRequest]: ErrorSchema,
+      [HTTP.ResultCodes.RS_4.Conflict]: ErrorSchema,
+    }),
+  },
+} as const;
+```
+
+## See Also
+
+- [API Usage Examples](../api-usage-examples) - Full API patterns
+- [Controllers Reference](../../references/base/controllers) - Controller API
+- [Swagger Component](../../references/components/swagger) - OpenAPI setup

package/wiki/best-practices/code-style-standards/tooling.md

@@ -0,0 +1,155 @@
+# Tooling Configuration
+
+Ignis provides centralized development configurations via the `@venizia/dev-configs` package.
+
+## Installation
+
+```bash
+bun add -d @venizia/dev-configs
+```
+
+This package provides:
+- **ESLint rules** - Pre-configured for Node.js/TypeScript projects
+- **Prettier settings** - Consistent formatting across all Ignis projects
+- **TypeScript configs** - Shared base and common configurations
+
+## Prettier Configuration
+
+Automatic code formatting eliminates style debates.
+
+**`.prettierrc.mjs`:**
+```javascript
+import { prettierConfigs } from '@venizia/dev-configs';
+
+export default prettierConfigs;
+```
+
+**Default Settings:**
+
+| Setting | Value | Description |
+|---------|-------|-------------|
+| `bracketSpacing` | `true` | `{ foo: bar }` |
+| `singleQuote` | `false` | `"string"` (double quotes) |
+| `printWidth` | `100` | Maximum line length |
+| `trailingComma` | `'all'` | `[1, 2, 3,]` |
+| `arrowParens` | `'avoid'` | `x => x` not `(x) => x` |
+| `semi` | `true` | Semicolons required |
+
+**Customization:**
+```javascript
+import { prettierConfigs } from '@venizia/dev-configs';
+
+export default {
+  ...prettierConfigs,
+  printWidth: 120,  // Override specific settings
+};
+```
+
+**Usage:**
+```bash
+bun run prettier:cli      # Check formatting
+bun run prettier:fix      # Auto-fix
+```
+
+## ESLint Configuration
+
+Prevents common errors and enforces best practices.
+
+**`eslint.config.mjs`:**
+```javascript
+import { eslintConfigs } from '@venizia/dev-configs';
+
+export default eslintConfigs;
+```
+
+**Includes:**
+- Pre-configured rules for Node.js/TypeScript (via `@minimaltech/eslint-node`)
+- Disables `@typescript-eslint/no-explicit-any` by default
+
+**Customization:**
+```javascript
+import { eslintConfigs } from '@venizia/dev-configs';
+
+export default [
+  ...eslintConfigs,
+  {
+    rules: {
+      'no-console': 'warn',  // Add project-specific rules
+    },
+  },
+];
+```
+
+**Usage:**
+```bash
+bun run eslint           # Check for issues
+bun run eslint --fix     # Auto-fix issues
+bun run lint:fix         # Run both ESLint + Prettier
+```
+
+## TypeScript Configuration
+
+Use the centralized TypeScript configs:
+
+**`tsconfig.json`:**
+```json
+{
+  "$schema": "http://json.schemastore.org/tsconfig",
+  "extends": "@venizia/dev-configs/tsconfig.common.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "baseUrl": "src",
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+**What's Included:**
+
+| Option | Value | Purpose |
+|--------|-------|---------|
+| `target` | `ES2022` | Modern JavaScript features |
+| `experimentalDecorators` | `true` | Required for Ignis decorators |
+| `emitDecoratorMetadata` | `true` | Metadata reflection for DI |
+| `strict` | `true` | Strict type checking |
+| `skipLibCheck` | `true` | Faster compilation |
+
+See [`@venizia/dev-configs` documentation](../../references/src-details/dev-configs) for full details.
+
+## IDE Integration
+
+### VS Code
+
+**Recommended Extensions:**
+- ESLint (`dbaeumer.vscode-eslint`)
+- Prettier (`esbenp.prettier-vscode`)
+
+**`.vscode/settings.json`:**
+```json
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "typescript.preferences.importModuleSpecifier": "relative"
+}
+```
+
+### WebStorm / IntelliJ
+
+1. Go to **Settings → Languages & Frameworks → JavaScript → Prettier**
+2. Enable "Run on save"
+3. Go to **Settings → Languages & Frameworks → JavaScript → Code Quality Tools → ESLint**
+4. Select "Automatic ESLint configuration"
+
+## See Also
+
+- [Naming Conventions](./naming-conventions) - File and class naming
+- [Type Safety](./type-safety) - TypeScript best practices
+- [@venizia/dev-configs Reference](../../references/src-details/dev-configs) - Full documentation

package/wiki/best-practices/code-style-standards/type-safety.md

@@ -0,0 +1,165 @@
+# Type Safety
+
+Strict type safety ensures long-term maintainability and catches errors at compile-time.
+
+## 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.
+
+| Type | Problem | Solution |
+|------|---------|----------|
+| `any` | Bypasses all type checking | Use specific types or generics |
+| `unknown` | Forces manual type checking | Use interfaces or type guards |
+
+**Why?**
+- **Maintenance**: Developers reading your code will know exactly what the data structure is
+- **Refactoring**: Changing an interface automatically highlights all broken code
+- **Documentation**: Types act as a self-documenting contract
+
+```typescript
+// ❌ BAD
+const data: any = await fetchData();
+const result: unknown = processData();
+
+// ✅ GOOD
+const data: TUserResponse = await fetchData();
+const result: TProcessResult = processData();
+```
+
+## 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) {
+  // Return type is inferred - can change unexpectedly
+}
+```
+
+## 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>;
+```
+
+### Const Assertion for Literal Types
+
+```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
+export class DefaultCRUDRepository<
+  Schema extends TTableSchemaWithId = TTableSchemaWithId
+> {
+  // Schema is constrained to have an 'id' column
+}
+
+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
+
+## Type Guard Patterns
+
+```typescript
+// Type guard function
+function isUser(obj: unknown): obj is TUser {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    'id' in obj &&
+    'email' in obj
+  );
+}
+
+// Usage
+const data = await fetchData();
+if (isUser(data)) {
+  // data is now typed as TUser
+  console.log(data.email);
+}
+```
+
+## Discriminated Unions
+
+```typescript
+type TResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: string };
+
+function processResult<T>(result: TResult<T>) {
+  if (result.success) {
+    // TypeScript knows result.data exists
+    return result.data;
+  } else {
+    // TypeScript knows result.error exists
+    throw new Error(result.error);
+  }
+}
+```
+
+## See Also
+
+- [Naming Conventions](./naming-conventions) - Type naming prefixes
+- [Function Patterns](./function-patterns) - Typed function signatures
+- [Advanced Patterns](./advanced-patterns) - Generic patterns