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

package/wiki/references/base/controllers.md

@@ -329,29 +329,42 @@ This factory method returns a `BaseController` class that is already set up with
 
 ### Routes Configuration
 
-The `routes` option provides a unified way to configure both schema overrides and authentication for each endpoint:
+The `routes` option provides a unified way to configure request/response schemas and authentication for each endpoint:
 
 ```typescript
 type TRouteAuthConfig =
   | { skipAuth: true }
   | { skipAuth?: false; authStrategies: Array<TAuthStrategy> };
 
-type TReadRouteConfig = TRouteAuthConfig & { schema?: z.ZodObject };
-type TWriteRouteConfig = TReadRouteConfig & { requestBody?: z.ZodObject };
-type TDeleteRouteConfig = TRouteAuthConfig & { schema?: z.ZodObject };
+type TRequestConfig = {
+  query?: z.ZodObject;    // Custom query parameters
+  headers?: z.ZodObject;  // Custom headers
+  params?: z.ZodObject;   // Custom path parameters
+  body?: z.ZodObject;     // Custom request body (write routes only)
+};
+
+type TResponseConfig = {
+  schema?: z.ZodObject;   // Custom response body schema
+  headers?: z.ZodObject;  // Custom response headers
+};
+
+type TBaseRouteConfig = TRouteAuthConfig & {
+  request?: TRequestConfig;
+  response?: TResponseConfig;
+};
 ```
 
-| Route | Type | Description |
+| Route | Customizable Components | Description |
 | :--- | :--- | :--- |
-| `count` | `TReadRouteConfig` | Config for count endpoint |
-| `find` | `TReadRouteConfig` | Config for find endpoint |
-| `findOne` | `TReadRouteConfig` | Config for findOne endpoint |
-| `findById` | `TReadRouteConfig` | Config for findById endpoint |
-| `create` | `TWriteRouteConfig` | Config for create endpoint (supports `requestBody`) |
-| `updateById` | `TWriteRouteConfig` | Config for updateById endpoint (supports `requestBody`) |
-| `updateBy` | `TWriteRouteConfig` | Config for updateBy endpoint (supports `requestBody`) |
-| `deleteById` | `TDeleteRouteConfig` | Config for deleteById endpoint |
-| `deleteBy` | `TDeleteRouteConfig` | Config for deleteBy endpoint |
+| `count` | query, headers, response | Config for count endpoint |
+| `find` | query, headers, response | Config for find endpoint |
+| `findOne` | query, headers, response | Config for findOne endpoint |
+| `findById` | query, headers, params, response | Config for findById endpoint |
+| `create` | headers, body, response | Config for create endpoint |
+| `updateById` | headers, params, body, response | Config for updateById endpoint |
+| `updateBy` | query, headers, body, response | Config for updateBy endpoint |
+| `deleteById` | headers, params, response | Config for deleteById endpoint |
+| `deleteBy` | query, headers, response | Config for deleteBy endpoint |
 
 ### Auth Resolution Priority
 
@@ -397,17 +410,70 @@ const ArticleController = ControllerFactory.defineCrudController({
   },
 });
 
-// 4. Custom schema with auth configuration
+// 4. Custom request/response schemas with auth configuration
 const OrderController = ControllerFactory.defineCrudController({
   entity: OrderEntity,
   repository: { name: 'OrderRepository' },
   controller: { name: 'OrderController', basePath: '/orders' },
   authStrategies: ['jwt'],
   routes: {
-    find: { schema: CustomOrderListSchema, skipAuth: true },
+    find: {
+      skipAuth: true,
+      response: { schema: CustomOrderListSchema },
+    },
+    create: {
+      request: { body: CustomOrderCreateSchema },
+      response: { schema: CustomOrderResponseSchema },
+    },
+  },
+});
+```
+
+### Route Customization Examples
+
+```typescript
+import { z } from '@hono/zod-openapi';
+
+// Custom request body for create
+const CreateUserSchema = z.object({
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+  role: z.enum(['admin', 'user']).default('user'),
+});
+
+// Custom response schema (omit sensitive fields)
+const PublicUserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  role: z.string(),
+  createdAt: z.string(),
+});
+
+const UserController = ControllerFactory.defineCrudController({
+  entity: UserEntity,
+  repository: { name: 'UserRepository' },
+  controller: { name: 'UserController', basePath: '/users' },
+  authStrategies: ['jwt'],
+  routes: {
+    // Public read endpoints
+    find: {
+      skipAuth: true,
+      response: { schema: z.array(PublicUserSchema) },
+    },
+    findById: {
+      skipAuth: true,
+      response: { schema: PublicUserSchema },
+    },
+
+    // Custom create with custom body and response
     create: {
-      schema: CustomOrderResponseSchema,
-      requestBody: CustomOrderCreateSchema,
+      request: { body: CreateUserSchema },
+      response: { schema: PublicUserSchema },
+    },
+
+    // Delete requires JWT auth (uses default schema)
+    deleteById: {
+      authStrategies: ['jwt'],
     },
   },
 });
@@ -459,6 +525,137 @@ export class ConfigurationController extends _ConfigurationController {
 
 By leveraging these structured configuration options and the `ControllerFactory`, you ensure that your API is not only functional but also well-documented, easy to validate, and rapidly deployable for standard CRUD operations.
 
+### Overriding CRUD Methods with Strong Typing
+
+When extending a generated CRUD controller, you can override methods with full type safety using the helper types `THandlerContext` and `TInferSchema`.
+
+#### Helper Types
+
+| Type | Purpose |
+| :--- | :--- |
+| `THandlerContext<Definitions, Key>` | Extracts the strongly-typed Hono context for a specific route |
+| `TInferSchema<ZodSchema>` | Extracts TypeScript type from a Zod schema |
+
+#### Example: Full Controller Override Pattern
+
+```typescript
+import { Configuration } from '@/models';
+import { ConfigurationRepository } from '@/repositories';
+import {
+  Authentication,
+  BindingKeys,
+  BindingNamespaces,
+  controller,
+  ControllerFactory,
+  inject,
+  THandlerContext,
+  TInferSchema,
+} from '@venizia/ignis';
+import { z } from '@hono/zod-openapi';
+
+const BASE_PATH = '/configurations';
+
+// Custom request body schema
+const CreateConfigurationSchema = z.object({
+  code: z.string().min(1).max(100),
+  description: z.string().max(500).optional(),
+  group: z.string().min(1).max(50),
+});
+
+// Custom response schema
+const CreateResponseSchema = z.object({
+  id: z.string(),
+  code: z.string(),
+  message: z.string(),
+});
+
+// Define the CRUD controller with custom schemas
+const _Controller = ControllerFactory.defineCrudController({
+  repository: { name: ConfigurationRepository.name },
+  controller: { name: 'ConfigurationController', basePath: BASE_PATH },
+  authStrategies: [Authentication.STRATEGY_JWT],
+  entity: () => Configuration,
+  routes: {
+    count: { skipAuth: true },
+    create: {
+      request: { body: CreateConfigurationSchema },
+      response: { schema: CreateResponseSchema },
+    },
+  },
+});
+
+// Extract definitions type for method overrides
+type TRouteDefinitions = InstanceType<typeof _Controller>['definitions'];
+
+@controller({ path: BASE_PATH })
+export class ConfigurationController extends _Controller {
+  constructor(
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.REPOSITORY,
+        key: ConfigurationRepository.name,
+      }),
+    })
+    repository: ConfigurationRepository,
+  ) {
+    super(repository);
+  }
+
+  // Override with full type safety
+  override async create(opts: { context: THandlerContext<TRouteDefinitions, 'CREATE'> }) {
+    const { context } = opts;
+
+    // Get typed request body using TInferSchema
+    const data = context.req.valid('json') as TInferSchema<typeof CreateConfigurationSchema>;
+
+    // Access typed properties
+    this.logger.info('[create] code: %s, group: %s', data.code, data.group);
+
+    // Custom business logic here...
+
+    // Call parent or return custom response
+    return super.create(opts);
+  }
+
+  // Override updateById
+  override async updateById(opts: { context: THandlerContext<TRouteDefinitions, 'UPDATE_BY_ID'> }) {
+    const { context } = opts;
+    const { id } = context.req.valid('param');
+    const data = context.req.valid('json');
+
+    this.logger.info('[updateById] id: %s', id);
+
+    return super.updateById(opts);
+  }
+
+  // Override deleteById with audit logging
+  override async deleteById(opts: { context: THandlerContext<TRouteDefinitions, 'DELETE_BY_ID'> }) {
+    const { context } = opts;
+    const { id } = context.req.valid('param');
+
+    this.logger.warn('[deleteById] Deleting id: %s', id);
+
+    return super.deleteById(opts);
+  }
+}
+```
+
+#### Available Route Keys
+
+Use these keys with `THandlerContext`:
+
+| Key | Method | Path |
+| :--- | :--- | :--- |
+| `'COUNT'` | GET | /count |
+| `'FIND'` | GET | / |
+| `'FIND_BY_ID'` | GET | /:id |
+| `'FIND_ONE'` | GET | /find-one |
+| `'CREATE'` | POST | / |
+| `'UPDATE_BY_ID'` | PATCH | /:id |
+| `'UPDATE_BY'` | PATCH | / |
+| `'DELETE_BY_ID'` | DELETE | /:id |
+| `'DELETE_BY'` | DELETE | / |
+
 ---
 
 ## See Also
@@ -471,14 +668,13 @@ By leveraging these structured configuration options and the `ControllerFactory`
   - [Dependency Injection](./dependency-injection.md) - DI patterns and injection
 
 - **Guides:**
-  - [Building Your First API](/guides/getting-started/first-api.md)
-  - [Controllers Guide](/guides/core-concepts/controllers.md)
-  - [Routing and Decorators](/guides/core-concepts/routing.md)
+  - [Controllers Guide](/guides/core-concepts/controllers)
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api)
 
 - **Best Practices:**
-  - [API Design Patterns](/best-practices/architecture/api-design.md)
-  - [Error Handling](/best-practices/architecture/error-handling.md)
-  - [Request Validation](/best-practices/security/input-validation.md)
+  - [API Usage Examples](/best-practices/api-usage-examples)
+  - [Troubleshooting Tips](/best-practices/troubleshooting-tips)
+  - [Security Guidelines](/best-practices/security-guidelines)
 
 - **External Resources:**
   - [OpenAPI Specification](https://swagger.io/specification/)

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

@@ -140,6 +140,72 @@ const filter = {
 ```
 
 
+## Range Queries (Content-Range Header)
+
+When building paginated APIs, you often need to return the total count alongside the data for pagination UI. Use `shouldQueryRange: true` to get range information following the HTTP Content-Range standard.
+
+### Basic Usage
+
+```typescript
+const result = await repo.find({
+  filter: { limit: 10, skip: 20 },
+  options: { shouldQueryRange: true }
+});
+
+// Result structure:
+// {
+//   data: [...],  // Array of records
+//   range: {
+//     start: 20,   // Starting index (inclusive)
+//     end: 29,     // Ending index (inclusive)
+//     total: 100   // Total matching records
+//   }
+// }
+```
+
+### Setting HTTP Headers
+
+Use the range information to set standard HTTP headers:
+
+```typescript
+const { data, range } = await repo.find({
+  filter: { limit: 10, skip: 20, where: { status: 'active' } },
+  options: { shouldQueryRange: true }
+});
+
+// Format: "records start-end/total"
+const contentRange = data.length > 0
+  ? `records ${range.start}-${range.end}/${range.total}`
+  : `records */${range.total}`;
+
+res.setHeader('Content-Range', contentRange);
+// → "records 20-29/100"
+```
+
+### TDataRange Type
+
+```typescript
+type TDataRange = {
+  start: number;  // Starting index (0-based, inclusive)
+  end: number;    // Ending index (0-based, inclusive)
+  total: number;  // Total count matching the query
+};
+```
+
+### Content-Range Format Reference
+
+| Scenario | Content-Range Header |
+|----------|---------------------|
+| Items 0-9 of 100 | `records 0-9/100` |
+| Items 20-29 of 100 | `records 20-29/100` |
+| No items found | `records */0` |
+| Last page (items 90-99) | `records 90-99/100` |
+
+### Performance Note
+
+When `shouldQueryRange: true`, the repository executes the data query and count query **in parallel** using `Promise.all` for optimal performance.
+
+
 ## Combined Example
 
 ```typescript
@@ -153,3 +219,21 @@ await repo.find({
   }
 });
 ```
+
+### With Range Information
+
+```typescript
+const { data, range } = await repo.find({
+  filter: {
+    where: { status: 'active' },
+    fields: ['id', 'name', 'price', 'createdAt'],
+    order: ['price ASC', 'createdAt DESC'],
+    limit: 20,
+    skip: 0
+  },
+  options: { shouldQueryRange: true }
+});
+
+console.log(`Showing ${range.start}-${range.end} of ${range.total}`);
+// → "Showing 0-19 of 150"
+```

package/wiki/references/base/middlewares.md

@@ -51,9 +51,10 @@ The error handler middleware catches all unhandled errors in your application an
 
 - **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
 - **Request Tracking**: Includes `requestId` for debugging and tracing
-- **Status Code Detection**: Automatically extracts HTTP status codes from errors
+- **Status Code Detection**: Automatically extracts `statusCode` from errors
 
 #### Usage
 
@@ -110,6 +111,37 @@ app.onError(appErrorHandler({
 }
 ```
 
+**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:
+
+```json
+{
+  "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
+  }
+}
+```
+
+**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 |
+
 #### API Reference
 
 ##### `appErrorHandler(options)`
@@ -594,8 +626,10 @@ Error handlers log every error. For high error rates, consider:
   - [Dependency Injection](./dependency-injection.md) - DI container and providers
 
 - **Guides:**
-  - [Building Your First API](/guides/getting-started/first-api.md)
-  - [Error Handling Best Practices](/best-practices/architecture/error-handling.md)
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api)
+
+- **Best Practices:**
+  - [Troubleshooting Tips](/best-practices/troubleshooting-tips)
 
 - **External Resources:**
   - [Hono Middleware Documentation](https://hono.dev/docs/guides/middleware)

package/wiki/references/base/models.md

@@ -709,6 +709,7 @@ generateUserAuditColumnDefs(opts?: TUserAuditEnricherOptions): {
 type TUserAuditColumnOpts = {
   dataType: 'string' | 'number';  // Required - type of user ID
   columnName: string;              // Column name in database
+  allowAnonymous?: boolean;        // Allow null user ID (default: true)
 };
 
 type TUserAuditEnricherOptions = {
@@ -718,8 +719,27 @@ type TUserAuditEnricherOptions = {
 ```
 
 **Default values:**
-- `created`: `{ dataType: 'number', columnName: 'created_by' }`
-- `modified`: `{ dataType: 'number', columnName: 'modified_by' }`
+- `created`: `{ dataType: 'number', columnName: 'created_by', allowAnonymous: true }`
+- `modified`: `{ dataType: 'number', columnName: 'modified_by', allowAnonymous: true }`
+
+#### `allowAnonymous` Behavior
+
+The `allowAnonymous` option controls whether the enricher requires an authenticated user context:
+
+| `allowAnonymous` | No Context | No User ID | Has User ID |
+|------------------|------------|------------|-------------|
+| `true` (default) | Returns `null` | Returns `null` | Returns user ID |
+| `false` | Throws error | Throws error | Returns user ID |
+
+**When to use `allowAnonymous: false`:**
+- Sensitive audit trails that must track the responsible user
+- Tables where anonymous operations should be forbidden
+- Compliance requirements that mandate user attribution
+
+**When to use `allowAnonymous: true` (default):**
+- Background jobs, migrations, or seed scripts without user context
+- System-generated records
+- Tables that allow both authenticated and anonymous operations
 
 #### Generated Columns
 
@@ -795,6 +815,24 @@ export const myTable = pgTable('MyTable', {
 // modifiedBy: integer('editor_id')
 ```
 
+**Requiring authenticated user (allowAnonymous: false):**
+
+```typescript
+// For sensitive tables that must track the responsible user
+export const auditLogTable = pgTable('AuditLog', {
+  ...generateIdColumnDefs(),
+  ...generateUserAuditColumnDefs({
+    created: { dataType: 'number', columnName: 'created_by', allowAnonymous: false },
+    modified: { dataType: 'number', columnName: 'modified_by', allowAnonymous: false },
+  }),
+  action: text('action').notNull(),
+  details: text('details'),
+});
+
+// If no authenticated user context is available, throws:
+// Error: [getCurrentUserId] Invalid request context to identify user | columnName: createdBy | allowAnonymous: false
+```
+
 
 ## Schema Utilities
 

package/wiki/references/base/providers.md

@@ -724,8 +724,7 @@ export class ConfigProvider extends BaseProvider<Config> {
   - [Building Services](/guides/core-concepts/services.md)
 
 - **Best Practices:**
-  - [Dependency Injection Patterns](/best-practices/architecture/dependency-injection.md)
-  - [Service Layer Patterns](/best-practices/architecture/service-patterns.md)
+  - [Architectural Patterns](/best-practices/architectural-patterns)
 
 - **External Resources:**
   - [Factory Pattern](https://refactoring.guru/design-patterns/factory-method)

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

@@ -39,6 +39,7 @@ export class TodoRepository extends DefaultCRUDRepository<typeof Todo.schema> {
 | Method | Description | Example |
 |--------|-------------|---------|
 | `find(opts)` | Find multiple records | `repo.find({ filter: { where: { status: 'active' } } })` |
+| `find(opts)` with range | Find with pagination range | `repo.find({ filter, options: { shouldQueryRange: true } })` |
 | `findOne(opts)` | Find single record | `repo.findOne({ filter: { where: { email } } })` |
 | `findById(opts)` | Find by primary key | `repo.findById({ id: '123' })` |
 | `count(opts)` | Count matching records | `repo.count({ where: { status: 'active' } })` |
@@ -186,6 +187,7 @@ await repo.deleteAll({ where: {}, options: { force: true } });
 | Want to... | Code |
 |------------|------|
 | Find all active | `repo.find({ filter: { where: { status: 'active' } } })` |
+| Find with range info | `repo.find({ filter, options: { shouldQueryRange: true } })` |
 | Find by ID | `repo.findById({ id: '123' })` |
 | Find with relations | `repo.find({ filter: { include: [{ relation: 'posts' }] } })` |
 | Create one | `repo.create({ data: { name: 'John' } })` |
@@ -207,7 +209,7 @@ await repo.deleteAll({ where: {}, options: { force: true } });
   - [Repositories Guide](/guides/core-concepts/persistent/repositories) - Creating repositories tutorial
   - [Models](/guides/core-concepts/persistent/models) - Entity definitions used by repositories
   - [DataSources](/guides/core-concepts/persistent/datasources) - Database connections
-  - [Services](/guides/core-concepts/persistent/services) - Use repositories for data access
+  - [Services](/guides/core-concepts/services) - Use repositories for data access
   - [Transactions](/guides/core-concepts/persistent/transactions) - Multi-operation consistency
 
 - **Repository Topics:**

package/wiki/references/base/services.md

@@ -117,5 +117,5 @@ By adhering to this pattern, you keep your code organized, testable, and maintai
   - [Dependency Injection Guide](/guides/core-concepts/dependency-injection.md)
 
 - **Best Practices:**
-  - [Service Layer Patterns](/best-practices/architecture/service-patterns.md)
-  - [Testing Services](/best-practices/testing/unit-testing.md)
+  - [Architectural Patterns](/best-practices/architectural-patterns)
+  - [Testing Guide](/guides/tutorials/testing)