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

package/wiki/guides/tutorials/complete-installation.md

@@ -19,15 +19,15 @@ bun init -y
 ### Production Dependencies
 
 ```bash
-bun add hono @hono/zod-openapi @scalar/hono-api-reference @venizia/ignis dotenv-flow
+bun add hono @hono/zod-openapi @scalar/hono-api-reference @venizia/ignis @venizia/ignis-helpers
 ```
 
 **What each package does:**
 - `hono` - High-performance web framework
 - `@hono/zod-openapi` - OpenAPI schema generation with Zod validation
 - `@scalar/hono-api-reference` - Interactive API documentation UI
-- `@venizia/ignis` - Core Ignis framework
-- `dotenv-flow` - Environment variable management
+- `@venizia/ignis` - Core Ignis framework (application, controllers, repositories, DI)
+- `@venizia/ignis-helpers` - Utilities (HTTP constants, logger, environment helpers)
 
 ### Development Dependencies
 
@@ -121,7 +121,7 @@ This setup might seem verbose compared to minimal frameworks. The trade-off: ~50
 ### Create Project Structure
 
 ```bash
-mkdir -p src/{common,components,configurations,controllers,datasources,helpers,models/{entities,requests,responses},repositories,services,utilities}
+mkdir -p src/{common,components,configurations,controllers/hello,datasources,helpers,models/{entities,requests,responses},repositories,services,utilities}
 ```
 
 Your structure will look like:
@@ -137,7 +137,10 @@ src/
 │   └── index.ts            # App configuration files
 ├── controllers/
 │   ├── index.ts            # Export all controllers
-│   └── hello.controller.ts
+│   └── hello/
+│       ├── definitions.ts  # Route configs, schemas, constants
+│       ├── hello.controller.ts
+│       └── index.ts        # Barrel export
 ├── datasources/
 │   └── index.ts            # Database connections
 ├── helpers/
@@ -155,6 +158,8 @@ src/
     └── index.ts            # Utility functions
 ```
 
+Each controller gets its own folder: `definitions.ts` for route configs and Zod schemas, the controller file itself, and an `index.ts` barrel export. This keeps things organized as controllers grow with custom routes, validations, and transformations.
+
 > **Note:** For this guide, we only use `controllers/`. Other folders will be used in the [CRUD Tutorial](./building-a-crud-api.md) when you add database support.
 
 ### Create Application Class
@@ -163,7 +168,7 @@ Create `src/application.ts` - this is where you configure and register all your
 
 ```typescript
 import { BaseApplication, IApplicationConfigs, IApplicationInfo, SwaggerComponent, ValueOrPromise } from '@venizia/ignis';
-import { HelloController } from './controllers/hello.controller';
+import { HelloController } from './controllers';
 import packageJson from '../package.json';
 
 // Define application configurations
@@ -255,22 +260,39 @@ export class Application extends BaseApplication {
 
 ### Create Controller
 
-Create `src/controllers/hello.controller.ts` - controllers handle HTTP requests and return responses:
+Each controller lives in its own folder with separate files for definitions, logic, and exports.
+
+Create `src/controllers/hello/definitions.ts` — route configs and schemas:
 
 ```typescript
-import {
-  BaseRestController,
-  controller,
-  api,
-  jsonContent,
-} from '@venizia/ignis';
+import { jsonContent } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
 import { z } from '@hono/zod-openapi';
-import { Context } from 'hono';
 
-const BASE_PATH = '/hello';
+export const BASE_PATH = '/hello';
+
+export const helloRouteConfigs = {
+  sayHello: {
+    method: HTTP.Methods.GET,
+    path: '/',
+    responses: {
+      [HTTP.ResultCodes.RS_2.Ok]: jsonContent({
+        description: 'A simple hello message',
+        schema: z.object({ message: z.string() }),
+      }),
+    },
+  },
+} as const;
+```
+
+Create `src/controllers/hello/hello.controller.ts` — the controller class:
+
+```typescript
+import { BaseRestController, controller, api } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
+import { Context } from 'hono';
+import { BASE_PATH, helloRouteConfigs } from './definitions';
 
-// The @controller decorator registers this class as a controller
 // All routes in this controller will be under /api/hello (remember path.base: '/api')
 @controller({ path: BASE_PATH })
 export class HelloController extends BaseRestController {
@@ -278,47 +300,38 @@ export class HelloController extends BaseRestController {
     super({ scope: HelloController.name, path: BASE_PATH });
   }
 
-  // Required: Override binding() to register routes or dependencies
-  override binding() {
-    // Option 1: Use bindRoute() or defineRoute() for programmatic route registration
-    // this.bindRoute({ configs: { method: 'get', path: '/programmatic', responses: {...} } }).to({ handler: this.myHandler });
-
-    // Option 2: Use @api decorator on methods (shown below) - recommended
-  }
+  // Override binding() to register custom routes via bindRoute() or defineRoute().
+  // For decorator-based routes (@api, @get, @post), this can be empty.
+  override binding() {}
 
-  // The @api decorator defines a route with explicit method. You can also use @get/@post shorthand decorators.
-  @api({
-    configs: {
-      method: HTTP.Methods.GET,
-      path: '/',
-      // This 'responses' config does two things:
-      // 1. Generates OpenAPI/Swagger documentation automatically
-      // 2. Validates that your handler returns the correct shape
-      responses: {
-        [HTTP.ResultCodes.RS_2.Ok]: jsonContent({
-          description: 'A simple hello message',
-          schema: z.object({ message: z.string() }),
-        }),
-      },
-    },
-  })
+  @api({ configs: helloRouteConfigs.sayHello })
   sayHello(c: Context) {
     return c.json({ message: 'Hello, World!' }, HTTP.ResultCodes.RS_2.Ok);
   }
-
-  // For authenticated endpoints, add 'authenticate':
-  // @api({ configs: { method: HTTP.Methods.GET, path: '/secure', authenticate: { strategies: [Authentication.STRATEGY_JWT] } } })
 }
 ```
 
+Create `src/controllers/hello/index.ts` — barrel export:
+
+```typescript
+export * from './hello.controller';
+```
+
+Create `src/controllers/index.ts` — export all controllers:
+
+```typescript
+export * from './hello';
+```
+
 **Controller Patterns:**
 
 | Pattern | Description |
 |---------|-------------|
-| `@controller` | Registers the class as a controller with a base path. Supports optional `transport` field (`'rest'` default, `'grpc'`) |
+| `definitions.ts` | Route configs, Zod schemas, and constants — keeps controller file clean |
+| `@controller` | Registers the class as a controller with a base path |
 | `@api` | Defines a route with `method` specified in configs |
 | `@get`, `@post`, etc. | Shorthand decorators that auto-set the HTTP method (recommended) |
-| `binding()` | Required override — use `bindRoute()` or `defineRoute()` for programmatic routes |
+| `binding()` | Override for programmatic routes via `bindRoute()` / `defineRoute()`. Empty for decorator-based routes |
 | Zod schemas | Provide automatic validation and OpenAPI docs |
 
 > **Deep Dive:** See [Controllers Reference](../core-concepts/rest-controllers.md) for advanced routing patterns and validation.
@@ -341,6 +354,10 @@ const main = async () => {
 
   const applicationName = process.env.APP_ENV_APPLICATION_NAME?.toUpperCase() ?? 'My-App';
   logger.info('[main] Getting ready to start up %s Application...', applicationName);
+
+  // start() runs the full lifecycle automatically:
+  // staticConfigure → preConfigure → registerDataSources → registerComponents
+  // → registerControllers → postConfigure → setupMiddlewares → HTTP server
   await application.start();
   return application;
 };
@@ -348,6 +365,9 @@ const main = async () => {
 export default main();
 ```
 
+> [!TIP]
+> `start()` runs the full lifecycle internally. You only need the explicit `init()` → `boot()` → `start()` sequence when using **auto-discovery** (glob-based booters) to discover controllers/repositories from the filesystem. For manual registration (as shown here), `start()` alone is sufficient.
+
 ## 5. Run Your Application
 
 Add common application scripts to your `package.json`:

package/wiki/guides/tutorials/ecommerce-api.md

@@ -28,7 +28,7 @@ cd ecommerce-api
 bun init -y
 
 # Install dependencies
-bun add hono @hono/zod-openapi @venizia/ignis dotenv-flow
+bun add hono @hono/zod-openapi @venizia/ignis @venizia/ignis-helpers
 bun add drizzle-orm drizzle-zod pg stripe
 bun add -d typescript @types/bun @venizia/dev-configs drizzle-kit @types/pg
 ```
@@ -57,9 +57,19 @@ ecommerce-api/
 │   │   ├── order.service.ts
 │   │   └── payment.service.ts
 │   ├── controllers/
-│   │   ├── product.controller.ts
-│   │   ├── cart.controller.ts
-│   │   └── order.controller.ts
+│   │   ├── product/
+│   │   │   ├── definitions.ts
+│   │   │   ├── product.controller.ts
+│   │   │   └── index.ts
+│   │   ├── cart/
+│   │   │   ├── definitions.ts
+│   │   │   ├── cart.controller.ts
+│   │   │   └── index.ts
+│   │   ├── order/
+│   │   │   ├── definitions.ts
+│   │   │   ├── order.controller.ts
+│   │   │   └── index.ts
+│   │   └── index.ts
 │   └── datasources/
 │       └── postgres.datasource.ts
 └── package.json
@@ -314,7 +324,6 @@ export * from './order.model';
 import {
   BaseDataSource,
   datasource,
-  TNodePostgresConnector,
   ValueOrPromise,
 } from '@venizia/ignis';
 import { drizzle } from 'drizzle-orm/node-postgres';
@@ -329,7 +338,7 @@ interface IDSConfigs {
 }
 
 @datasource({ driver: 'node-postgres' })
-export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
@@ -915,7 +924,7 @@ export class PaymentService extends BaseService {
 ### Product Controller
 
 ```typescript
-// src/controllers/product.controller.ts
+// src/controllers/product/product.controller.ts
 import { z } from '@hono/zod-openapi';
 import {
   BaseRestController,
@@ -1003,7 +1012,7 @@ export class ProductController extends BaseRestController {
 ### Cart Controller
 
 ```typescript
-// src/controllers/cart.controller.ts
+// src/controllers/cart/cart.controller.ts
 import { z } from '@hono/zod-openapi';
 import {
   BaseRestController,
@@ -1142,7 +1151,7 @@ export class CartController extends BaseRestController {
 ### Order Controller
 
 ```typescript
-// src/controllers/order.controller.ts
+// src/controllers/order/order.controller.ts
 import { z } from '@hono/zod-openapi';
 import {
   BaseRestController,
@@ -1265,9 +1274,9 @@ export class OrderController extends BaseRestController {
 import { BaseApplication, IApplicationInfo } from '@venizia/ignis';
 import { HealthCheckComponent, SwaggerComponent } from '@venizia/ignis';
 
-import { ProductController } from './controllers/product.controller';
-import { CartController } from './controllers/cart.controller';
-import { OrderController } from './controllers/order.controller';
+import { ProductController } from './controllers/product';
+import { CartController } from './controllers/cart';
+import { OrderController } from './controllers/order';
 
 import { ProductService } from './services/product.service';
 import { CartService } from './services/cart.service';

package/wiki/guides/tutorials/realtime-chat.md

@@ -25,7 +25,7 @@ cd chat-api
 bun init -y
 
 # Install dependencies
-bun add hono @hono/zod-openapi @venizia/ignis dotenv-flow
+bun add hono @hono/zod-openapi @venizia/ignis @venizia/ignis-helpers
 bun add drizzle-orm drizzle-zod pg
 bun add -d typescript @types/bun @venizia/dev-configs drizzle-kit @types/pg
 
@@ -241,7 +241,6 @@ export * from './message.model';
 import {
   BaseDataSource,
   datasource,
-  TNodePostgresConnector,
   ValueOrPromise,
 } from '@venizia/ignis';
 import { drizzle } from 'drizzle-orm/node-postgres';
@@ -256,7 +255,7 @@ interface IDSConfigs {
 }
 
 @datasource({ driver: 'node-postgres' })
-export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
@@ -953,7 +952,7 @@ import {
   SocketIOServerHelper,
 } from '@venizia/ignis-helpers';
 import { ChatService } from './services/chat.service';
-import { ChatController } from './controllers/chat.controller';
+import { ChatController } from './controllers/chat';
 import { UserRepository } from './repositories/user.repository';
 import { RoomRepository, RoomMemberRepository } from './repositories/room.repository';
 import { MessageRepository, DirectMessageRepository } from './repositories/message.repository';
@@ -1124,7 +1123,7 @@ Client connects → 'authenticate' event → authenticateFn() → 'authenticated
 ## 7. REST API for Chat History
 
 ```typescript
-// src/controllers/chat.controller.ts
+// src/controllers/chat/chat.controller.ts
 import { z } from '@hono/zod-openapi';
 import {
   BaseRestController,

package/wiki/references/base/filter-system/default-filter.md

@@ -299,13 +299,13 @@ export class Subscription extends BaseEntity<typeof Subscription.schema> {}
 
 ### Query Limit Protection
 
+Use the dedicated `settings.defaultLimit` to raise (or lower) the per-model default page size. Prefer it over putting `limit` inside `defaultFilter`:
+
 ```typescript
 @model({
   type: 'entity',
   settings: {
-    defaultFilter: {
-      limit: 1000,  // Prevent unbounded queries
-    },
+    defaultLimit: 1000,  // Per-model default when a query omits `limit`
   },
 })
 export class LogEntry extends BaseEntity<typeof LogEntry.schema> {}
@@ -315,6 +315,9 @@ await logRepo.find({ filter: {} });           // LIMIT 1000
 await logRepo.find({ filter: { limit: 50 } }); // LIMIT 50
 ```
 
+> [!TIP]
+> `defaultLimit` is independent of `defaultFilter`: bypassing the default filter via `shouldSkipDefaultFilter` does **not** drop the limit. See [Pagination → Default Limit](/references/base/filter-system/fields-order-pagination#default-limit).
+
 
 ## Relation Include Default Filters
 

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

@@ -132,6 +132,32 @@ await repo.find({
 > [!TIP]
 > Always use `limit` for public-facing endpoints to prevent memory exhaustion. The default limit is 10 if not specified.
 
+### Default Limit
+
+When a query omits `limit`, the repository resolves one with this precedence:
+
+```
+query.limit  ??  model settings.defaultLimit  ??  DEFAULT_LIMIT (10)
+```
+
+- **`query.limit`** — an explicit `limit` in the filter always wins.
+- **`settings.defaultLimit`** — a per-model default set on the `@model` decorator. Must be a positive integer (validated at decoration time). Applies to top-level `find()` and to every to-many relation (using the related model's own `defaultLimit`).
+- **`DEFAULT_LIMIT`** — the global fallback, `10`.
+
+```typescript
+@model({
+  type: 'entity',
+  settings: { defaultLimit: 200 },  // Small lookup table — default to 200 rows
+})
+export class Country extends BaseEntity<typeof Country.schema> {}
+
+await countryRepo.find({ filter: {} });            // LIMIT 200
+await countryRepo.find({ filter: { limit: 10 } }); // LIMIT 10  (explicit wins)
+```
+
+> [!NOTE]
+> `defaultLimit` is independent of `defaultFilter`: passing `shouldSkipDefaultFilter` to bypass the default `where` clause does **not** drop the default limit. There is no "unbounded" sentinel — to fetch more rows, pass an explicit `limit`.
+
 ### Pagination Helper
 
 ```typescript

package/wiki/references/base/models.md

@@ -51,6 +51,7 @@ 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
+    defaultLimit?: number,        // Default row limit when a query omits `limit`
     authorize?: {                  // Authorization settings
       principal: string,           // Authorization subject name
       [extra: string | symbol]: any, // Extensible metadata
@@ -66,15 +67,17 @@ 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.defaultLimit` | `number` | Default row limit applied when a query omits `limit`. Must be a positive integer (validated at decoration time). Falls back to the global `DEFAULT_LIMIT` (10). See [Pagination](/references/base/filter-system/fields-order-pagination#default-limit) |
 | `settings.authorize` | `IModelAuthorizeSettings` | Authorization settings — declares the model's authorization principal (see [Authorization](/extensions/components/authorization/usage#model-based-resource-references)) |
 | `settings.authorize.principal` | `string` | The authorization subject name for this model. Auto-populates `AUTHORIZATION_SUBJECT` static property |
 
 #### `@model` Behavior
 
 When the `@model` decorator is applied:
-1. If `settings.authorize.principal` is provided and `AUTHORIZATION_SUBJECT` is not already defined on the class, it auto-populates `AUTHORIZATION_SUBJECT` with the principal value
-2. The model is registered in the `MetadataRegistry` model registry, keyed by table name (resolved as: `metadata.tableName` > `static TABLE_NAME` > class name)
-3. The static `relations` property is stored as a resolver (not immediately resolved) to avoid circular dependency issues between models
+1. If `settings.defaultLimit` is provided, it is validated to be a positive integer — otherwise the decorator throws at decoration (boot) time
+2. If `settings.authorize.principal` is provided and `AUTHORIZATION_SUBJECT` is not already defined on the class, it auto-populates `AUTHORIZATION_SUBJECT` with the principal value
+3. The model is registered in the `MetadataRegistry` model registry, keyed by table name (resolved as: `metadata.tableName` > `static TABLE_NAME` > class name)
+4. The static `relations` property is stored as a resolver (not immediately resolved) to avoid circular dependency issues between models
 
 ### Hidden Properties
 

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.
@@ -599,6 +707,7 @@ All repository operations accept an `options` parameter with these fields:
 | `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:
 
@@ -618,6 +727,8 @@ Write operations additionally support:
 | 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 }` |