@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/best-practices/architecture-decisions.md

@@ -1,6 +1,6 @@
 # Architecture Decisions Guide
 
-This guide helps you make informed architectural decisions when building applications with Ignis. Learn when to use different patterns and how to scale your application.
+This guide helps you make informed architectural decisions when building applications with IGNIS. Learn when to use different patterns and how to scale your application.
 
 ## Common Decision Points
 
@@ -24,14 +24,14 @@ This guide helps you make informed architectural decisions when building applica
 export class ItemController extends BaseRestController {
   constructor(
     @inject({ key: 'repositories.ItemRepository' })
-    private itemRepo: ItemRepository,
+    private itemRepository: ItemRepository,
   ) {
     super({ scope: 'ItemController', path: '/items' });
   }
 
-  @get({ configs: { path: '/:id' } })
+  @get({ configs: RouteConfigs.GET_ITEM_BY_ID })
   async getItem(c: Context) {
-    const item = await this.itemRepo.findById(c.req.param('id'));
+    const item = await this.itemRepository.findById({ id: c.req.param('id') });
     return c.json(item);
   }
 }
@@ -56,7 +56,7 @@ export class OrderController extends BaseRestController {
     super({ scope: 'OrderController', path: '/orders' });
   }
 
-  @post({ configs: { path: '/' } })
+  @post({ configs: RouteConfigs.CREATE_ORDER })
   async createOrder(c: Context) {
     const data = await c.req.json();
     // Service handles: validation, inventory check, payment, notifications
@@ -96,22 +96,28 @@ export class OrderController extends BaseRestController {
 
 ```typescript
 // Component: Self-contained, configurable, reusable
-@component({ scope: 'NotificationComponent' })
 export class NotificationComponent extends BaseComponent {
-  private emailService: EmailService;
-  private smsService: SMSService;
-  private pushService: PushService;
-
-  override configure() {
-    // Setup services based on configuration
-    this.emailService = new EmailService(this.config.email);
-    if (this.config.sms?.enabled) {
-      this.smsService = new SMSService(this.config.sms);
-    }
+  constructor(
+    @inject({ key: CoreBindings.APPLICATION_INSTANCE }) private application: BaseApplication,
+  ) {
+    super({
+      scope: NotificationComponent.name,
+      initDefault: { enable: true, container: application },
+      bindings: {
+        // Default configuration - applications can rebind to override
+        'notification.options': Binding.bind({ key: 'notification.options' }).toValue({
+          email: { enabled: true },
+          sms: { enabled: false },
+        }),
+      },
+    });
   }
 
-  async notify(opts: NotifyOptions) {
-    // Unified notification API
+  // Called when the application configures components (registerComponents)
+  override binding(): void {
+    const options = this.application.get({ key: 'notification.options' });
+    // Register notification services based on the resolved options
+    this.application.service(EmailNotificationService);
   }
 }
 ```
@@ -126,7 +132,7 @@ export class NotificationComponent extends BaseComponent {
 // Inline: Simple, one-off, no need for abstraction
 @controller({ path: '/health' })
 export class HealthController extends BaseRestController {
-  @get({ configs: { path: '/' } })
+  @get({ configs: RouteConfigs.HEALTH_CHECK })
   healthCheck(c: Context) {
     return c.json({ status: 'ok', timestamp: new Date() });
   }
@@ -146,17 +152,19 @@ export class HealthController extends BaseRestController {
 
 ### Start with Standard CRUD
 
-Every repository gets these methods from `BaseRepository`:
+Every repository gets these methods from `DefaultCRUDRepository`:
 
 ```typescript
-// Inherited methods - use these first
-find(filter)      // List with filters
-findById(id)      // Get by ID
-findOne(filter)   // Get first match
-create(data)      // Create new
-updateById(id, data)  // Update existing
-deleteById(id)    // Delete
-count(filter)     // Count matches
+// Inherited methods (options-object API) - use these first
+find({ filter })            // List with filters
+findById({ id })            // Get by ID
+findOne({ filter })         // Get first match
+create({ data })            // Create new
+updateById({ id, data })    // Update existing
+updateAll({ data, where })  // Bulk update (updateBy is an alias)
+deleteById({ id })          // Delete
+deleteAll({ where })        // Bulk delete (deleteBy is an alias)
+count({ where })            // Count matches
 ```
 
 ### Add Custom Methods When:
@@ -167,22 +175,24 @@ count(filter)     // Count matches
 
 ```typescript
 // Custom repository methods
-export class OrderRepository extends BaseRepository<Order> {
+export class OrderRepository extends DefaultCRUDRepository<typeof Order.schema> {
   // Complex query that's used in multiple places
   async findPendingOrdersOlderThan(hours: number) {
     const cutoff = new Date(Date.now() - hours * 60 * 60 * 1000);
     return this.find({
-      where: {
-        status: 'pending',
-        createdAt: { lt: cutoff },
+      filter: {
+        where: {
+          status: 'pending',
+          createdAt: { lt: cutoff },
+        },
+        order: ['createdAt ASC'],
       },
-      orderBy: { createdAt: 'asc' },
     });
   }
 
-  // Performance-optimized query
+  // Performance-optimized query (raw SQL through the Drizzle connector)
   async getOrderStats(userId: string) {
-    return this.db.execute(sql`
+    return this.dataSource.connector.execute(sql`
       SELECT
         COUNT(*) as total,
         SUM(total) as revenue,
@@ -194,9 +204,12 @@ export class OrderRepository extends BaseRepository<Order> {
 
   // Business logic at data layer
   async softDelete(id: string) {
-    return this.updateById(id, {
-      deletedAt: new Date(),
-      status: 'deleted',
+    return this.updateById({
+      id,
+      data: {
+        deletedAt: new Date(),
+        status: 'deleted',
+      },
     });
   }
 }
@@ -210,15 +223,15 @@ export class OrderRepository extends BaseRepository<Order> {
 ```typescript
 @controller({ path: '/users' })
 export class UserController extends BaseRestController {
-  @post({ configs: { path: '/' } })
+  @post({ configs: RouteConfigs.CREATE_USER })
   async createUser(c: Context) {
     try {
       const data = await c.req.json();
       const user = await this.userService.create(data);
       return c.json(user, 201);
     } catch (error) {
-      // Format error for API response
-      if (error.code === 'DUPLICATE_EMAIL') {
+      // Format error for API response -- messageCode is always lower-cased by ApplicationError
+      if (error instanceof ApplicationError && error.messageCode === 'app.user.duplicate_email') {
         return c.json({ error: 'Email already exists' }, 400);
       }
       throw error; // Let global handler catch unknown errors
@@ -230,23 +243,29 @@ export class UserController extends BaseRestController {
 ### Service Level: Throw Domain Errors
 
 ```typescript
-@injectable()
 export class UserService extends BaseService {
+  constructor(
+    @inject({ key: 'repositories.UserRepository' })
+    private userRepository: UserRepository,
+  ) {
+    super({ scope: UserService.name });
+  }
+
   async create(data: CreateUserInput) {
     // Validate and throw domain-specific errors
-    const existing = await this.userRepo.findByEmail(data.email);
+    const existing = await this.userRepository.findByEmail(data.email);
     if (existing) {
       throw getError({
         statusCode: 400,
-        code: 'DUPLICATE_EMAIL',
+        messageCode: MessageCode.build({ parts: ['app', 'user', 'duplicate_email'] }),
         message: 'User with this email already exists',
       });
     }
 
     // Log operations
-    this.logger.info('Creating user', { email: data.email });
+    this.logger.info('Creating user | email: %s', data.email);
 
-    return this.userRepo.create(data);
+    return this.userRepository.create({ data });
   }
 }
 ```
@@ -254,11 +273,11 @@ export class UserService extends BaseService {
 ### Repository Level: Let Errors Bubble
 
 ```typescript
-export class UserRepository extends BaseRepository<User> {
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
   // Don't catch database errors here
   // Let them bubble up to service/controller
   async findByEmail(email: string) {
-    return this.findOne({ where: { email } });
+    return this.findOne({ filter: { where: { email } } });
   }
 }
 ```
@@ -356,25 +375,27 @@ OrderStatusRepository  // Probably doesn't need its own repo
 
 ```typescript
 // Use repository methods for most cases
-const orders = await orderRepo.find({ where: { userId } });
+const orders = await orderRepository.find({ filter: { where: { userId } } });
+
+// Use raw queries (via the datasource's Drizzle connector) for:
+const connector = this.dataSource.connector;
 
-// Use raw queries for:
 // 1. Complex aggregations
-const stats = await db.execute(sql`
+const stats = await connector.execute(sql`
   SELECT category, COUNT(*), AVG(price)
   FROM products
   GROUP BY category
 `);
 
 // 2. Performance-critical paths
-const results = await db.execute(sql`
+const results = await connector.execute(sql`
   SELECT * FROM products
   WHERE tsv @@ plainto_tsquery(${search})
   LIMIT 10
 `);
 
 // 3. Database-specific features
-const nearby = await db.execute(sql`
+const nearby = await connector.execute(sql`
   SELECT * FROM stores
   WHERE ST_DWithin(location, ${point}, 5000)
 `);
@@ -386,14 +407,16 @@ const nearby = await db.execute(sql`
 ### Environment Variables
 
 ```typescript
+import { applicationEnvironment } from '@venizia/ignis-helpers';
+
 // Use for: secrets, environment-specific values
 const config = {
   database: {
-    host: EnvHelper.get('APP_ENV_POSTGRES_HOST'),
-    password: EnvHelper.get('APP_ENV_POSTGRES_PASSWORD'),
+    host: applicationEnvironment.get<string>('APP_ENV_POSTGRES_HOST'),
+    password: applicationEnvironment.get<string>('APP_ENV_POSTGRES_PASSWORD'),
   },
   stripe: {
-    secretKey: EnvHelper.get('STRIPE_SECRET_KEY'),
+    secretKey: applicationEnvironment.get<string>('APP_ENV_STRIPE_SECRET_KEY'),
   },
 };
 ```
@@ -417,11 +440,19 @@ const appConfig = {
 
 ```typescript
 // Use for: component-specific settings
-this.component(SwaggerComponent, {
-  title: 'My API',
-  version: '1.0.0',
-  path: '/doc',
+// Components read their options from bindings - rebind before registering
+this.bind<IApiReferenceOptions>({ key: ApiReferenceBindingKeys.API_REFERENCE_OPTIONS }).toValue({
+  restOptions: {
+    base: { path: '/doc' },
+    doc: { path: '/openapi.json' },
+    ui: { path: '/explorer', type: 'swagger' },
+  },
+  explorer: {
+    openapi: '3.1.0',
+    info: { title: 'My API', version: '1.0.0', description: 'My API documentation' },
+  },
 });
+this.component(ApiReferenceComponent);
 ```
 
 

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

@@ -1,19 +1,19 @@
 # Advanced Patterns
 
-Advanced TypeScript patterns used throughout the Ignis framework.
+Advanced TypeScript patterns used throughout the IGNIS framework.
 
 ## Mixin Pattern
 
 Create reusable class extensions without deep inheritance:
 
 ```typescript
-import { TMixinTarget } from '@venizia/ignis-helpers';
+import { LoggerFactory, TMixinTarget } from '@venizia/ignis-helpers';
 
-export const LoggableMixin = <BaseClass extends TMixinTarget<Base>>(
+export const LoggableMixin = <BaseClass extends TMixinTarget<object>>(
   baseClass: BaseClass,
 ) => {
   return class extends baseClass {
-    protected logger = LoggerFactory.getLogger(this.constructor.name);
+    protected logger = LoggerFactory.getLogger([this.constructor.name]);
 
     log(message: string): void {
       this.logger.info(message);
@@ -32,7 +32,7 @@ class MyService extends LoggableMixin(BaseService) {
 ### Multiple Mixins
 
 ```typescript
-class MyRepository extends LoggableMixin(CacheableMixin(BaseRepository)) {
+class MyService extends LoggableMixin(CacheableMixin(BaseService)) {
   // Has both logging and caching capabilities
 }
 ```
@@ -61,46 +61,51 @@ export const TimestampMixin = <
 Generate classes dynamically with configuration:
 
 ```typescript
-class ControllerFactory {
-  static defineCrudController<Schema extends TTableSchemaWithId>(
-    opts: ICrudControllerOptions<Schema>,
-  ) {
+class ControllerFactory extends BaseHelper {
+  /** `TDataObject`/`TPersistObject` cannot be inferred from `entity` -
+   * pass them explicitly for typed CRUD handlers. */
+  static defineCrudController<
+    TDataObject extends object = object,
+    TPersistObject extends object = TDataObject,
+  >(defOpts: ICrudControllerOptions) {
+    const { controller, entity } = defOpts;
+
+    // `entity` accepts a class directly or a resolver function
+    const entityClass = isClass(entity) ? entity : entity();
+    const entityInstance = new entityClass();
+
+    // Derive request/response schemas + route configs from the entity instance
+    const routeDefinitions = buildRouteDefinitions({ entity: entityInstance });
+
     return class extends BaseRestController {
-      constructor(repository: AbstractRepository<Schema>) {
-        super({ scope: opts.controller.name });
+      repository: AbstractRepository<TDataObject, TPersistObject>;
+
+      constructor(repository: AbstractRepository<TDataObject, TPersistObject>) {
+        super({ scope: controller.name, path: controller.basePath });
         this.repository = repository;
-        this.setupRoutes();
       }
 
-      private setupRoutes(): void {
-        // Dynamically bind CRUD routes
+      /** Registers all CRUD route handlers. */
+      override binding(): ValueOrPromise<void> {
         this.defineRoute({
-          configs: { method: 'get', path: '/' },
-          handler: (c) => this.list(c),
+          configs: routeDefinitions.FIND,
+          handler: async context => this.find({ context }),
         });
         this.defineRoute({
-          configs: { method: 'get', path: '/:id' },
-          handler: (c) => this.getById(c),
+          configs: routeDefinitions.FIND_BY_ID,
+          handler: async context => this.findById({ context }),
         });
-        // ... 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);
+        // ... more routes (count/findOne/create/updateById/deleteById/...)
       }
     };
   }
 }
 
-// Usage
-const UserCrudController = ControllerFactory.defineCrudController({
+// Usage - type parameters are explicit, entity can be a class or a resolver
+type TUser = typeof User.schema.$inferSelect;
+type TNewUser = typeof User.schema.$inferInsert;
+
+const UserCrudController = ControllerFactory.defineCrudController<TUser, TNewUser>({
   controller: { name: 'UserController', basePath: '/users' },
   repository: { name: UserRepository.name },
   entity: () => User,
@@ -117,26 +122,33 @@ export class UserController extends UserCrudController {
 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>;
+// Type definitions (from @venizia/ignis-helpers)
+export type TResolver<T> = (...args: any[]) => T;
+export type TValueOrResolver<T> = T | TResolver<T>;
 
 // Resolver function
 export const resolveValue = <T>(valueOrResolver: TValueOrResolver<T>): T => {
   if (typeof valueOrResolver !== 'function') {
     return valueOrResolver;  // Direct value
   }
-  if (isClassConstructor(valueOrResolver)) {
+
+  if (isClass(valueOrResolver as Function)) {
     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 ');
-}
+// isClass (from @venizia/ignis-inversion, re-exported by helpers) - distinguishes class
+// constructors from arrow/regular functions by testing the SOURCE against /^class[\s{]/,
+// since every non-arrow function has a prototype
+export const isClass = <T>(target: any): target is TClass<T> => {
+  if (typeof target !== 'function' || target.prototype === undefined) {
+    return false;
+  }
+
+  return /^class[\s{]/.test(Function.prototype.toString.call(target));
+};
 ```
 
 ### Usage
@@ -222,7 +234,7 @@ class StrategyRegistry<T> {
 
   register(name: string, strategy: T): void {
     if (this.strategies.has(name)) {
-      throw new Error(`Strategy '${name}' already registered`);
+      throw getError({ message: `[register] Strategy '${name}' already registered` });
     }
     this.strategies.set(name, strategy);
   }
@@ -230,7 +242,7 @@ class StrategyRegistry<T> {
   get(name: string): T {
     const strategy = this.strategies.get(name);
     if (!strategy) {
-      throw new Error(`Strategy '${name}' not found`);
+      throw getError({ message: `[get] Strategy '${name}' not found` });
     }
     return strategy;
   }
@@ -255,5 +267,5 @@ const strategy = authRegistry.get('jwt');
 ## See Also
 
 - [Type Safety](./type-safety) - Generic type patterns
-- [Repositories Reference](../../references/base/repositories/) - Mixin usage
+- [Repositories Reference](../../references/base/repositories/) - Repository hierarchy
 - [Architectural Patterns](../architectural-patterns) - High-level patterns

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

@@ -18,7 +18,6 @@ export class Authentication {
 export class HealthCheckRestPaths {
   static readonly ROOT = '/';
   static readonly PING = '/ping';
-  static readonly METRICS = '/metrics';
 }
 ```
 
@@ -162,12 +161,13 @@ const DEFAULT_SERVER_OPTIONS: Partial<IServerOptions> = {
 
 ```typescript
 // In component constructor or binding
-const extraOptions = this.application.get<Partial<IServerOptions>>({
-  key: BindingKeys.SERVER_OPTIONS,
-  isOptional: true,
-}) ?? {};
+const extraServerOptions =
+  this.application.get<Partial<ServerOptions>>({
+    key: SocketIOBindingKeys.SERVER_OPTIONS,
+    isOptional: true,
+  }) ?? {};
 
-this.options = Object.assign({}, DEFAULT_OPTIONS, extraOptions);
+this.serverOptions = Object.assign({}, DEFAULT_SERVER_OPTIONS, extraServerOptions);
 ```
 
 ### Constructor Validation
@@ -175,20 +175,20 @@ this.options = Object.assign({}, DEFAULT_OPTIONS, extraOptions);
 Validate required options in the constructor:
 
 ```typescript
-constructor(options: IJWTTokenServiceOptions) {
-  super({ scope: JWTTokenService.name });
+constructor(options: IJWSTokenServiceOptions) {
+  super({ scope: JWSTokenService.name });
 
   if (!options.jwtSecret) {
     throw getError({
       statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
-      message: '[JWTTokenService] Invalid jwtSecret',
+      message: '[JWSTokenService] Invalid jwtSecret',
     });
   }
 
-  if (!options.applicationSecret) {
+  if (!options.getTokenExpiresFn) {
     throw getError({
       statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
-      message: '[JWTTokenService] Invalid applicationSecret',
+      message: '[JWSTokenService] Invalid getTokenExpiresFn',
     });
   }
 

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

@@ -107,6 +107,9 @@ this.logger.info('[create] User created | ID: %s | Email: %s', user.id, user.ema
 this.logger.debug('[config] Server options: %j', this.serverOptions);
 ```
 
+> [!NOTE]
+> `%j` on an `Error` instance drops `message` and `stack` -- they are non-enumerable, so `JSON.stringify` never sees them. Use `%s` for errors, `%j`/`%o` for plain data objects. An object passed to `%s` is inspected up to `APP_ENV_LOGGER_INSPECT_DEPTH` levels deep (default `5`) instead of Node's hard-coded `depth: 0`, so nested fields print instead of collapsing to `[Object]`. See [Logger Helper](/extensions/helpers/logger/) for details.
+
 ### Log Levels
 
 | Level | Use For |
@@ -142,7 +145,7 @@ Include class/method context in error messages:
 // Format: [ClassName][methodName] Descriptive message
 throw getError({
   statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
-  message: '[JWTTokenService][generate] Failed to generate token',
+  message: '[JWSTokenService][generate] Failed to generate token',
 });
 
 throw getError({
@@ -224,7 +227,7 @@ import dayjs from 'dayjs';
 
 // 3. Internal absolute imports (by domain/package)
 import { getError } from '@venizia/ignis-helpers';
-import { BaseEntity } from '@/base/models';
+import { AbstractEntity } from '@/base/models';
 import { UserService } from '@/services';
 
 // 4. Relative imports (same feature) - LAST

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

@@ -24,14 +24,14 @@ Use JSDoc comments for public APIs to improve IDE support and generate documenta
  * @returns Promise resolving to the query result
  *
  * @example
- * const users = await userRepo.find({
+ * const users = await userRepository.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>> {
+async find(opts: { filter: TFilter<TUser>; options?: IExtraOptions }): Promise<TUser[]> {
   // implementation
 }
 ```
@@ -87,15 +87,15 @@ async createUser(data: TCreateUserRequest): Promise<TUser> {
  * @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.limit - Maximum records to return
  * @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
+ * @returns Promise resolving to the array of matching entities
  *
  * @example
  * // Find active users, sorted by name
- * const result = await userRepo.find({
+ * const users = await userRepository.find({
  *   filter: {
  *     where: { status: 'ACTIVE' },
  *     order: ['name ASC'],
@@ -103,7 +103,7 @@ async createUser(data: TCreateUserRequest): Promise<TUser> {
  *   },
  * });
  */
-async find(opts: TFindOpts<Schema>): Promise<TFindResult<TEntity>> {
+async find<R = TUser>(opts: { filter: TFilter<TUser>; options?: IExtraOptions }): Promise<R[]> {
   // ...
 }
 ```
@@ -116,13 +116,13 @@ async find(opts: TFindOpts<Schema>): Promise<TFindResult<TEntity>> {
  *
  * @example
  * // Before (deprecated)
- * const user = await repo.getById('123');
+ * const user = await userRepository.getById('123');
  *
  * // After (recommended)
- * const { data: user } = await repo.findById({ id: '123' });
+ * const user = await userRepository.findById({ id: '123' });
  */
 async getById(id: string): Promise<TUser | null> {
-  return this.findById({ id }).then(r => r.data);
+  return this.findById({ id });
 }
 ```
 
@@ -181,7 +181,7 @@ interface IJWTStrategyOptions {
  * Extends this class to create entity-specific repositories with
  * type-safe operations and automatic schema binding.
  *
- * @template Schema - The Drizzle table schema type
+ * @template EntitySchema - The Drizzle table schema type
  *
  * @example
  * @repository({ model: User, dataSource: PostgresDataSource })
@@ -189,10 +189,10 @@ interface IJWTStrategyOptions {
  *   // Custom methods here
  * }
  *
- * @see {@link BaseEntity} for model definition
- * @see {@link BaseDataSource} for database connection
+ * @see {@link BasePostgresEntity} for model definition
+ * @see {@link BasePostgresDataSource} for database connection
  */
-abstract class DefaultCRUDRepository<Schema extends TTableSchemaWithId> {
+class DefaultCRUDRepository<EntitySchema extends TTableSchemaWithId = TTableSchemaWithId> {
   // ...
 }
 ```