@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/best-practices/data-modeling.md

@@ -1,21 +1,24 @@
 # Data Modeling
 
-Ignis streamlines data modeling with Drizzle ORM by providing powerful helpers and "enrichers" that reduce boilerplate code for common schema patterns.
+IGNIS streamlines data modeling with Drizzle ORM by providing powerful helpers and "enrichers" that reduce boilerplate code for common schema patterns.
+
+> [!NOTE] Scope: PostgreSQL connector
+> This page covers Drizzle-backed models (`BasePostgresEntity`; the legacy `BaseEntity` export is a compatibility alias for the same class) and enrichers, which are specific to relational tables. Search documents (typesense connector) use `defineSearchCollection` instead - see [Search & Typesense](/guides/core-concepts/persistent/search-typesense). See [Connectors](/references/base/connectors) for how the engine-neutral `AbstractEntity` relates to each connector's concrete entity class.
 
 ## 1. Base Entity
 
-All entity models should extend `BaseEntity`. This provides integration with the framework's repository layer and automatic schema generation support.
+All PostgreSQL entity models should extend `BasePostgresEntity`. This provides integration with the framework's repository layer and automatic schema generation support.
 
 The recommended pattern is to define the schema and relations as **static properties** on the class. This keeps the definition self-contained and enables powerful type inference.
 
 **Example (`src/models/entities/user.model.ts`):**
 
 ```typescript
-import { BaseEntity, extraUserColumns, generateIdColumnDefs, model } from '@venizia/ignis';
+import { BasePostgresEntity, extraUserColumns, generateIdColumnDefs, model } from '@venizia/ignis';
 import { pgTable } from 'drizzle-orm/pg-core';
 
 @model({ type: 'entity' })
-export class User extends BaseEntity<typeof User.schema> {
+export class User extends BasePostgresEntity<typeof User.schema> {
   // 1. Define schema as a static property
   static override schema = pgTable('User', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
@@ -29,7 +32,7 @@ export class User extends BaseEntity<typeof User.schema> {
 
 ## 2. Schema Enrichers
 
-Instead of manually defining common columns like primary keys, timestamps, or audit fields in every table, use Ignis "enrichers".
+Instead of manually defining common columns like primary keys, timestamps, or audit fields in every table, use IGNIS "enrichers".
 
 **Available Enrichers:**
 
@@ -50,7 +53,7 @@ import {
   generateTzColumnDefs,
   generateUserAuditColumnDefs,
 } from '@venizia/ignis';
-import { pgTable, text } from 'drizzle-orm/pg-core';
+import { pgTable, text, unique } from 'drizzle-orm/pg-core';
 
 export const configurationTable = pgTable(
   'Configuration',
@@ -151,7 +154,7 @@ export const commentTable = pgTable('Comment', {
 **Querying polymorphic relations:**
 ```typescript
 // Find all comments on a specific post
-const comments = await commentRepo.find({
+const comments = await commentRepository.find({
   filter: {
     where: {
       commentableType: 'Post',
@@ -161,7 +164,7 @@ const comments = await commentRepo.find({
 });
 
 // Find all comments on a product
-const productComments = await commentRepo.find({
+const productComments = await commentRepository.find({
   filter: {
     where: {
       commentableType: 'Product',
@@ -186,11 +189,11 @@ Relations are defined using the `TRelationConfig` structure within the static `r
 
 **One-to-One (belongsTo):**
 ```typescript
-import { BaseEntity, model, RelationTypes, TRelationConfig } from '@venizia/ignis';
+import { BasePostgresEntity, model, RelationTypes, TRelationConfig } from '@venizia/ignis';
 import { User } from './user.model';
 
 @model({ type: 'entity' })
-export class Configuration extends BaseEntity<typeof Configuration.schema> {
+export class Configuration extends BasePostgresEntity<typeof Configuration.schema> {
   static override schema = pgTable('Configuration', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
     createdBy: text('created_by'),
@@ -215,7 +218,7 @@ export class Configuration extends BaseEntity<typeof Configuration.schema> {
 **One-to-Many (hasMany):**
 ```typescript
 @model({ type: 'entity' })
-export class User extends BaseEntity<typeof User.schema> {
+export class User extends BasePostgresEntity<typeof User.schema> {
   static override schema = pgTable('User', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
     name: text('name').notNull(),
@@ -248,7 +251,7 @@ export class User extends BaseEntity<typeof User.schema> {
 
 ```typescript
 // Eager load single relation
-const configs = await configRepo.find({
+const configs = await configurationRepository.find({
   filter: {
     include: [{ relation: 'creator' }],
   },
@@ -256,7 +259,7 @@ const configs = await configRepo.find({
 // Result: [{ id, code, ..., creator: { id, name, email } }]
 
 // Eager load multiple relations
-const users = await userRepo.find({
+const users = await userRepository.find({
   filter: {
     include: [
       { relation: 'posts' },
@@ -266,7 +269,7 @@ const users = await userRepo.find({
 });
 
 // Nested relations (up to 2 levels recommended)
-const users = await userRepo.find({
+const users = await userRepository.find({
   filter: {
     include: [{
       relation: 'posts',
@@ -283,7 +286,7 @@ const users = await userRepo.find({
 
 ## 4. Repositories and Auto-Discovery
 
-Ignis simplifies the connection between models, repositories, and datasources.
+IGNIS simplifies the connection between models, repositories, and datasources.
 
 ### DataSource Auto-Discovery
 
@@ -291,8 +294,21 @@ DataSources automatically discover their schema from the repositories that bind
 
 ```typescript
 // src/datasources/postgres.datasource.ts
-@datasource({ driver: 'node-postgres' })
-export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+import { datasource, ValueOrPromise } from '@venizia/ignis';
+import { BasePostgresDataSource } from '@venizia/ignis/postgres';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
+import { Pool } from 'pg';
+
+interface IDataSourceConfigs {
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  password: string;
+}
+
+@datasource({ driver: NodePostgresDriver })
+export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
@@ -302,9 +318,17 @@ export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, I
   }
 
   override configure(): ValueOrPromise<void> {
-    // This method automatically collects all schemas from bound repositories
-    const schema = this.getSchema();
-    this.connector = drizzle({ client: new Pool(this.settings), schema });
+    // getSchema() automatically collects all schemas from bound repositories
+    this.logger.debug('[configure] Auto-discovered schema | Keys: %o', Object.keys(this.getSchema()));
+
+    // Keep the pool on this.client - naming NodePostgresDriver above is what wires the driver
+    // and Drizzle connector; beginTransaction() resolves its driver from this.client lazily.
+    this.client = new Pool(this.settings);
+  }
+
+  override getConnectionString(): ValueOrPromise<string> {
+    const { host, port, user, password, database } = this.settings;
+    return `postgresql://${user}:${password}@${host}:${port}/${database}`;
   }
 }
 ```
@@ -356,7 +380,7 @@ Protect sensitive data by configuring properties that are excluded at the SQL le
     hiddenProperties: ['password', 'secret'],
   },
 })
-export class User extends BaseEntity<typeof User.schema> {
+export class User extends BasePostgresEntity<typeof User.schema> {
   static override schema = pgTable('User', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
     email: text('email').notNull(),
@@ -387,7 +411,7 @@ Declare your model's authorization principal in `@model` settings to make the mo
     hiddenProperties: ['password'],
   },
 })
-export class User extends BaseEntity<typeof User.schema> {
+export class User extends BasePostgresEntity<typeof User.schema> {
   static override schema = pgTable('User', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
     email: text('email').notNull(),

package/content/best-practices/deployment-strategies.md

@@ -1,6 +1,6 @@
 # Deployment Strategies
 
-Deploy your Ignis application reliably, securely, and efficiently.
+Deploy your IGNIS application reliably, securely, and efficiently.
 
 ## 1. Building for Production
 
@@ -46,7 +46,7 @@ FROM oven/bun:1-slim
 WORKDIR /usr/src/app
 
 # Copy dependency files
-COPY package.json bun.lockb ./
+COPY package.json bun.lock ./
 
 # Install production dependencies
 RUN bun install --production --frozen-lockfile
@@ -109,7 +109,7 @@ services:
         condition: service_started
     restart: unless-stopped
     healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:3000/health-check"]
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
       interval: 30s
       timeout: 10s
       retries: 3
@@ -188,7 +188,7 @@ scp dist/my-app .env user@server:/app/
 ```ini
 # /etc/systemd/system/my-app.service
 [Unit]
-Description=My Ignis Application
+Description=My IGNIS Application
 After=network.target
 
 [Service]
@@ -225,7 +225,7 @@ Add health check endpoint for load balancers:
 this.component(HealthCheckComponent);
 ```
 
-Access at `/health-check` for liveness/readiness probes.
+Access at `/health` (default path, configurable) for liveness/readiness probes.
 
 ## 5. Build Debugging
 
@@ -273,30 +273,30 @@ Total time:        8.47s
 
 ### Force Update Strategy
 
-Keep dependencies in sync with the NPM registry using the force-update script:
+Keep dependencies in sync with the NPM registry using each package's force-update script (`packages/<name>/scripts/force-update.sh`, exposed as the `force-update` script in that package):
 
 ```bash
-# Update to latest stable versions
-./scripts/force-update.sh latest
+# Update to latest stable versions (from a package directory)
+bun run force-update latest
 
 # Update to pre-release versions (for testing new features)
-./scripts/force-update.sh next
+bun run force-update next
 ```
 
 **What it does:**
-1. Queries NPM registry for the specified tag (`latest` or `next`)
-2. Updates `package.json` with exact versions
-3. Applies to all `@venizia/*` packages
+1. Queries NPM registry for the specified tag (`latest`, `next`, or `highest`)
+2. Updates the package's `@venizia/*` dependencies in `package.json` with exact versions
 
 **When to use:**
 | Tag | Use Case |
 |-----|----------|
 | `latest` | Production deployments, stable releases |
 | `next` | Testing new features, pre-release validation |
+| `highest` | Highest released version by semver sort |
 
-**Makefile shortcuts:**
+**Makefile shortcuts (repo root):**
 ```bash
-make update           # Force update all packages (latest)
+make update           # Reinstall deps (postinstall runs force-update)
 make update-core      # Update only @venizia/ignis
 make update-helpers   # Update only @venizia/ignis-helpers
 ```
@@ -447,7 +447,7 @@ Railway provides simple deployments with automatic builds:
   },
   "deploy": {
     "startCommand": "bun run server:prod",
-    "healthcheckPath": "/health-check",
+    "healthcheckPath": "/health",
     "healthcheckTimeout": 30,
     "restartPolicyType": "ON_FAILURE",
     "restartPolicyMaxRetries": 3
@@ -495,7 +495,7 @@ primary_region = "sjc"
     interval = 10000
     grace_period = "5s"
     method = "get"
-    path = "/health-check"
+    path = "/health"
     protocol = "http"
     timeout = 2000
 ```
@@ -524,7 +524,7 @@ services:
         generateValue: true
       - key: APP_ENV_JWT_SECRET
         generateValue: true
-    healthCheckPath: /health-check
+    healthCheckPath: /health
     autoDeploy: true
 
 databases:
@@ -579,13 +579,13 @@ spec:
                   key: db-host
           livenessProbe:
             httpGet:
-              path: /health-check
+              path: /health
               port: 3000
             initialDelaySeconds: 10
             periodSeconds: 30
           readinessProbe:
             httpGet:
-              path: /health-check
+              path: /health
               port: 3000
             initialDelaySeconds: 5
             periodSeconds: 10
@@ -634,7 +634,7 @@ kubectl logs -l app=ignis -f
 
 ### Health Check Endpoints
 
-Ignis provides built-in health checks:
+IGNIS provides built-in health checks:
 
 ```typescript
 // In application.ts
@@ -643,9 +643,9 @@ import { HealthCheckComponent } from '@venizia/ignis';
 this.component(HealthCheckComponent);
 ```
 
-**Endpoints:**
-- `GET /health-check` - Basic liveness check
-- `GET /health-check/ready` - Readiness (includes DB connection)
+**Endpoints (default path `/health`, configurable via component options):**
+- `GET /health` - Basic liveness check
+- `POST /health/ping` - Echo/ping check (send `{ "message": "..." }`, get a PONG back)
 
 ### Logging in Production
 
@@ -654,11 +654,12 @@ Configure structured logging:
 ```typescript
 import { LoggerFactory } from '@venizia/ignis-helpers';
 
-// Set log level via environment
-// APP_ENV_LOG_LEVEL=info (debug, info, warn, error)
+// Debug-level logs are gated by the DEBUG environment variable (DEBUG=true)
+// and the current NODE_ENV. File output is configured via APP_ENV_LOGGER_*
+// variables (e.g. APP_ENV_LOGGER_FOLDER_PATH, APP_ENV_LOGGER_FORMAT).
 
 const logger = LoggerFactory.getLogger(['MyService']);
-logger.info('Service started', { port: 3000, env: 'production' });
+logger.info('Service started | port: %d | env: %s', 3000, 'production');
 ```
 
 ### Metrics Collection
@@ -669,7 +670,7 @@ Add Prometheus metrics endpoint:
 // src/controllers/metrics.controller.ts
 @controller({ path: '/metrics' })
 export class MetricsController extends BaseRestController {
-  @get({ configs: { path: '/' } })
+  @get({ configs: { path: '/', responses: { 200: { description: 'Prometheus metrics' } } } })
   getMetrics(c: Context) {
     return c.text(`
 # HELP http_requests_total Total HTTP requests

package/content/best-practices/error-handling.md

@@ -1,6 +1,6 @@
 # Error Handling
 
-Comprehensive guide to handling errors gracefully in Ignis applications.
+Comprehensive guide to handling errors gracefully in IGNIS applications.
 
 ## Error Handling Philosophy
 
@@ -13,7 +13,7 @@ Comprehensive guide to handling errors gracefully in Ignis applications.
 
 ## 1. Using `getError` Helper
 
-Ignis provides `getError` for creating consistent, structured errors.
+IGNIS provides `getError` for creating consistent, structured errors.
 
 ```typescript
 import { getError, HTTP } from '@venizia/ignis-helpers';
@@ -52,7 +52,7 @@ Use the correct status code for each error type:
 | 401 | `RS_4.Unauthorized` | Missing or invalid authentication |
 | 403 | `RS_4.Forbidden` | Authenticated but insufficient permissions |
 | 404 | `RS_4.NotFound` | Resource does not exist |
-| 409 | `RS_4.Conflict` | Resource already exists (custom duplicate handling) |
+| 409 | `RS_4.Conflict` | Resource already exists (custom duplicate handling); transient DB conflicts (deadlock / serialization failure, auto-handled) |
 | 422 | `RS_4.UnprocessableEntity` | Validation failed (Zod errors) |
 | 429 | `RS_4.TooManyRequests` | Rate limit exceeded |
 | 500 | `RS_5.InternalServerError` | Unexpected server error |
@@ -60,7 +60,7 @@ Use the correct status code for each error type:
 | 503 | `RS_5.ServiceUnavailable` | Service temporarily down |
 
 :::tip Automatic Database Error Handling
-Database errors in SQLSTATE class `22` (data exception) and `23` (integrity constraint — unique, foreign key, not null, check, exclusion) are automatically converted to HTTP 400 by the global error middleware. You don't need to catch these manually. Other classes (e.g. syntax / undefined column) stay 500, and production responses are sanitized — see [Repository Layer Errors](#repository-layer-errors).
+Database errors in SQLSTATE classes `22` (data exception), `23` (integrity constraint - unique, foreign key, not null, check, exclusion), and `44` (WITH CHECK OPTION violation) are automatically converted to HTTP 400 by the global error middleware. Transient conflicts (`40001` serialization failure, `40P01` deadlock) become HTTP 409 with a retryable message. You don't need to catch these manually. Other classes (e.g. syntax / undefined column) stay 500, and production responses are sanitized - see [Repository Layer Errors](#repository-layer-errors).
 :::
 
 ## 3. Error Handling Patterns
@@ -73,12 +73,12 @@ import { getError, HTTP } from '@venizia/ignis-helpers';
 
 export class UserService extends BaseService {
   async createUser(data: TCreateUserRequest): Promise<TUser> {
-    // Validate business rules
-    const existingUser = await this.userRepo.findOne({
+    // Validate business rules (findOne returns the record or null)
+    const existingUser = await this.userRepository.findOne({
       filter: { where: { email: data.email } },
     });
 
-    if (existingUser.data) {
+    if (existingUser) {
       throw getError({
         statusCode: HTTP.ResultCodes.RS_4.Conflict,
         message: 'Email already registered',
@@ -95,13 +95,16 @@ export class UserService extends BaseService {
         data.email, error.message);
     }
 
-    return this.userRepo.create({ data });
+    // create returns { count, data }
+    const created = await this.userRepository.create({ data });
+    return created.data;
   }
 
   async getUserOrFail(id: string): Promise<TUser> {
-    const user = await this.userRepo.findById({ id });
+    // findById returns the record or null (no wrapper object)
+    const user = await this.userRepository.findById({ id });
 
-    if (!user.data) {
+    if (!user) {
       throw getError({
         statusCode: HTTP.ResultCodes.RS_4.NotFound,
         message: 'User not found',
@@ -109,7 +112,7 @@ export class UserService extends BaseService {
       });
     }
 
-    return user.data;
+    return user;
   }
 }
 ```
@@ -148,33 +151,34 @@ export class UserController extends BaseRestController {
 
 ### Repository Layer Errors
 
-Database errors in SQLSTATE class `22` (data exception) and `23` (integrity constraint — unique, foreign key, not null, check, exclusion) are **automatically handled** by the global error middleware and return HTTP 400. Codes outside those classes (e.g. class `42` undefined column — an application/SQL bug) correctly stay 500.
+Database errors in SQLSTATE classes `22` (data exception), `23` (integrity constraint - unique, foreign key, not null, check, exclusion), and `44` (WITH CHECK OPTION violation) are **automatically handled** by the global error middleware and return HTTP 400. Transient conflicts (`40001` serialization failure, `40P01` deadlock) return HTTP 409 with a generic retryable message. Codes outside those classes (e.g. class `42` undefined column - an application/SQL bug) correctly stay 500.
 
 **Non-production** returns the full driver context for debugging:
 
 ```json
 {
   "message": "Unique constraint violation\nDetail: Key (email)=(test@example.com) already exists.\nTable: User\nConstraint: UQ_User_email",
+  "messageCode": "core.system_error",
   "statusCode": 400,
   "requestId": "abc123"
 }
 ```
 
 :::warning Production sanitizes database internals
-In production the message is the **base message only** — `Detail:` (which echoes row values like emails), `Table:`, and `Constraint:` are stripped, and `details.stack`/`details.cause` are omitted. Unexpected (non-client) database errors and connection failures return a generic `"Internal Server Error"`, so SQL, schema names, and connection host/port never leak. Use `requestId` + server logs to diagnose.
+In production the message is the **base message only** - `Detail:` (which echoes row values like emails), `Table:`, and `Constraint:` are stripped, and `details.stack`/`details.cause` are omitted. Unexpected (non-client) database errors and connection failures return a generic `"Internal Server Error"`, so SQL, schema names, and connection host/port never leak. Use `requestId` + server logs to diagnose.
 
 ```json
-{ "message": "Unique constraint violation", "statusCode": 400, "requestId": "abc123" }
+{ "message": "Unique constraint violation", "messageCode": "core.system_error", "statusCode": 400, "requestId": "abc123" }
 ```
 :::
 
 You don't need to wrap repository calls in try-catch for constraint errors. If you need custom error messages, you can still handle them explicitly:
 
 ```typescript
-import { BaseRepository } from '@venizia/ignis';
+import { DefaultCRUDRepository } from '@venizia/ignis';
 import { getError, HTTP } from '@venizia/ignis-helpers';
 
-export class UserRepository extends BaseRepository<typeof User.schema> {
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
   async createWithCustomError(data: TCreateUser): Promise<TCreateResult<TUser>> {
     try {
       return await this.create({ data });
@@ -194,11 +198,11 @@ export class UserRepository extends BaseRepository<typeof User.schema> {
 
 ## 4. Global Error Handler
 
-Ignis includes a built-in error handler. Customize behavior in your application:
+IGNIS includes a built-in error handler. Customize behavior in your application:
 
 ```typescript
 import { BaseApplication } from '@venizia/ignis';
-import { ApplicationError } from '@venizia/ignis-helpers';
+import { ApplicationError, MessageCode } from '@venizia/ignis-helpers';
 
 export class Application extends BaseApplication {
   override setupMiddlewares(): void {
@@ -216,6 +220,7 @@ export class Application extends BaseApplication {
         return c.json({
           statusCode: error.statusCode,
           message: error.message,
+          messageCode: error.messageCode, // already lower-cased, never undefined
           details: error.details,
           requestId,
         }, error.statusCode as StatusCode);
@@ -226,6 +231,7 @@ export class Application extends BaseApplication {
         return c.json({
           statusCode: 422,
           message: 'Validation failed',
+          messageCode: MessageCode.DEFAULT,
           details: { cause: error.errors },
           requestId,
         }, 422);
@@ -235,6 +241,7 @@ export class Application extends BaseApplication {
       return c.json({
         statusCode: 500,
         message: 'Internal server error',
+        messageCode: MessageCode.DEFAULT,
         requestId,
       }, 500);
     });
@@ -271,19 +278,23 @@ interface ErrorResponse {
 {
   "statusCode": 400,
   "message": "Invalid request body",
+  "messageCode": "core.system_error",
   "requestId": "abc123"
 }
 
 // 404 Not Found
+// Extra keys passed to getError(...) (e.g. `details`) surface under `extra`;
+// the top-level `details` object is reserved for middleware context (url, path, stack, cause).
 {
   "statusCode": 404,
   "message": "User not found",
+  "messageCode": "core.system_error",
   "requestId": "abc123",
-  "details": { "id": "user-uuid" }
+  "extra": { "details": { "id": "user-uuid" } }
 }
 
 // 422 Validation Error
-// `message`/`messageCode` come from the first failing issue — its `params.code` if the schema set
+// `message`/`messageCode` come from the first failing issue - its `params.code` if the schema set
 // one, otherwise the raw Zod code (e.g. `invalid_type`, `too_small`). The full list stays in `details.cause`.
 {
   "statusCode": 422,
@@ -305,12 +316,25 @@ interface ErrorResponse {
 {
   "statusCode": 500,
   "message": "Internal server error",
+  "messageCode": "core.system_error",
   "requestId": "abc123"
 }
 ```
 
 ## 6. Logging Errors
 
+### `%s`, Never `%j`, for an `Error`
+
+`message` and `stack` are non-enumerable properties on a native `Error` (and on `ApplicationError`, which extends it). `%j` serializes via `JSON.stringify`, which only visits enumerable own properties - so `logger.error('... | error: %j', error)` silently drops both `message` and `stack`, logging little more than `{}`. Always use `%s` to log an `Error` instance; reserve `%j`/`%o` for plain data objects.
+
+```typescript
+// ✅ Good - %s prints message + stack
+this.logger.error('[createOrder] Failed | error: %s', error);
+
+// ❌ Bad - %j drops message and stack (non-enumerable)
+this.logger.error('[createOrder] Failed | error: %j', error);
+```
+
 ### What to Log
 
 ```typescript
@@ -358,7 +382,7 @@ this.logger.debug('[query] Executing | sql: %s | params: %j', sql, params);
 ```typescript
 // ✅ Good - Errors propagate naturally with async/await
 async function processOrder(orderId: string) {
-  const order = await orderRepo.findById({ id: orderId }); // Throws if fails
+  const order = await orderRepository.findById({ id: orderId }); // Throws if fails
   const payment = await paymentService.charge(order); // Throws if fails
   return payment;
 }
@@ -402,11 +426,11 @@ this.sendNotification(userId); // If this rejects, crash!
 
 ```typescript
 async function transferFunds(from: string, to: string, amount: number) {
-  const tx = await accountRepo.beginTransaction();
+  const tx = await accountRepository.beginTransaction();
 
   try {
-    await accountRepo.debit({ id: from, amount }, { transaction: tx });
-    await accountRepo.credit({ id: to, amount }, { transaction: tx });
+    await accountRepository.debit({ id: from, amount, options: { transaction: tx } });
+    await accountRepository.credit({ id: to, amount, options: { transaction: tx } });
 
     await tx.commit();
     return { success: true };

package/content/best-practices/index.md

@@ -1,6 +1,6 @@
 # Best Practices
 
-Production-ready patterns, security guidelines, and optimization strategies for building robust Ignis applications. These best practices are distilled from real-world experience building enterprise applications.
+Production-ready patterns, security guidelines, and optimization strategies for building robust IGNIS applications. These best practices are distilled from real-world experience building enterprise applications.
 
 <div class="guide-cards">
 
@@ -112,7 +112,7 @@ request: { body: jsonContent({ schema: z.object({ email: z.string().email() }) }
 // ❌ Business logic in controllers
 @get({ configs: RouteConfigs.GET_USER })
 async getUser(c: Context) {
-  const user = await this.userRepo.findById(id);
+  const user = await this.userRepository.findById({ id });
   if (user.lastLogin < cutoff) await this.sendReminder(user); // Move to service!
   return c.json(user);
 }
@@ -130,7 +130,7 @@ const data: any = await fetchData(); // Use proper types!
 |-------|--------|
 | Secrets | Store in environment variables, never in code |
 | Input | Validate with Zod schemas at API boundaries |
-| Auth | Protect routes with `authStrategies: [Authentication.STRATEGY_JWT]` |
+| Auth | Protect routes with `authenticate: { strategies: [Authentication.STRATEGY_JWT] }` |
 | Sensitive data | Use `hiddenProperties` in model settings |
 | File uploads | Use `sanitizeFilename()` for all user-provided filenames |
 | CORS | Configure allowed origins explicitly |
@@ -186,7 +186,7 @@ const data: any = await fetchData(); // Use proper types!
 |-------|-------------|
 | [Contribution Workflow](./contribution-workflow) | Git workflow, PR guidelines, code review |
 
-> [!TIP] New to Ignis?
+> [!TIP] New to IGNIS?
 > Start with the [Getting Started Guide](/guides/) for tutorials, then return here for production-ready patterns.
 
 > [!WARNING] Production Deployment?
@@ -194,7 +194,7 @@ const data: any = await fetchData(); // Use proper types!
 
 ## See Also
 
-- [Getting Started](/guides/) - New to Ignis? Start here
+- [Getting Started](/guides/) - New to IGNIS? Start here
 - [API Reference](/references/) - Detailed API documentation
 - [Core Concepts](/guides/core-concepts/application/) - Deep dive into architecture
 - [Changelogs](/changelogs/) - Version history and updates