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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/ignis-docs",
-  "version": "0.0.4-1",
+  "version": "0.0.4-2",
   "description": "Documentation and MCP Server for Ignis Framework",
   "keywords": [
     "ignis",

package/wiki/best-practices/api-usage-examples.md

@@ -223,6 +223,7 @@ const deleted = await configurationRepository.deleteById({
   id: newRecord.data!.id,
   options: { shouldReturn: true }, // Option to return the deleted record
 });
+```
 
 ## Server-Side Rendering (JSX)
 

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

@@ -0,0 +1,259 @@
+# Advanced Patterns
+
+Advanced TypeScript patterns used throughout the Ignis framework.
+
+## 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
+  }
+}
+```
+
+### Multiple Mixins
+
+```typescript
+class MyRepository extends LoggableMixin(CacheableMixin(BaseRepository)) {
+  // Has both logging and caching capabilities
+}
+```
+
+### Typed Mixin with Constraints
+
+```typescript
+type TWithId = { id: string };
+
+export const TimestampMixin = <
+  BaseClass extends TMixinTarget<TWithId>
+>(baseClass: BaseClass) => {
+  return class extends baseClass {
+    createdAt: Date = new Date();
+    updatedAt: Date = new Date();
+
+    touch(): void {
+      this.updatedAt = new Date();
+    }
+  };
+};
+```
+
+## 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
+        this.defineRoute({
+          configs: { method: 'get', path: '/' },
+          handler: (c) => this.list(c),
+        });
+        this.defineRoute({
+          configs: { method: 'get', path: '/:id' },
+          handler: (c) => this.getById(c),
+        });
+        // ... more routes
+      }
+
+      async list(c: Context) {
+        const data = await this.repository.find({});
+        return c.json(data);
+      }
+
+      async getById(c: Context) {
+        const { id } = c.req.param();
+        const data = await this.repository.findById({ id });
+        return c.json(data);
+      }
+    };
+  }
+}
+
+// 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
+// Type definitions
+export type TResolver<T> = () => T;
+export type TConstructor<T> = new (...args: any[]) => T;
+export type TValueOrResolver<T> = T | TResolver<T> | TConstructor<T>;
+
+// Resolver function
+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
+};
+
+// Helper to detect class constructors
+function isClassConstructor(fn: Function): boolean {
+  return fn.toString().startsWith('class ');
+}
+```
+
+### Usage
+
+```typescript
+interface IOptions {
+  entity: TValueOrResolver<typeof User>;
+}
+
+// All valid:
+const opts1: IOptions = { entity: User };           // Direct class
+const opts2: IOptions = { entity: () => User };     // Resolver function (for lazy loading)
+
+// In consumer code
+const EntityClass = resolveValue(opts.entity);
+const instance = new EntityClass();
+```
+
+### Why Use Value Resolvers?
+
+1. **Circular Dependency Prevention**: Lazy loading via resolver functions breaks cycles
+2. **Lazy Initialization**: Defer expensive imports until needed
+3. **Testing**: Easy to swap implementations via resolvers
+4. **Flexibility**: Single API accepts multiple input types
+
+## Builder Pattern
+
+For constructing complex objects step-by-step:
+
+```typescript
+class QueryBuilder<T> {
+  private _where: Record<string, any> = {};
+  private _orderBy: string[] = [];
+  private _limit?: number;
+  private _offset?: number;
+
+  where(conditions: Record<string, any>): this {
+    this._where = { ...this._where, ...conditions };
+    return this;
+  }
+
+  orderBy(field: string, direction: 'asc' | 'desc' = 'asc'): this {
+    this._orderBy.push(`${field} ${direction.toUpperCase()}`);
+    return this;
+  }
+
+  limit(n: number): this {
+    this._limit = n;
+    return this;
+  }
+
+  offset(n: number): this {
+    this._offset = n;
+    return this;
+  }
+
+  build(): TQueryOptions {
+    return {
+      where: this._where,
+      order: this._orderBy,
+      limit: this._limit,
+      offset: this._offset,
+    };
+  }
+}
+
+// Usage
+const query = new QueryBuilder()
+  .where({ status: 'active' })
+  .orderBy('createdAt', 'desc')
+  .limit(10)
+  .offset(0)
+  .build();
+```
+
+## Registry Pattern
+
+Centralized registration of components:
+
+```typescript
+class StrategyRegistry<T> {
+  private strategies = new Map<string, T>();
+
+  register(name: string, strategy: T): void {
+    if (this.strategies.has(name)) {
+      throw new Error(`Strategy '${name}' already registered`);
+    }
+    this.strategies.set(name, strategy);
+  }
+
+  get(name: string): T {
+    const strategy = this.strategies.get(name);
+    if (!strategy) {
+      throw new Error(`Strategy '${name}' not found`);
+    }
+    return strategy;
+  }
+
+  has(name: string): boolean {
+    return this.strategies.has(name);
+  }
+
+  all(): Map<string, T> {
+    return new Map(this.strategies);
+  }
+}
+
+// Usage
+const authRegistry = new StrategyRegistry<IAuthStrategy>();
+authRegistry.register('jwt', new JWTStrategy());
+authRegistry.register('basic', new BasicStrategy());
+
+const strategy = authRegistry.get('jwt');
+```
+
+## See Also
+
+- [Type Safety](./type-safety) - Generic type patterns
+- [Repositories Reference](../../references/base/repositories/) - Mixin usage
+- [Architectural Patterns](../architectural-patterns) - High-level patterns

package/wiki/best-practices/code-style-standards/constants-configuration.md

@@ -0,0 +1,225 @@
+# Constants & Configuration
+
+Best practices for defining constants and managing configuration.
+
+## Constants Pattern
+
+**Prefer static classes over enums** for better tree-shaking and extensibility.
+
+### Basic Constants
+
+```typescript
+export class Authentication {
+  static readonly STRATEGY_BASIC = 'basic';
+  static readonly STRATEGY_JWT = 'jwt';
+  static readonly TYPE_BEARER = 'Bearer';
+}
+
+export class HealthCheckRestPaths {
+  static readonly ROOT = '/';
+  static readonly PING = '/ping';
+  static readonly METRICS = '/metrics';
+}
+```
+
+### Typed Constants with Validation
+
+For constants that need type extraction and runtime validation, use this pattern:
+
+```typescript
+import { TConstValue } from '@venizia/ignis-helpers';
+
+export class DocumentUITypes {
+  // 1. Define static readonly values
+  static readonly SWAGGER = 'swagger';
+  static readonly SCALAR = 'scalar';
+
+  // 2. Create a Set for O(1) validation lookup
+  static readonly SCHEME_SET = new Set([this.SWAGGER, this.SCALAR]);
+
+  // 3. Validation helper method
+  static isValid(value: string): boolean {
+    return this.SCHEME_SET.has(value);
+  }
+}
+
+// 4. Extract union type from class values
+export type TDocumentUIType = TConstValue<typeof DocumentUITypes>;
+// Result: 'swagger' | 'scalar'
+```
+
+### Full Example with Usage
+
+```typescript
+import { TConstValue } from '@venizia/ignis-helpers';
+
+export class UserStatuses {
+  static readonly ACTIVE = 'active';
+  static readonly INACTIVE = 'inactive';
+  static readonly PENDING = 'pending';
+  static readonly BANNED = 'banned';
+
+  static readonly SCHEME_SET = new Set([
+    this.ACTIVE,
+    this.INACTIVE,
+    this.PENDING,
+    this.BANNED,
+  ]);
+
+  static isValid(value: string): boolean {
+    return this.SCHEME_SET.has(value);
+  }
+
+  // Optional: get all values as array
+  static values(): string[] {
+    return [...this.SCHEME_SET];
+  }
+}
+
+// Type-safe union type
+export type TUserStatus = TConstValue<typeof UserStatuses>;
+// Result: 'active' | 'inactive' | 'pending' | 'banned'
+
+// Usage in interfaces
+interface IUser {
+  id: string;
+  status: TUserStatus; // Type-safe!
+}
+
+// Usage with validation
+function updateUserStatus(userId: string, status: string) {
+  if (!UserStatuses.isValid(status)) {
+    throw getError({
+      statusCode: HTTP.ResultCodes.RS_4.BadRequest,
+      message: `Invalid status: ${status}. Valid: ${UserStatuses.values().join(', ')}`,
+    });
+  }
+  // status is validated at runtime
+}
+```
+
+## Enum vs Static Class Comparison
+
+| Aspect | Static Class | TypeScript Enum |
+|--------|--------------|-----------------|
+| Tree-shaking | Full support | Partial (IIFE blocks it) |
+| Bundle size | Minimal | Larger (IIFE wrapper) |
+| Runtime validation | O(1) with `Set` | O(n) with `Object.values()` |
+| Type extraction | `TConstValue<typeof X>` → values | `keyof typeof X` → keys (not values!) |
+| Add methods | Yes | Not possible |
+| Compiled output | Clean class | IIFE wrapper |
+
+**Compiled JavaScript:**
+
+```typescript
+// Enum compiles to IIFE (not tree-shakable)
+var UserStatus;
+(function (UserStatus) {
+  UserStatus["ACTIVE"] = "active";
+})(UserStatus || (UserStatus = {}));
+
+// Static class compiles cleanly
+class UserStatuses { }
+UserStatuses.ACTIVE = 'active';
+```
+
+**Type Extraction Difference:**
+
+```typescript
+// Enum - extracts KEYS
+type T = keyof typeof UserStatus; // 'ACTIVE' | 'INACTIVE'
+
+// Static Class - extracts VALUES
+type T = TConstValue<typeof UserStatuses>; // 'active' | 'inactive'
+```
+
+**When to use `const enum`:** Only for numeric flags with no iteration needed (values are inlined, zero runtime). But doesn't work with `--isolatedModules`.
+
+**Verdict:** Use Static Class for 90% of cases - better tree-shaking, easy validation, type-safe values, extensible with methods.
+
+## Configuration Patterns
+
+### Default Options
+
+Every configurable class should define `DEFAULT_OPTIONS`:
+
+```typescript
+const DEFAULT_OPTIONS: IHealthCheckOptions = {
+  restOptions: { path: '/health' },
+};
+
+const DEFAULT_SERVER_OPTIONS: Partial<IServerOptions> = {
+  identifier: 'SOCKET_IO_SERVER',
+  path: '/io',
+  cors: {
+    origin: '*',
+    methods: ['GET', 'POST'],
+  },
+};
+```
+
+### Option Merging
+
+```typescript
+// In component constructor or binding
+const extraOptions = this.application.get<Partial<IServerOptions>>({
+  key: BindingKeys.SERVER_OPTIONS,
+  isOptional: true,
+}) ?? {};
+
+this.options = Object.assign({}, DEFAULT_OPTIONS, extraOptions);
+```
+
+### Constructor Validation
+
+Validate required options in the constructor:
+
+```typescript
+constructor(options: IJWTTokenServiceOptions) {
+  super({ scope: JWTTokenService.name });
+
+  if (!options.jwtSecret) {
+    throw getError({
+      statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
+      message: '[JWTTokenService] Invalid jwtSecret',
+    });
+  }
+
+  if (!options.applicationSecret) {
+    throw getError({
+      statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
+      message: '[JWTTokenService] Invalid applicationSecret',
+    });
+  }
+
+  this.options = options;
+}
+```
+
+## Environment Variables Management
+
+Avoid using `process.env` directly in your business logic. Instead, use the `applicationEnvironment` helper and define your keys as constants.
+
+**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);
+```
+
+## See Also
+
+- [Naming Conventions](./naming-conventions) - Constant naming
+- [Type Safety](./type-safety) - Type extraction patterns
+- [Configuration Reference](../../references/configuration/) - Environment variables