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

package/wiki/best-practices/code-style-standards/control-flow.md

@@ -0,0 +1,245 @@
+# Control Flow & Organization
+
+Guidelines for control flow, logging, error handling, and code organization.
+
+## 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
+
+## Logging Patterns
+
+### Method Context Prefix
+
+Always include class and method context in log messages:
+
+```typescript
+// Format: [ClassName][methodName] Message with %s placeholders
+this.logger.info('[binding] Asset storage bound | Key: %s | Type: %s', key, storageType);
+this.logger.debug('[authenticate] Token validated | User: %s', userId);
+this.logger.warn('[register] Skipping duplicate registration | Type: %s', opts.type);
+this.logger.error('[generate] Token generation failed | Error: %s', error.message);
+```
+
+### Structured Data
+
+Use format specifiers for structured logging:
+
+```typescript
+// %s - string, %d - number, %j - JSON object
+this.logger.info('[create] User created | ID: %s | Email: %s', user.id, user.email);
+this.logger.debug('[config] Server options: %j', this.serverOptions);
+```
+
+### Log Levels
+
+| Level | Use For |
+|-------|---------|
+| `error` | Exceptions that need attention |
+| `warn` | Recoverable issues, deprecations |
+| `info` | Important business events |
+| `debug` | Detailed debugging information |
+
+## Standardized Error Handling
+
+Use the `getError` helper and `HTTP` constants to throw consistent, formatted exceptions.
+
+### Basic Error
+
+```typescript
+import { getError, HTTP } from '@venizia/ignis';
+
+if (!record) {
+  throw getError({
+    statusCode: HTTP.ResultCodes.RS_4.NotFound,
+    message: 'Record not found',
+    details: { id: requestedId },
+  });
+}
+```
+
+### Error with Context
+
+Include class/method context in error messages:
+
+```typescript
+// Format: [ClassName][methodName] Descriptive message
+throw getError({
+  statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
+  message: '[JWTTokenService][generate] Failed to generate token',
+});
+
+throw getError({
+  statusCode: HTTP.ResultCodes.RS_4.Unauthorized,
+  message: '[AuthMiddleware][authenticate] Missing authorization header',
+});
+```
+
+### Validation Errors
+
+```typescript
+constructor(options: IServiceOptions) {
+  if (!options.apiKey) {
+    throw getError({
+      statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
+      message: '[PaymentService] Missing required apiKey configuration',
+    });
+  }
+}
+```
+
+### HTTP Status Code Quick Reference
+
+| Category | Constant | Use Case |
+|----------|----------|----------|
+| Success | `HTTP.ResultCodes.RS_2.Ok` | Successful response |
+| Created | `HTTP.ResultCodes.RS_2.Created` | Resource created |
+| Bad Request | `HTTP.ResultCodes.RS_4.BadRequest` | Invalid input |
+| Unauthorized | `HTTP.ResultCodes.RS_4.Unauthorized` | Missing/invalid auth |
+| Forbidden | `HTTP.ResultCodes.RS_4.Forbidden` | Insufficient permissions |
+| Not Found | `HTTP.ResultCodes.RS_4.NotFound` | Resource not found |
+| Internal Error | `HTTP.ResultCodes.RS_5.InternalServerError` | Server errors |
+
+## 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
+
+## See Also
+
+- [Error Handling](../error-handling) - Comprehensive error patterns
+- [Logging Reference](../../references/helpers/logger) - Logger API
+- [Function Patterns](./function-patterns) - Method organization

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

@@ -0,0 +1,221 @@
+# Documentation (JSDoc)
+
+Use JSDoc comments for public APIs to improve IDE support and generate documentation.
+
+## When to Use JSDoc
+
+| Context | Required? | Reason |
+|---------|-----------|--------|
+| Public methods | Yes | Consumers need documentation |
+| Exported functions | Yes | API contract documentation |
+| Complex types | Yes | Clarify usage |
+| Private methods | No | Internal, can change |
+| Self-explanatory code | No | Avoid redundant docs |
+
+## JSDoc Format
+
+```typescript
+/**
+ * Brief description of what the function does.
+ *
+ * @param opts - Description of the options object
+ * @param opts.filter - Query filter with where, limit, offset
+ * @param opts.options - Additional options like transaction
+ * @returns Promise resolving to the query result
+ *
+ * @example
+ * const users = await userRepo.find({
+ *   filter: { where: { status: 'ACTIVE' }, limit: 10 },
+ * });
+ *
+ * @throws {ApplicationError} When validation fails
+ * @see {@link UserService} for business logic
+ */
+async find(opts: TFindOptions): Promise<TFindResult<TUser>> {
+  // implementation
+}
+```
+
+## Common JSDoc Tags
+
+| Tag | Usage |
+|-----|-------|
+| `@param` | Document function parameters |
+| `@returns` | Document return value |
+| `@throws` | Document thrown exceptions |
+| `@example` | Provide usage examples |
+| `@see` | Reference related items |
+| `@deprecated` | Mark as deprecated with migration path |
+| `@internal` | Mark as internal (not public API) |
+| `@since` | Version when feature was added |
+| `@default` | Default value for optional parameter |
+
+## Examples
+
+### Service Method
+
+```typescript
+/**
+ * Creates a new user account with the given data.
+ *
+ * Validates that the email is unique, hashes the password,
+ * and sends a welcome email upon successful creation.
+ *
+ * @param data - User creation data
+ * @returns The created user without sensitive fields
+ * @throws {ApplicationError} 409 if email already exists
+ * @throws {ApplicationError} 422 if validation fails
+ *
+ * @example
+ * const user = await userService.createUser({
+ *   email: 'john@example.com',
+ *   name: 'John Doe',
+ *   password: 'SecurePass123!',
+ * });
+ */
+async createUser(data: TCreateUserRequest): Promise<TUser> {
+  // ...
+}
+```
+
+### Repository Method
+
+```typescript
+/**
+ * Finds entities matching the given filter.
+ *
+ * @param opts - Find options
+ * @param opts.filter - Query filter
+ * @param opts.filter.where - Conditions to match
+ * @param opts.filter.limit - Maximum records to return (default: 100)
+ * @param opts.filter.offset - Records to skip for pagination
+ * @param opts.filter.order - Sort order (e.g., ['createdAt DESC'])
+ * @param opts.filter.include - Relations to load
+ * @returns Promise with data array and count
+ *
+ * @example
+ * // Find active users, sorted by name
+ * const result = await userRepo.find({
+ *   filter: {
+ *     where: { status: 'ACTIVE' },
+ *     order: ['name ASC'],
+ *     limit: 20,
+ *   },
+ * });
+ */
+async find(opts: TFindOpts<Schema>): Promise<TFindResult<TEntity>> {
+  // ...
+}
+```
+
+### Deprecation
+
+```typescript
+/**
+ * @deprecated Use {@link findById} instead. Will be removed in v2.0.
+ *
+ * @example
+ * // Before (deprecated)
+ * const user = await repo.getById('123');
+ *
+ * // After (recommended)
+ * const { data: user } = await repo.findById({ id: '123' });
+ */
+async getById(id: string): Promise<TUser | null> {
+  return this.findById({ id }).then(r => r.data);
+}
+```
+
+### Type Documentation
+
+```typescript
+/**
+ * Options for configuring user audit columns.
+ *
+ * @property dataType - The database type for user IDs ('string' | 'number')
+ * @property columnName - The column name in the database
+ * @property allowAnonymous - Whether to allow null user IDs (default: true)
+ *
+ * @example
+ * const opts: TUserAuditColumnOpts = {
+ *   dataType: 'string',
+ *   columnName: 'created_by',
+ *   allowAnonymous: false,
+ * };
+ */
+type TUserAuditColumnOpts = {
+  dataType: 'string' | 'number';
+  columnName: string;
+  allowAnonymous?: boolean;
+};
+```
+
+### Interface Documentation
+
+```typescript
+/**
+ * Configuration for JWT authentication strategy.
+ *
+ * @interface IJWTStrategyOptions
+ * @property secret - Secret key for signing tokens (required)
+ * @property expiresIn - Token expiration time (default: '1h')
+ * @property algorithm - Signing algorithm (default: 'HS256')
+ * @property issuer - Token issuer claim
+ * @property audience - Token audience claim
+ */
+interface IJWTStrategyOptions {
+  secret: string;
+  expiresIn?: string;
+  algorithm?: 'HS256' | 'HS384' | 'HS512';
+  issuer?: string;
+  audience?: string;
+}
+```
+
+### Class Documentation
+
+```typescript
+/**
+ * Base repository providing CRUD operations for database entities.
+ *
+ * Extends this class to create entity-specific repositories with
+ * type-safe operations and automatic schema binding.
+ *
+ * @template Schema - The Drizzle table schema type
+ *
+ * @example
+ * @repository({ model: User, dataSource: PostgresDataSource })
+ * export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
+ *   // Custom methods here
+ * }
+ *
+ * @see {@link BaseEntity} for model definition
+ * @see {@link BaseDataSource} for database connection
+ */
+abstract class DefaultCRUDRepository<Schema extends TTableSchemaWithId> {
+  // ...
+}
+```
+
+## Best Practices
+
+### Do
+
+- Write descriptions in third person ("Creates...", "Returns...", "Validates...")
+- Include `@example` for non-obvious usage
+- Document all parameters with `@param`
+- Use `@throws` for expected exceptions
+- Link to related items with `@see` and `{@link}`
+
+### Don't
+
+- Don't document obvious things (`@param id - The ID` - unhelpful)
+- Don't copy TypeScript types into JSDoc (they're already visible)
+- Don't write multi-paragraph descriptions for simple functions
+- Don't use JSDoc for private implementation details
+
+## See Also
+
+- [Type Safety](./type-safety) - TypeScript best practices
+- [Function Patterns](./function-patterns) - Method organization
+- [API Reference](../../references/) - Documentation examples

package/wiki/best-practices/code-style-standards/function-patterns.md

@@ -0,0 +1,142 @@
+# Function Patterns
+
+Consistent function patterns improve code readability and maintainability.
+
+## 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 { }
+export function createUser() { }
+export const DEFAULT_OPTIONS = { };
+
+// ❌ BAD
+export default class UserController { }
+```
+
+## 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);
+```
+
+## 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 });
+  }
+}
+```
+
+## 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)
+```
+
+## See Also
+
+- [Naming Conventions](./naming-conventions) - Class and file naming
+- [Type Safety](./type-safety) - Typed function signatures
+- [Route Definitions](./route-definitions) - Controller methods

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

@@ -0,0 +1,110 @@
+# Code Style Standards
+
+Maintain consistent code style using **Prettier** (formatting) and **ESLint** (code quality). Ignis provides centralized configurations via the `@venizia/dev-configs` package.
+
+## Quick Reference
+
+| Aspect | Standard |
+|--------|----------|
+| Interface prefix | `I` (e.g., `IUserService`) |
+| 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*` |
+
+## Sections
+
+| Section | Description |
+|---------|-------------|
+| [Tooling](./tooling) | ESLint, Prettier, TypeScript configuration |
+| [Naming Conventions](./naming-conventions) | Classes, files, types, binding keys |
+| [Type Safety](./type-safety) | Avoiding `any`, explicit returns, generics |
+| [Function Patterns](./function-patterns) | Options object, naming, exports |
+| [Route Definitions](./route-definitions) | Config-driven routes, OpenAPI integration |
+| [Constants & Configuration](./constants-configuration) | Static classes vs enums, defaults |
+| [Control Flow & Organization](./control-flow) | Braces, switches, imports, logging |
+| [Advanced Patterns](./advanced-patterns) | Mixins, factories, value resolvers |
+| [Documentation (JSDoc)](./documentation) | When and how to document code |
+
+## Essential Examples
+
+### Naming
+
+```typescript
+// Interfaces use 'I' prefix
+interface IUserService { }
+
+// Type aliases use 'T' prefix
+type TUserRequest = { };
+
+// Classes use PascalCase with suffix
+class UserController extends BaseController { }
+class UserService extends BaseService { }
+class UserRepository extends BaseRepository { }
+```
+
+### File Structure
+
+```
+src/components/auth/
+├── index.ts              # Barrel exports
+├── component.ts          # IoC binding
+├── controller.ts         # Routes
+└── common/
+    ├── index.ts
+    ├── keys.ts           # Binding keys
+    └── types.ts          # Interfaces
+```
+
+### Constants (Static Class vs Enum)
+
+```typescript
+// ✅ GOOD - Static class (tree-shakable)
+export class UserStatuses {
+  static readonly ACTIVE = 'active';
+  static readonly INACTIVE = 'inactive';
+}
+
+// ❌ AVOID - Enum (not tree-shakable)
+enum UserStatus {
+  ACTIVE = 'active',
+  INACTIVE = 'inactive',
+}
+```
+
+### Import Order
+
+```typescript
+// 1. Node built-ins
+import fs from 'node:fs';
+
+// 2. Third-party
+import { z } from '@hono/zod-openapi';
+
+// 3. Internal absolute
+import { getError } from '@venizia/ignis-helpers';
+
+// 4. Relative (same feature)
+import { QueryBuilder } from './query';
+```
+
+## See Also
+
+- [Architectural Patterns](../architectural-patterns) - High-level design
+- [Common Pitfalls](../common-pitfalls) - Mistakes to avoid
+- [@venizia/dev-configs Reference](../../references/src-details/dev-configs) - Full tooling docs