@venizia/ignis-docs 0.0.7 → 0.0.8-1

package/wiki/references/base/providers.md

@@ -2,7 +2,7 @@
 title: Providers Reference
 description: Technical reference for the Provider pattern in IGNIS
 difficulty: advanced
-lastUpdated: 2026-01-03
+lastUpdated: 2026-03-15
 ---
 
 # Providers Reference
@@ -461,38 +461,38 @@ export class MailQueueExecutorProvider extends BaseProvider<TGetMailQueueExecuto
 
 ### Example 3: Middleware Provider
 
-Providers can also produce middleware:
+Providers can also produce middleware. `RequestSpyMiddleware` is a real-world example that implements `IProvider<MiddlewareHandler>` directly (extending `BaseHelper`, not `BaseProvider`):
 
 ```typescript
-import { RequestSpyMiddleware } from '@venizia/ignis';
-
-// RequestSpyMiddleware is a provider that produces Hono middleware
-@injectable()
+// From packages/core/src/base/middlewares/request-spy.middleware.ts
 export class RequestSpyMiddleware extends BaseHelper implements IProvider<MiddlewareHandler> {
   static readonly REQUEST_ID_KEY = 'requestId';
 
   constructor() {
-    super({ scope: RequestSpyMiddleware.name });
+    super({ scope: 'SpyMW' });
   }
 
+  /** Returns a Hono middleware that logs request details and duration. */
   value() {
     return createMiddleware(async (context, next) => {
+      const t = performance.now();
       const requestId = context.get(RequestSpyMiddleware.REQUEST_ID_KEY);
+      const method = context.req.method;
+      const path = context.req.path ?? '/';
 
-      this.logger.info('[spy][%s] START | path: %s', requestId, context.req.path);
+      this.logger.info('[%s][=>] %s %s', requestId, method, path);
 
       await next();
 
-      this.logger.info('[spy][%s] DONE | path: %s', requestId, context.req.path);
+      const duration = (performance.now() - t).toFixed(2);
+      this.logger.info('[%s][<=] %s %s | Took: %s (ms)', requestId, method, path, duration);
     });
   }
 }
-
-// Usage
-const requestSpy = new RequestSpyMiddleware();
-app.use(requestSpy.value());
 ```
 
+Note that `RequestSpyMiddleware.value()` does not accept a `container` parameter -- the `IProvider<T>` interface defines `value(container: Container): T`, but implementations may ignore the parameter when they don't need container access. In practice, `RequestSpyMiddleware` is registered via `RequestTrackerComponent`, which binds it as a provider in the DI container and resolves it automatically.
+
 
 ## Common Patterns
 
@@ -708,7 +708,7 @@ export class ConfigProvider extends BaseProvider<Config> {
 - **Related References:**
   - [Services](./services.md) - Business logic layer
   - [Dependency Injection](./dependency-injection.md) - DI container and injection
-  - [Middlewares](./middlewares.md) - Middleware providers
+  - [Middleware](./middleware.md) - Built-in middlewares (includes `RequestSpyMiddleware` provider)
 
 - **Guides:**
   - [Dependency Injection Guide](/guides/core-concepts/dependency-injection.md)

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

@@ -101,6 +101,114 @@ async function transferFunds(fromId: string, toId: string, amount: number) {
 ```
 
 
+## Row-Level Locking
+
+Acquire pessimistic locks on selected rows within a transaction using PostgreSQL's `SELECT ... FOR UPDATE/SHARE` syntax.
+
+### Basic Usage
+
+Pass `lock` in options alongside a `transaction`:
+
+```typescript
+const tx = await repo.beginTransaction();
+
+try {
+  // Lock the row — other transactions will wait
+  const item = await repo.findOne({
+    filter: { where: { id: '123' } },
+    options: {
+      transaction: tx,
+      lock: { strength: 'update' },
+    },
+  });
+
+  // Safe to modify — no concurrent changes possible
+  await repo.updateById({
+    id: '123',
+    data: { quantity: item.quantity - 1 },
+    options: { transaction: tx },
+  });
+
+  await tx.commit();
+} catch (error) {
+  await tx.rollback();
+  throw error;
+}
+```
+
+### Lock Strengths
+
+Use the `LockStrengths` constant class or string literals:
+
+```typescript
+import { LockStrengths } from '@venizia/ignis';
+
+// Using constant
+lock: { strength: LockStrengths.UPDATE }
+
+// Using string literal
+lock: { strength: 'update' }
+```
+
+| Strength | SQL | Use Case |
+|----------|-----|----------|
+| `update` | `FOR UPDATE` | Exclusive lock for writes |
+| `no key update` | `FOR NO KEY UPDATE` | Exclusive lock, allows concurrent `FOR KEY SHARE` |
+| `share` | `FOR SHARE` | Shared read lock, prevents writes |
+| `key share` | `FOR KEY SHARE` | Weakest lock, only prevents key changes |
+
+### Wait Behavior
+
+Control what happens when rows are already locked:
+
+```typescript
+// Skip locked rows (queue-style worker pattern)
+const items = await repo.find({
+  filter: { where: { status: 'pending' }, limit: 10 },
+  options: {
+    transaction: tx,
+    lock: { strength: 'update', config: { skipLocked: true } },
+  },
+});
+
+// Fail immediately instead of waiting
+const item = await repo.findOne({
+  filter: { where: { id: '123' } },
+  options: {
+    transaction: tx,
+    lock: { strength: 'update', config: { noWait: true } },
+  },
+});
+```
+
+| Config | SQL | Behavior |
+|--------|-----|----------|
+| *(none)* | `FOR UPDATE` | Wait until lock is released |
+| `{ noWait: true }` | `FOR UPDATE NOWAIT` | Throw error immediately if locked |
+| `{ skipLocked: true }` | `FOR UPDATE SKIP LOCKED` | Silently skip locked rows |
+
+### Constraints
+
+> [!WARNING]
+> Row-level locking requires a **transaction** and is **incompatible with `include`/`fields`** in the filter (these use the Drizzle Query API which does not support `.for()`).
+
+```typescript
+// Error — no transaction
+await repo.findOne({
+  filter: { where: { id: '123' } },
+  options: { lock: { strength: 'update' } },
+});
+
+// Error — include uses Query API
+await repo.findOne({
+  filter: { where: { id: '123' }, include: [{ relation: 'posts' }] },
+  options: { transaction: tx, lock: { strength: 'update' } },
+});
+```
+
+**Supported methods:** `find`, `findOne`, `findById`
+
+
 ## Hidden Properties
 
 Automatically exclude sensitive fields from query results.
@@ -207,7 +315,7 @@ const usersWithPosts = await repo.find({
 
 | Filter Options | API Used | Performance |
 |----------------|----------|-------------|
-| `where`, `limit`, `order`, `offset` only | Core API | ~15-20% faster |
+| `where`, `limit`, `order`, `offset`/`skip` only | Core API | ~15-20% faster |
 | Has `include` (relations) | Query API | Standard |
 | Has `fields` selection | Query API | Standard |
 
@@ -216,7 +324,7 @@ const usersWithPosts = await repo.find({
 Prevent memory exhaustion on large tables:
 
 ```typescript
-// ✅ Good - bounded result set
+// Good - bounded result set
 await repo.find({
   filter: {
     where: { status: 'active' },
@@ -230,42 +338,39 @@ await repo.find({
 });
 ```
 
-### Pagination Pattern
+> [!NOTE]
+> The default limit is `10` when using the `FilterSchema` Zod validation (via `LimitSchema`). However, when calling repository methods directly without schema validation, no default limit is applied.
+
+### Pagination with Data Range
+
+Use `shouldQueryRange` to get both data and total count in a single call:
 
 ```typescript
-async function getPaginatedUsers(page: number, pageSize: number = 20) {
-  const [users, total] = await Promise.all([
-    userRepo.find({
-      filter: {
-        where: { status: 'active' },
-        limit: pageSize,
-        skip: (page - 1) * pageSize,
-        order: ['createdAt DESC']
-      }
-    }),
-    userRepo.count({ where: { status: 'active' } })
-  ]);
-
-  return {
-    data: users,
-    pagination: {
-      page,
-      pageSize,
-      total,
-      totalPages: Math.ceil(total / pageSize)
-    }
-  };
-}
+const result = await userRepo.find({
+  filter: {
+    where: { status: 'active' },
+    limit: 20,
+    skip: 40,
+    order: ['createdAt DESC']
+  },
+  options: { shouldQueryRange: true }
+});
+
+// Result type: { data: User[], range: { start: number, end: number, total: number } }
+// range follows HTTP Content-Range standard (inclusive end index)
+// Example: { data: [...20 users], range: { start: 40, end: 59, total: 150 } }
 ```
 
+This runs `find` and `count` in parallel via `Promise.all` for optimal performance.
+
 ### WeakMap Cache
 
 The filter builder caches table column metadata, avoiding repeated reflection:
 
 ```typescript
 // Internal optimization - automatic
-// First query: getTableColumns(schema) → cached
-// Subsequent queries: retrieved from WeakMap
+// First query: getTableColumns(schema) -> cached in WeakMap
+// Subsequent queries: retrieved from WeakMap cache
 ```
 
 
@@ -281,8 +386,7 @@ const result1 = await repo.create({
   data: { name: 'John' },
   options: { shouldReturn: false }
 });
-// Type: Promise<{ count: number; data: null }>
-console.log(result1.data); // null
+// Type: Promise<{ count: number; data: undefined | null }>
 
 // shouldReturn: true (default) - TypeScript knows data is the entity
 const result2 = await repo.create({
@@ -327,7 +431,7 @@ if (user) {
 **Supported Methods:**
 - `find<R>()`, `findOne<R>()`, `findById<R>()`
 - `create<R>()`, `createAll<R>()`
-- `updateById<R>()`, `updateAll<R>()`
+- `updateById<R>()`, `updateAll<R>()`, `updateBy<R>()`
 - `deleteById<R>()`, `deleteAll<R>()`, `deleteBy<R>()`
 
 
@@ -355,7 +459,7 @@ await repo.updateById({
 });
 ```
 
-**Available on:** `create`, `createAll`, `updateById`, `updateAll`, `deleteById`, `deleteAll`, `deleteBy`
+**Available on:** `create`, `createAll`, `updateById`, `updateAll`, `updateBy`, `deleteById`, `deleteAll`, `deleteBy` (all write operations that go through `_create`, `_update`, or `_delete` internal methods)
 
 ### Query Interface Validation
 
@@ -377,10 +481,10 @@ The repository validates schema registration on startup:
 Prevents accidental mass updates/deletes:
 
 ```typescript
-// ❌ Throws error - empty where without force
+// Throws error - empty where without force
 await repo.deleteAll({ where: {} });
 
-// ✅ Explicit force flag - logs warning, proceeds
+// Explicit force flag - logs warning, proceeds
 await repo.deleteAll({
   where: {},
   options: { force: true }
@@ -393,29 +497,16 @@ await repo.deleteAll({
 | Empty `where` | Throws error | Logs warning, proceeds |
 | Valid `where` | Executes normally | Executes normally |
 
-### Constructor Type Validation
+> [!NOTE]
+> This protection applies to `updateAll`, `updateBy`, `deleteAll`, and `deleteBy`. The `updateById` and `deleteById` methods always have a non-empty where (`{ id }`) so they are not affected.
 
-The `@repository` decorator validates constructor parameters:
+### Transaction Safety
 
-```typescript
-// ❌ Error: First parameter must extend AbstractDataSource
-@repository({ model: User, dataSource: PostgresDataSource })
-export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
-  constructor(dataSource: any) { // 'any' not allowed!
-    super(dataSource);
-  }
-}
+The `resolveConnector` method validates transaction state before use:
 
-// ✅ Correct: Concrete DataSource type
-@repository({ model: User, dataSource: PostgresDataSource })
-export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
-  constructor(
-    @inject({ key: 'datasources.PostgresDataSource' })
-    dataSource: PostgresDataSource,
-  ) {
-    super(dataSource);
-  }
-}
+```typescript
+// If a transaction has already been committed or rolled back:
+// Error: [UserRepository][resolveConnector] Transaction is no longer active
 ```
 
 
@@ -444,12 +535,13 @@ const results = await connector
 
 ## Repository Class Hierarchy
 
-| Class | Description |
-|-------|-------------|
-| `AbstractRepository` | Base class, defines method signatures |
-| `ReadableRepository` | Read-only operations (find, findOne, count) |
-| `PersistableRepository` | Adds write operations (create, update, delete) |
-| `DefaultCRUDRepository` | Full CRUD - **use this one** |
+| Class | Scope | Description |
+|-------|-------|-------------|
+| `AbstractRepository` | N/A | Abstract base class, defines all method signatures, combines `FieldsVisibilityMixin` + `DefaultFilterMixin` |
+| `ReadableRepository` | `READ_ONLY` | Read-only operations (`find`, `findOne`, `findById`, `count`, `existsWith`). Write operations throw errors. |
+| `PersistableRepository` | `READ_WRITE` | Adds write operations (`create`, `update`, `delete`) with `UpdateBuilder` |
+| `DefaultCRUDRepository` | `READ_WRITE` | Extends `PersistableRepository` with no additional logic - **recommended default** |
+| `SoftDeletableRepository` | `READ_WRITE` | Extends `DefaultCRUDRepository` with soft delete + restore operations |
 
 ### Creating a Read-Only Repository
 
@@ -461,6 +553,15 @@ export class AuditLogRepository extends ReadableRepository<typeof AuditLog.schem
 }
 ```
 
+### Alias Methods
+
+`AbstractRepository` provides two alias methods for convenience:
+
+- `updateBy(opts)` - Alias for `updateAll(opts)`. Delegates directly.
+- `deleteBy(opts)` - Alias for `deleteAll(opts)`. Delegates directly.
+
+Both accept the same parameters (`where`, `data`/`options`) and support `shouldReturn` and `force` options.
+
 
 ## Default Filter Bypass
 
@@ -515,7 +616,7 @@ await tx.commit();
 
 ## Nested JSON Updates
 
-Repositories support updating specific fields within `json` or `jsonb` columns without overwriting the entire object. This is achieved using **JSON Path Notation** in the update data.
+Repositories support updating specific fields within `json` or `jsonb` columns without overwriting the entire object. This is achieved using **JSON Path Notation** in the update data via the `UpdateBuilder`.
 
 ### Basic Usage
 
@@ -540,9 +641,10 @@ await repo.updateById({
 
 - **Deep Nesting:** Update properties at any depth (e.g., `settings.display.font.size`).
 - **Array Access:** Update array elements by index (e.g., `tags[0]`).
-- **Auto-Creation:** Creates missing intermediate keys automatically.
-- **Type Safety:** Validates that the target column is a JSON type.
-- **Multiple Updates:** Chain multiple updates to the same or different columns.
+- **Auto-Creation:** Creates missing intermediate keys automatically (`jsonb_set` with `create_missing = true`).
+- **Type Safety:** Validates that the target column is a JSON/JSONB type.
+- **Multiple Updates:** Multiple updates to the same column are chained as nested `jsonb_set` calls.
+- **Mixed Updates:** Combine regular column updates with JSON path updates in a single call.
 
 ### Examples
 
@@ -580,7 +682,7 @@ await repo.updateById({
   data: {
     status: 'active',           // Regular column
     'metadata.lastLogin': now,  // JSON path
-    'preferences.lang': 'en'    // Another JSON path
+    'preferences.lang': 'en'   // Another JSON path
   }
 });
 ```
@@ -588,14 +690,34 @@ await repo.updateById({
 ### Security & Validation
 
 The framework validates JSON paths to prevent SQL injection:
-- **Allowed Characters:** Alphanumeric, underscores `_`, hyphens `-`, and brackets `[]`.
-- **Validation:** Invalid paths (e.g., containing SQL commands or special characters) throw an error before reaching the database.
-- **Values:** Values are safely serialized and parameterized.
+- **Allowed Characters:** Path components must match `/^[a-zA-Z_][a-zA-Z0-9_-]*$|^\d+$/` (identifiers, kebab-case, or array indices).
+- **Column Type Validation:** Only `json` and `jsonb` columns are allowed. Other column types throw an error.
+- **Values:** Values are serialized to JSONB literals with proper escaping.
 
 > [!NOTE]
 > This feature uses PostgreSQL's `jsonb_set` function. It is only available for columns defined as `json` or `jsonb`.
 
 
+## ExtraOptions Reference
+
+All repository operations accept an `options` parameter with these fields:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `transaction` | `ITransaction` | - | Transaction context for the operation |
+| `log` | `{ use: boolean; level?: TLogLevel }` | - | Enable operation logging |
+| `shouldSkipDefaultFilter` | `boolean` | `false` | Bypass the default filter from model settings |
+| `lock` | `TLockOptions` | - | Row-level locking (requires transaction, Core API only) |
+
+Write operations additionally support:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `shouldReturn` | `boolean` | `true` | Return the created/updated/deleted data |
+| `force` | `boolean` | `false` | Allow empty `where` condition on bulk operations |
+| `shouldQueryRange` | `boolean` | `false` | Return `{ data, range }` with total count (find only) |
+
+
 ## Quick Reference
 
 | Feature | Code |
@@ -605,9 +727,12 @@ The framework validates JSON paths to prevent SQL injection:
 | Commit | `await tx.commit()` |
 | Rollback | `await tx.rollback()` |
 | Bypass default filter | `options: { shouldSkipDefaultFilter: true }` |
+| Lock rows for update | `options: { transaction: tx, lock: { strength: 'update' } }` |
+| Lock + skip locked | `options: { transaction: tx, lock: { strength: 'update', config: { skipLocked: true } } }` |
 | Enable logging | `options: { log: { use: true, level: 'debug' } }` |
 | Force delete all | `options: { force: true }` |
 | Skip returning data | `options: { shouldReturn: false }` |
+| Get data + count | `options: { shouldQueryRange: true }` |
 | Access connector | `repo.getConnector()` |
 
 
@@ -618,6 +743,7 @@ The framework validates JSON paths to prevent SQL injection:
 - [Default Filter](../filter-system/default-filter.md) - Automatic filter configuration
 - [Repository Mixins](./mixins.md) - Composable features
 - [Relations & Includes](./relations.md) - Eager loading
+- [Soft-Deletable Repository](./soft-deletable.md) - Soft delete operations
 - [JSON Path Filtering](../filter-system/json-filtering) - JSONB queries
 - [Array Operators](../filter-system/array-operators) - PostgreSQL arrays
 
@@ -629,7 +755,7 @@ The framework validates JSON paths to prevent SQL injection:
   - [DataSources](/guides/core-concepts/persistent/datasources) - Database connections
 
 - **Related Topics:**
-  - [Repository Mixins](./mixins) - Soft delete and auditing
+  - [Repository Mixins](./mixins) - Composable mixin features
   - [Relations & Includes](./relations) - Loading related data
   - [Filter System](/references/base/filter-system/) - Query operators