@venizia/ignis-docs 0.0.8-1 → 0.0.8-3

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

@@ -43,14 +43,14 @@ IGNIS provides a collection of built-in middlewares for common application needs
 
 The error handler middleware catches all unhandled errors in your application and formats them into consistent JSON responses.
 
-**File:** `packages/core/src/base/middlewares/app-error.middleware.ts`
+**File:** `packages/core/src/base/middlewares/app-error/app-error.middleware.ts`
 
 #### Features
 
 - **Automatic Error Formatting**: Converts all errors to structured JSON responses
-- **ZodError Support**: Special handling for Zod validation errors with detailed field-level messages
-- **Database Error Handling**: Automatically returns 400 for database constraint violations (unique, foreign key, not null, etc.)
-- **Environment-Aware**: Hides stack traces and error causes in production
+- **ZodError Support**: Validation errors surface a schema-driven `messageCode` and `message` (from `params.code`, else the raw Zod code), with the full per-field list under `details.cause`
+- **Database Error Handling**: Returns 400 for SQLSTATE class `22` (data exception) and `23` (integrity) errors, with a fallback message; other classes (e.g. `42` programming errors) stay 500
+- **Production-Safe**: Hides stack traces, error causes, DB driver internals (`detail`/`table`/`constraint`), and raw system messages in production
 - **Request Tracking**: Includes `requestId` for debugging and tracing
 - **Status Code Detection**: Automatically extracts `statusCode` from errors
 
@@ -87,9 +87,13 @@ app.onError(appErrorHandler({
 ```
 
 **Validation Error (ZodError):**
+
+Top-level `message`/`messageCode` come from the first failing issue — its `params.code` if the schema set one (see below), otherwise its raw Zod code. The full per-field list stays under `details.cause`. If `error.rootKey` is configured, the whole body is wrapped under that key.
+
 ```json
 {
-  "message": "ValidationError",
+  "message": "Invalid email address",
+  "messageCode": "invalid_type",
   "statusCode": 422,
   "requestId": "abc123",
   "details": {
@@ -100,45 +104,50 @@ app.onError(appErrorHandler({
       {
         "path": "email",
         "message": "Invalid email address",
-        "code": "invalid_string",
-        "expected": "string",
-        "received": "undefined"
+        "code": "invalid_type",
+        "expected": "string"
       }
     ]
   }
 }
 ```
 
+To emit a stable, domain-specific `messageCode`, attach `params.code` to a custom check:
+
+```typescript
+z.string().refine(isEmail, { message: 'Invalid email address', params: { code: 'user.email.invalid' } });
+// → "messageCode": "user.email.invalid"
+```
+
 **Database Constraint Error:**
 
-Database constraint violations (unique, foreign key, not null, check) are automatically detected and returned as 400 Bad Request with a human-readable message:
+Database errors in SQLSTATE class `22` (data exception) and `23` (integrity constraint) are detected by **class** and returned as 400 Bad Request. A known code uses its specific message; any other in-class code uses `DATABASE_CLIENT_ERROR_FALLBACK_MESSAGE` (`"Invalid database request"`).
 
 ```json
+// non-production — full driver context for debugging
 {
   "message": "Unique constraint violation\nDetail: Key (email)=(test@example.com) already exists.\nTable: User\nConstraint: UQ_User_email",
   "statusCode": 400,
   "requestId": "abc123",
-  "details": {
-    "url": "http://localhost:3000/api/users",
-    "path": "/api/users",
-    "stack": "...",  // development only
-    "cause": { ... }  // development only
-  }
+  "details": { "url": "...", "path": "/api/users", "stack": "...", "cause": { } }
 }
 ```
 
-**Supported PostgreSQL Error Codes:**
-
-| Code | Error Type |
-|------|------------|
-| 23505 | Unique constraint violation |
-| 23503 | Foreign key constraint violation |
-| 23502 | Not null constraint violation |
-| 23514 | Check constraint violation |
-| 23P01 | Exclusion constraint violation |
-| 22P02 | Invalid text representation |
-| 22003 | Numeric value out of range |
-| 22001 | String data too long |
+:::warning Production sanitizes database internals
+In **production** the message is the base message only — `Detail:`/`Table:`/`Constraint:` are stripped (they echo row values and schema names), and `details.stack`/`details.cause` are omitted. Codes outside class 22/23 (e.g. `42703` undefined column) and connection failures return a generic `"Internal Server Error"`, so SQL, schema names, and connection host/port never leak.
+:::
+
+**Database client error classes** — codes in SQLSTATE class `22` (data exception), `23` (integrity constraint), and `44` (WITH CHECK OPTION) map to HTTP 400. Common codes get a specific message; any other in-class code uses the fallback (`"Invalid database request"`).
+
+| Class | Codes with a specific message |
+|-------|-------------------------------|
+| `23` Integrity | `23505` unique · `23503` foreign key · `23502` not null · `23514` check · `23P01` exclusion · `23000` integrity · `23001` restrict |
+| `22` Data exception | `22001` string too long · `22003` numeric range · `22004` null not allowed · `22007` datetime format · `22008` datetime overflow · `22009` tz displacement · `22011` substring · `22012` division by zero · `22023` invalid parameter · `22025` invalid escape · `22026` length mismatch · `22030` duplicate JSON key · `22032` invalid JSON · `22P01` floating-point · `22P02` invalid text · `22P03` invalid binary · `22P05` untranslatable char |
+| `44` View check | `44000` WITH CHECK OPTION violation |
+
+:::tip Transient conflicts return 409, not 400/500
+Class `40` (`40001` serialization failure, `40P01` deadlock) is **transient/retryable** and returns **409 Conflict** with `messageCode: "database.conflict"` and a safe "please retry" message — the client can safely retry the same request. Programming/infra classes (`42` syntax, `53` resources, `0A`, `25`, `28`) remain 500.
+:::
 
 #### API Reference
 

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