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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/ignis-docs",
-  "version": "0.0.7-0",
+  "version": "0.0.7-2",
   "description": "Interactive documentation site and MCP (Model Context Protocol) server for the Ignis Framework. Includes a VitePress-powered documentation site with guides, API references, and best practices. Ships an MCP server (CLI: ignis-docs-mcp) with 11 tools for AI assistants to search docs, browse source code, verify dependencies, and access real-time framework knowledge. Built with Mastra MCP SDK and Fuse.js fuzzy search.",
   "keywords": [
     "ai",

package/wiki/references/base/application.md

@@ -49,6 +49,34 @@ Extends `AbstractApplication` with concrete lifecycle implementations and resour
 | `repository(MyRepository, opts?)`| `repositories.MyRepository` (default) or custom key via `opts.binding` |
 | `dataSource(MyDataSource, opts?)`| `datasources.MyDataSource` (default) or custom key via `opts.binding` |
 
+> [!TIP]
+> All registration methods accept an optional `opts.binding` parameter to override the default namespace-based key:
+> ```typescript
+> this.controller(UserController, {
+>   binding: { namespace: 'controllers', key: 'CustomUserController' },
+> });
+> ```
+
+### registerDynamicBindings
+
+Protected method for handling late-registration and circular dependency patterns. Iterates bindings in a namespace, configuring each instance and re-fetching to pick up dynamically added bindings.
+
+```typescript
+protected async registerDynamicBindings<T extends IConfigurable>(opts: {
+  namespace: TBindingNamespace;
+  onBeforeConfigure?: (opts: { binding: Binding<T> }) => Promise<void>;
+  onAfterConfigure?: (opts: { binding: Binding<T>; instance: T }) => Promise<void>;
+}): Promise<void>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `namespace` | `TBindingNamespace` | Binding namespace to scan (e.g., `'components'`, `'controllers'`) |
+| `onBeforeConfigure` | callback | Called before each binding's `configure()` — use for validation |
+| `onAfterConfigure` | callback | Called after `configure()` — use for route mounting, post-setup |
+
+The method tracks already-configured bindings to prevent duplicates and re-fetches after each configuration to handle bindings registered during the configure phase.
+
 ### `initialize()` Method Flow
 
 Startup sequence executed by the `initialize()` method:

package/wiki/references/base/controllers.md

@@ -197,6 +197,29 @@ Manual route definition is useful for:
 - Complex routing logic that benefits from programmatic control
 :::
 
+#### `defineJSXRoute`
+
+Define a route that returns server-rendered JSX/HTML:
+
+```typescript
+this.defineJSXRoute({
+  configs: {
+    path: '/dashboard',
+    method: 'get',
+    responses: htmlResponse({ description: 'Dashboard page' }),
+  },
+  handler: async (c) => {
+    const data = await this.dashboardService.getData();
+    return c.html(<DashboardPage data={data} />);
+  },
+  hook: (result, c) => {
+    // Optional hook for post-processing
+  },
+});
+```
+
+Works the same as `defineRoute()` but typed for JSX handler return values.
+
 #### `defineRoute`
 
 This method is for creating API endpoints. It now handles both public and authenticated routes by accepting an `authStrategies` array within the `configs`.

package/wiki/references/base/datasources.md

@@ -18,7 +18,7 @@ Technical reference for DataSource classes - managing database connections in Ig
 | **AbstractDataSource** | Base implementation with logging | Extends `BaseHelper` |
 | **BaseDataSource** | Concrete class to extend | Auto-discovery, driver from decorator, transaction support |
 | **ITransaction** | Transaction object | `connector`, `isActive`, `commit()`, `rollback()` |
-| **IsolationLevels** | Isolation level constants | `READ_COMMITTED`, `REPEATABLE_READ`, `SERIALIZABLE` |
+| **IsolationLevels** | Isolation level constants | `READ_UNCOMMITTED`, `READ_COMMITTED`, `REPEATABLE_READ`, `SERIALIZABLE` |
 
 ## `IDataSource` Interface
 
@@ -61,6 +61,9 @@ This class extends `AbstractDataSource` and provides a constructor with **auto-d
 | **Schema Auto-Discovery** | Schema is automatically built from registered `@repository` decorators |
 | **Manual Override** | You can still manually provide schema in constructor for full control |
 
+> [!TIP]
+> Set `metadata.autoDiscovery` to `false` in the `@datasource` decorator to disable automatic schema discovery. This is useful when you want to manually provide the schema.
+
 ### Constructor Options
 
 ```typescript
@@ -288,7 +291,7 @@ DataSources provide built-in transaction management through the `beginTransactio
 |------|-------------|
 | `ITransaction<Schema>` | Transaction object with `commit()`, `rollback()`, and `connector` |
 | `ITransactionOptions` | Options for starting a transaction (e.g., `isolationLevel`) |
-| `TIsolationLevel` | Union type: `'READ COMMITTED'` \| `'REPEATABLE READ'` \| `'SERIALIZABLE'` |
+| `TIsolationLevel` | Union type: `'READ UNCOMMITTED'` \| `'READ COMMITTED'` \| `'REPEATABLE READ'` \| `'SERIALIZABLE'` |
 | `IsolationLevels` | Static class with isolation level constants and validation |
 
 ### ITransaction Interface
@@ -312,6 +315,7 @@ Use the `IsolationLevels` static class for type-safe isolation level constants:
 import { IsolationLevels } from '@venizia/ignis';
 
 // Available levels
+IsolationLevels.READ_UNCOMMITTED // Allows dirty reads (least strict)
 IsolationLevels.READ_COMMITTED   // Default - prevents dirty reads
 IsolationLevels.REPEATABLE_READ  // Consistent reads within transaction
 IsolationLevels.SERIALIZABLE     // Strictest isolation

package/wiki/references/base/dependency-injection.md

@@ -191,6 +191,37 @@ class UserController {
 
 > **Learn More:** See [Bootstrapping Concepts](/guides/core-concepts/application/bootstrapping)
 
+## Request Context Access
+
+Access the current Hono request context from anywhere using `useRequestContext()`. This uses Hono's context storage middleware and requires `asyncContext.enable: true` in application config.
+
+```typescript
+import { useRequestContext } from '@venizia/ignis';
+
+class MyService extends BaseService {
+  async doSomething() {
+    const ctx = useRequestContext();
+    if (ctx) {
+      const userId = ctx.get('currentUser')?.id;
+      // Use context data without passing it through parameters
+    }
+  }
+}
+```
+
+> [!WARNING]
+> `useRequestContext()` returns `undefined` outside of request handling. Always check for `undefined` before accessing context properties.
+
+**Setup:** Enable async context in your application:
+```typescript
+class MyApp extends BaseApplication {
+  configs = {
+    asyncContext: { enable: true },
+    // ...
+  };
+}
+```
+
 ## See Also
 
 - **Related Concepts:**

package/wiki/references/base/filter-system/fields-order-pagination.md

@@ -94,7 +94,9 @@ await repo.find({
 
 ## Pagination
 
-### Limit and Skip
+### Limit and Skip/Offset
+
+Both `skip` and `offset` are supported as aliases — they both map to the SQL `OFFSET` clause. When both are provided, `skip` takes precedence.
 
 ```typescript
 // First 10 results
@@ -107,6 +109,11 @@ await repo.find({
   filter: { limit: 10, skip: 10 }
 });
 
+// Using offset (equivalent to skip)
+await repo.find({
+  filter: { limit: 10, offset: 10 }
+});
+
 // Page N formula: skip = (page - 1) * limit
 const page = 3;
 const pageSize = 20;

package/wiki/references/base/models.md

@@ -842,6 +842,139 @@ export const auditLogTable = pgTable('AuditLog', {
 ```
 
 
+### `generateDataTypeColumnDefs`
+
+Adds polymorphic data storage columns for entities that need to store values of different types in a single table. This is useful for key-value stores, settings tables, or any schema where a row's value type is determined at runtime.
+
+**File:** `packages/core/src/base/models/enrichers/data-type.enricher.ts`
+
+#### Signature
+
+```typescript
+generateDataTypeColumnDefs(opts?: TDataTypeEnricherOptions): {
+  dataType: PgTextBuilderInitial;
+  nValue: PgDoublePrecisionBuilderInitial;
+  tValue: PgTextBuilderInitial;
+  bValue: PgCustomColumnBuilder<Buffer>;
+  jValue: PgJsonbBuilderInitial<Record<string, any>>;
+  boValue: PgBooleanBuilderInitial;
+}
+```
+
+#### Options (`TDataTypeEnricherOptions`)
+
+```typescript
+type TDataTypeEnricherOptions = {
+  defaultValue: Partial<{
+    dataType: string;
+    nValue: number;
+    tValue: string;
+    bValue: Buffer;
+    jValue: object;
+    boValue: boolean;
+  }>;
+};
+```
+
+#### Generated Columns
+
+| Column | SQL Type | DB Column Name | TypeScript Type | Purpose |
+|--------|----------|----------------|-----------------|---------|
+| `dataType` | `text` | `data_type` | `string` | Type discriminator (e.g., `'number'`, `'text'`, `'json'`) |
+| `nValue` | `double precision` | `n_value` | `number` | Numeric values |
+| `tValue` | `text` | `t_value` | `string` | Text values |
+| `bValue` | `bytea` | `b_value` | `Buffer` | Binary values |
+| `jValue` | `jsonb` | `j_value` | `Record<string, any>` | JSON values |
+| `boValue` | `boolean` | `bo_value` | `boolean` | Boolean values |
+
+All columns are **nullable** by default (no `NOT NULL` constraint), since only one value column is typically populated per row depending on the `dataType` discriminator.
+
+#### Usage Examples
+
+**Basic usage:**
+
+```typescript
+import { pgTable } from 'drizzle-orm/pg-core';
+import { BaseEntity, model, generateIdColumnDefs, generateDataTypeColumnDefs } from '@venizia/ignis';
+
+@model({ type: 'entity' })
+export class Setting extends BaseEntity<typeof Setting.schema> {
+  static override schema = pgTable('Setting', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    ...generateDataTypeColumnDefs(),
+  });
+}
+```
+
+**With default values:**
+
+```typescript
+export const settingTable = pgTable('Setting', {
+  ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+  ...generateDataTypeColumnDefs({
+    defaultValue: { dataType: 'text', tValue: '' },
+  }),
+});
+
+// Generates columns with SQL defaults:
+// data_type text DEFAULT 'text'
+// t_value text DEFAULT ''
+// nValue, bValue, jValue, boValue — no defaults
+```
+
+**Key-value store pattern:**
+
+```typescript
+@model({ type: 'entity' })
+export class AppConfig extends BaseEntity<typeof AppConfig.schema> {
+  static override schema = pgTable('AppConfig', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    ...generateDataTypeColumnDefs(),
+    key: text('key').notNull().unique(),
+    description: text('description'),
+  });
+}
+
+// Usage:
+// { key: 'max_retries', dataType: 'number', nValue: 3 }
+// { key: 'welcome_message', dataType: 'text', tValue: 'Hello!' }
+// { key: 'feature_flags', dataType: 'json', jValue: { darkMode: true } }
+// { key: 'is_maintenance', dataType: 'boolean', boValue: false }
+```
+
+### `enrichDataTypes`
+
+A convenience function that merges data type columns into an existing schema object, rather than spreading into `pgTable`.
+
+#### Signature
+
+```typescript
+enrichDataTypes(
+  baseSchema: TColumnDefinitions,
+  opts?: TDataTypeEnricherOptions,
+): TColumnDefinitions
+```
+
+#### Usage
+
+```typescript
+import { text } from 'drizzle-orm/pg-core';
+import { enrichDataTypes, generateIdColumnDefs } from '@venizia/ignis';
+
+const baseColumns = {
+  ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+  key: text('key').notNull(),
+};
+
+// Merge data type columns into existing column definitions
+const allColumns = enrichDataTypes(baseColumns);
+
+export const configTable = pgTable('Config', allColumns);
+```
+
+This is equivalent to spreading `generateDataTypeColumnDefs()` directly but useful when building column definitions programmatically.
+
+
 ## Schema Utilities
 
 ### `snakeToCamel`

package/wiki/references/base/repositories/advanced.md

@@ -328,7 +328,7 @@ if (user) {
 - `find<R>()`, `findOne<R>()`, `findById<R>()`
 - `create<R>()`, `createAll<R>()`
 - `updateById<R>()`, `updateAll<R>()`
-- `deleteById<R>()`, `deleteAll<R>()`
+- `deleteById<R>()`, `deleteAll<R>()`, `deleteBy<R>()`
 
 
 ## Debugging
@@ -355,7 +355,7 @@ await repo.updateById({
 });
 ```
 
-**Available on:** `create`, `createAll`, `updateById`, `updateAll`, `deleteById`, `deleteAll`
+**Available on:** `create`, `createAll`, `updateById`, `updateAll`, `deleteById`, `deleteAll`, `deleteBy`
 
 ### Query Interface Validation
 

package/wiki/references/base/repositories/index.md

@@ -29,8 +29,9 @@ export class TodoRepository extends DefaultCRUDRepository<typeof Todo.schema> {
 | **ReadableRepository** | Read-only operations | Views, external tables |
 | **PersistableRepository** | Read + Write operations | Rarely used directly |
 | **DefaultCRUDRepository** | Full CRUD operations | Standard data tables |
+| **SoftDeletableRepository** | CRUD + soft delete + restore | Tables with `deletedAt` column |
 
-**Most common:** Extend `DefaultCRUDRepository` for standard tables.
+**Most common:** Extend `DefaultCRUDRepository` for standard tables, or `SoftDeletableRepository` for soft-delete patterns.
 
 
 ## Available Methods
@@ -54,6 +55,7 @@ export class TodoRepository extends DefaultCRUDRepository<typeof Todo.schema> {
 | `updateAll(opts)` | Update matching records | `repo.updateAll({ where: { status: 'draft' }, data: { status: 'published' } })` |
 | `deleteById(opts)` | Delete by primary key | `repo.deleteById({ id: '123' })` |
 | `deleteAll(opts)` | Delete matching records | `repo.deleteAll({ where: { status: 'archived' } })` |
+| `deleteBy(opts)` | Delete by where condition | `repo.deleteBy({ where: { status: 'archived' } })` |
 
 
 ## Documentation Sections
@@ -94,6 +96,22 @@ await repo.find({
 });
 ```
 
+### [SoftDeletableRepository](./soft-deletable.md)
+Soft-delete and restore operations using `deletedAt` timestamps instead of physical deletion.
+
+```typescript
+// Preview
+@repository({ model: Category, dataSource: PostgresDataSource })
+export class CategoryRepository extends SoftDeletableRepository<typeof Category.schema> {}
+
+// Soft delete (sets deletedAt)
+await repo.deleteById({ id: '123' });
+// Restore
+await repo.restoreById({ id: '123' });
+// Hard delete (physical removal)
+await repo.deleteById({ id: '123', options: { shouldHardDelete: true } });
+```
+
 ### [Advanced Features](./advanced.md)
 Transactions, hidden properties, default filter bypass, performance optimization, and type inference.
 
@@ -193,6 +211,10 @@ await repo.deleteAll({ where: {}, options: { force: true } });
 | Create one | `repo.create({ data: { name: 'John' } })` |
 | Update by ID | `repo.updateById({ id: '123', data: { name: 'Jane' } })` |
 | Delete by ID | `repo.deleteById({ id: '123' })` |
+| Delete by condition | `repo.deleteBy({ where: { status: 'archived' } })` |
+| Soft delete | `repo.deleteById({ id: '123' })` (with `SoftDeletableRepository`) |
+| Restore soft-deleted | `repo.restoreById({ id: '123' })` (with `SoftDeletableRepository`) |
+| Hard delete (bypass soft) | `repo.deleteById({ id: '123', options: { shouldHardDelete: true } })` |
 | Count matching | `repo.count({ where: { status: 'active' } })` |
 | Check exists | `repo.existsWith({ where: { email: 'test@example.com' } })` |
 
@@ -201,6 +223,7 @@ await repo.deleteAll({ where: {}, options: { force: true } });
 
 - **New to filtering?** Start with [Filter System](/references/base/filter-system/)
 - **Need related data?** See [Relations & Includes](./relations.md)
+- **Need soft delete?** See [SoftDeletableRepository](./soft-deletable.md)
 - **Need transactions?** Go to [Advanced Features](./advanced.md)
 
 ## See Also

package/wiki/references/base/repositories/soft-deletable.md

@@ -0,0 +1,213 @@
+---
+title: SoftDeletableRepository
+description: Repository with soft-delete and restore operations using deletedAt timestamps
+difficulty: intermediate
+---
+
+# SoftDeletableRepository
+
+A repository that overrides delete operations to set a `deletedAt` timestamp instead of physically removing records. Extends `DefaultCRUDRepository` with restore capabilities.
+
+**File:** `packages/core/src/base/repositories/core/soft-deletable.ts`
+
+
+## Setup
+
+### 1. Define Model with Soft Delete
+
+```typescript
+import { pgTable, text, timestamp } from 'drizzle-orm/pg-core';
+import {
+  BaseEntity,
+  model,
+  generateIdColumnDefs,
+  generateTzColumnDefs,
+} from '@venizia/ignis';
+
+@model({
+  type: 'entity',
+  settings: {
+    hiddenProperties: ['deletedAt'],
+    defaultFilter: { where: { deletedAt: null } },
+  },
+})
+export class Category extends BaseEntity<typeof Category.schema> {
+  static override schema = pgTable('Category', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    ...generateTzColumnDefs(),
+    name: text('name').notNull(),
+    deletedAt: timestamp('deleted_at', { mode: 'date', withTimezone: true }),
+  });
+}
+```
+
+> [!IMPORTANT]
+> - The model **must** have a `deletedAt` column (`Date | null`).
+> - Set `defaultFilter: { where: { deletedAt: null } }` so soft-deleted records are excluded by default.
+> - Optionally add `deletedAt` to `hiddenProperties` to hide it from API responses.
+
+### 2. Create Repository
+
+```typescript
+import { repository, SoftDeletableRepository } from '@venizia/ignis';
+import { Category } from '@/models/category.model';
+import { PostgresDataSource } from '@/datasources/postgres.datasource';
+
+@repository({ model: Category, dataSource: PostgresDataSource })
+export class CategoryRepository extends SoftDeletableRepository<typeof Category.schema> {}
+```
+
+
+## Delete Operations
+
+All delete methods set `deletedAt = new Date()` instead of removing the row. They internally call the corresponding `update` method.
+
+### deleteById
+
+```typescript
+// Soft delete — sets deletedAt timestamp
+const result = await repo.deleteById({ id: '123' });
+// { count: 1, data: { id: '123', name: 'Electronics', deletedAt: '2026-03-06T...' } }
+
+// Hard delete — physically removes the row
+const result = await repo.deleteById({
+  id: '123',
+  options: { shouldHardDelete: true },
+});
+```
+
+### deleteAll
+
+```typescript
+// Soft delete all matching records
+const result = await repo.deleteAll({
+  where: { status: 'archived' },
+  options: { force: true },
+});
+
+// Hard delete all matching records
+const result = await repo.deleteAll({
+  where: { status: 'archived' },
+  options: { shouldHardDelete: true, force: true },
+});
+```
+
+### deleteBy
+
+```typescript
+// Soft delete by where condition (requires non-empty where)
+const result = await repo.deleteBy({
+  where: { name: 'Obsolete' },
+});
+```
+
+
+## Restore Operations
+
+Restore methods set `deletedAt = null` and automatically use `shouldSkipDefaultFilter: true` to find soft-deleted records.
+
+### restoreById
+
+```typescript
+const result = await repo.restoreById({ id: '123' });
+// { count: 1, data: { id: '123', name: 'Electronics', deletedAt: null } }
+
+// Without returning data
+const result = await repo.restoreById({
+  id: '123',
+  options: { shouldReturn: false },
+});
+```
+
+### restoreAll
+
+```typescript
+// Restore all soft-deleted records (requires force for empty where)
+const result = await repo.restoreAll({
+  where: {},
+  options: { force: true },
+});
+
+// Restore matching records
+const result = await repo.restoreAll({
+  where: { name: 'Electronics' },
+});
+```
+
+### restoreBy
+
+```typescript
+// Alias for restoreAll with required where
+const result = await repo.restoreBy({
+  where: { status: 'archived' },
+});
+```
+
+
+## Read Operations
+
+### findById with isStrict
+
+`SoftDeletableRepository` overrides `findById` to support a `isStrict` option that throws a `404 Not Found` error when the record doesn't exist:
+
+```typescript
+// Returns null if not found (default)
+const category = await repo.findById({ id: '123' });
+
+// Throws 404 if not found
+const category = await repo.findById({
+  id: '123',
+  options: { isStrict: true },
+});
+```
+
+
+## Options Reference
+
+### Delete Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `shouldHardDelete` | `boolean` | `false` | Bypass soft delete and physically remove the row |
+| `shouldReturn` | `boolean` | `true` | Return the updated/deleted record |
+| `force` | `boolean` | `false` | Allow empty `where` condition (deleteAll/deleteBy) |
+| `transaction` | `ITransaction` | — | Transaction context |
+
+### Restore Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `shouldReturn` | `boolean` | `true` | Return the restored record |
+| `force` | `boolean` | `false` | Allow empty `where` condition (restoreAll) |
+| `transaction` | `ITransaction` | — | Transaction context |
+
+
+## How It Works
+
+| Operation | Behavior |
+|-----------|----------|
+| `deleteById` | `UPDATE SET deletedAt = NOW() WHERE id = ?` |
+| `deleteAll` | `UPDATE SET deletedAt = NOW() WHERE ...` |
+| `restoreById` | `UPDATE SET deletedAt = NULL WHERE id = ?` (skips default filter) |
+| `restoreAll` | `UPDATE SET deletedAt = NULL WHERE ...` (skips default filter) |
+| `find` / `findOne` | Default filter automatically excludes `deletedAt IS NOT NULL` |
+
+> [!TIP]
+> Restore operations automatically set `shouldSkipDefaultFilter: true` so they can find soft-deleted records that would normally be hidden by the default filter.
+
+
+## With Transactions
+
+```typescript
+const tx = await this.dataSource.beginTransaction();
+try {
+  await this.categoryRepo.deleteById({ id: '123', options: { transaction: tx } });
+  await this.auditRepo.create({
+    data: { action: 'soft_delete', entityId: '123' },
+    options: { transaction: tx },
+  });
+  await tx.commit();
+} catch {
+  await tx.rollback();
+}
+```