@venizia/ignis-docs 0.0.6-3 → 0.0.7-1

package/wiki/references/base/controllers.md

@@ -58,7 +58,8 @@ For decorator-based routes, you do not need to explicitly annotate the return ty
 The generic `@api` decorator allows you to define a route with a full configuration object. The decorated method will automatically have its `context` parameter and return type inferred and type-checked against the provided route configuration. This ensures strong type safety throughout your API definitions.
 
 ```typescript
-import { api, BaseController, controller, HTTP, jsonContent, jsonResponse, z, TRouteContext } from '@venizia/ignis';
+import { api, BaseController, controller, jsonContent, jsonResponse, z, TRouteContext } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 
 const MyRouteConfig = {
   method: 'get',
@@ -89,7 +90,8 @@ For convenience, `Ignis` provides decorator shortcuts for each HTTP method: Thes
 **Example using `@get` and `@post`:**
 
 ```typescript
-import { get, post, z, jsonContent, jsonResponse, Authentication, TRouteContext, HTTP } from '@venizia/ignis';
+import { get, post, z, jsonContent, jsonResponse, Authentication, TRouteContext } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 
 // Define route configs as const
 const UserRoutes = {
@@ -153,7 +155,8 @@ const UserRoutes = {
 For better organization, you can define all your route configurations in a constant and reference them in your decorators. This approach also allows you to get a typed context for your handler.
 
 ```typescript
-import { api, BaseController, controller, TRouteContext, jsonContent, jsonResponse, HTTP } from '@venizia/ignis';
+import { api, BaseController, controller, TRouteContext, jsonContent, jsonResponse } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 import { z } from 'hono/zod-openapi';
 
 const RouteConfigs = {
@@ -194,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`.
@@ -264,7 +290,8 @@ request: {
 The `defineRouteConfigs` function is a simple helper for creating a typed object containing multiple route configurations. This is particularly useful for organizing all of a controller's route definitions in a single, type-checked constant.
 
 ```typescript
-import { defineRouteConfigs, HTTP, jsonResponse, jsonContent, z } from '@venizia/ignis';
+import { defineRouteConfigs, jsonResponse, jsonContent, z } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 
 const RouteConfigs = defineRouteConfigs({
   ROOT: {

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/middlewares.md

@@ -294,7 +294,8 @@ app.use(requestSpy.value());
 #### Accessing Request ID
 
 ```typescript
-import { RequestSpyMiddleware, get, HTTP, jsonResponse, TRouteContext, z } from '@venizia/ignis';
+import { RequestSpyMiddleware, get, jsonResponse, TRouteContext, z } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 
 const ExampleConfig = {
   method: HTTP.Methods.GET,

package/wiki/references/base/models.md

@@ -32,7 +32,7 @@ Fundamental building block wrapping a Drizzle ORM schema.
 | **Schema Encapsulation** | Holds Drizzle `pgTable` schema for consistent repository access |
 | **Metadata** | Works with `@model` decorator to mark database entities |
 | **Schema Generation** | Uses `drizzle-zod` to generate Zod schemas (`SELECT`, `CREATE`, `UPDATE`) |
-| **Static Properties** | Supports static `schema`, `relations`, and `TABLE_NAME` for cleaner syntax |
+| **Static Properties** | Supports static `schema`, `relations`, `TABLE_NAME`, and `AUTHORIZATION_SUBJECT` |
 | **Convenience** | Includes `toObject()` and `toJSON()` methods |
 
 ### The `@model` Decorator
@@ -49,6 +49,10 @@ The `@model` decorator marks a class as a database entity and configures its beh
   settings?: {
     hiddenProperties?: string[],  // Properties to exclude from query results
     defaultFilter?: TFilter,      // Filter applied to all repository queries
+    authorize?: {                  // Authorization settings
+      principal: string,           // Authorization subject name
+      [extra: string | symbol]: any, // Extensible metadata
+    },
   }
 })
 ```
@@ -60,6 +64,8 @@ The `@model` decorator marks a class as a database entity and configures its beh
 | `skipMigrate` | `boolean` | Skip this model during schema migrations |
 | `settings.hiddenProperties` | `string[]` | Array of property names to exclude from all repository query results |
 | `settings.defaultFilter` | `TFilter` | Filter automatically applied to all repository queries (see [Default Filter](/references/base/filter-system/default-filter)) |
+| `settings.authorize` | `IModelAuthorizeSettings` | Authorization settings — declares the model's authorization principal (see [Authorization](/references/components/authorization/usage#model-based-resource-references)) |
+| `settings.authorize.principal` | `string` | The authorization subject name for this model. Auto-populates `AUTHORIZATION_SUBJECT` static property |
 
 ### Hidden Properties
 
@@ -233,6 +239,7 @@ export class User extends BaseEntity<typeof userTable> {
 | `schema` | `TTableSchemaWithId` | Drizzle table schema defined with `pgTable()` |
 | `relations` | `TValueOrResolver<Array<TRelationConfig>>` | Relation definitions (can be a function for lazy loading) |
 | `TABLE_NAME` | `string \| undefined` | Optional table name (defaults to class name if not set) |
+| `AUTHORIZATION_SUBJECT` | `string \| undefined` | Authorization principal name. Auto-populated from `@model` settings `authorize.principal` |
 
 ### IEntity Interface
 
@@ -269,6 +276,7 @@ export class BaseEntity<Schema extends TTableSchemaWithId = TTableSchemaWithId>
   static schema: TTableSchemaWithId;
   static relations?: TValueOrResolver<Array<TRelationConfig>>;
   static TABLE_NAME?: string;  // Optional, defaults to class name
+  static AUTHORIZATION_SUBJECT?: string;  // Auto-set by @model decorator from authorize.principal
 
   // Static singleton for schemaFactory - shared across all instances
   // Performance optimization: avoids creating new factory per entity
@@ -834,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`
@@ -902,7 +1043,8 @@ console.log(result);
 **Use case:** API endpoint that accepts snake_case but works with camelCase internally
 
 ```typescript
-import { BaseController, controller, snakeToCamel, HTTP } from '@venizia/ignis';
+import { BaseController, controller, snakeToCamel } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 import { z } from '@hono/zod-openapi';
 
 const createUserSchema = 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();
+}
+```

package/wiki/references/base/services.md

@@ -64,7 +64,8 @@ Services are the core of your application's logic. They act as a bridge between
 ### Example
 
 ```typescript
-import { BaseService, inject, getError } from '@venizia/ignis';
+import { BaseService, inject } from '@venizia/ignis';
+import { getError } from '@venizia/ignis-helpers';
 import { UserRepository } from '../repositories/user.repository';
 import { TUser } from '../models/entities';