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

package/wiki/changelogs/2026-01-05-range-queries-content-range.md

@@ -0,0 +1,184 @@
+---
+title: Range Queries & Content-Range Header
+description: Added shouldQueryRange option for paginated API responses with HTTP Content-Range standard support
+---
+
+# Changelog - 2026-01-05
+
+## Range Queries & Content-Range Header
+
+This release adds the `shouldQueryRange` option to the `find()` method, enabling paginated API responses with range information following the HTTP Content-Range header standard.
+
+## Overview
+
+- **shouldQueryRange Option**: New option for `find()` that returns data with range information
+- **TDataRange Type**: New type for pagination range data (`start`, `end`, `total`)
+- **HTTP Content-Range Standard**: Range format follows RFC 7233 for compatibility with browsers and HTTP clients
+- **Parallel Execution**: Count and data queries run in parallel for optimal performance
+
+## New Features
+
+### shouldQueryRange Option
+
+**Files:**
+- `packages/core/src/base/repositories/common/types.ts`
+- `packages/core/src/base/repositories/core/readable.ts`
+- `packages/core/src/base/repositories/core/abstract.ts`
+
+**Problem:** When building paginated APIs, you often need to return both the data and total count for pagination UI (showing "Page 1 of 10" or "Showing 1-20 of 200 results"). Previously, this required two separate queries.
+
+**Solution:** Pass `shouldQueryRange: true` to get range information alongside the data:
+
+```typescript
+// Without range (default behavior)
+const users = await userRepo.find({
+  filter: { limit: 10, skip: 20 }
+});
+// Returns: Array<User>
+
+// With range information
+const result = await userRepo.find({
+  filter: { limit: 10, skip: 20 },
+  options: { shouldQueryRange: true }
+});
+// Returns: { data: Array<User>, range: TDataRange }
+```
+
+**Benefits:**
+- Single method call returns both data and count
+- Count query runs in parallel with data fetch (no performance penalty)
+- Range format follows HTTP Content-Range standard
+- Easy to set HTTP headers for RESTful APIs
+
+### TDataRange Type
+
+**File:** `packages/core/src/base/repositories/common/types.ts`
+
+New type for range information following HTTP Content-Range standard:
+
+```typescript
+type TDataRange = {
+  start: number;  // Starting index (0-based, inclusive)
+  end: number;    // Ending index (0-based, inclusive)
+  total: number;  // Total count matching the query
+};
+```
+
+**HTTP Content-Range Header Format:**
+
+```typescript
+const { data, range } = await repo.find({
+  filter: { limit: 10, skip: 20 },
+  options: { shouldQueryRange: true }
+});
+
+// Format: "unit 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"
+```
+
+| 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 (90-99) | `records 90-99/100` |
+
+### Performance Optimization
+
+When `shouldQueryRange: true`, the repository uses `Promise.all` to run the data query and count query in parallel:
+
+```typescript
+// Runs in parallel - no extra latency
+const [data, { count: total }] = await Promise.all([
+  dataPromise,
+  this.count({ where: mergedFilter.where ?? {}, options: effectiveOptions }),
+]);
+```
+
+## Files Changed
+
+### Core Package (`packages/core`)
+
+| File | Changes |
+|------|---------|
+| `src/base/repositories/common/types.ts` | Added `TDataRange` type, updated `IReadableRepository.find()` overloads |
+| `src/base/repositories/core/abstract.ts` | Added abstract `find()` overload for `shouldQueryRange: true` |
+| `src/base/repositories/core/readable.ts` | Implemented `shouldQueryRange` logic with parallel execution |
+| `src/base/controllers/factory/controller.ts` | Updated to use `shouldQueryRange` and set `Content-Range` header |
+
+### Helpers Package (`packages/helpers`)
+
+| File | Changes |
+|------|---------|
+| `src/common/constants/http.ts` | Added `CONTENT_RANGE` header constant |
+
+## No Breaking Changes
+
+All changes are additive. The default behavior of `find()` remains unchanged:
+
+```typescript
+// Still works exactly as before
+const users = await repo.find({ filter: { where: { active: true } } });
+// Returns: Array<User>
+```
+
+The new `shouldQueryRange` option is opt-in only.
+
+## Usage Examples
+
+### Basic Pagination API
+
+```typescript
+// In your controller
+async list(req, res) {
+  const page = parseInt(req.query.page) || 1;
+  const pageSize = parseInt(req.query.pageSize) || 20;
+
+  const { data, range } = await this.repo.find({
+    filter: {
+      where: req.query.filter,
+      limit: pageSize,
+      skip: (page - 1) * pageSize,
+      order: ['createdAt DESC']
+    },
+    options: { shouldQueryRange: true }
+  });
+
+  res.setHeader('Content-Range', `records ${range.start}-${range.end}/${range.total}`);
+  return res.json({
+    data,
+    pagination: {
+      page,
+      pageSize,
+      totalPages: Math.ceil(range.total / pageSize),
+      totalItems: range.total
+    }
+  });
+}
+```
+
+### React Admin / Data Grid Integration
+
+Many data grid libraries expect the `Content-Range` header for pagination:
+
+```typescript
+// Server response
+res.setHeader('Content-Range', `records 0-24/100`);
+res.setHeader('Access-Control-Expose-Headers', 'Content-Range');
+return res.json(data);
+
+// Client can read the header
+const response = await fetch('/api/users?limit=25&skip=0');
+const contentRange = response.headers.get('Content-Range');
+// → "records 0-24/100"
+```
+
+## Documentation
+
+- [Fields, Order & Pagination](/references/base/filter-system/fields-order-pagination) - Range Queries section added
+- [Repositories Overview](/references/base/repositories/) - Updated method tables

package/wiki/changelogs/2026-01-06-basic-authentication.md

@@ -0,0 +1,103 @@
+---
+title: Basic Authentication Strategy
+description: Added HTTP Basic Authentication strategy for API authentication
+---
+
+# Changelog - 2026-01-06
+
+## Basic Authentication Strategy
+
+This release adds HTTP Basic Authentication support to the Ignis authentication system.
+
+## Overview
+
+- **BasicAuthenticationStrategy**: New strategy implementing HTTP Basic auth
+- **BasicTokenService**: Service for extracting and verifying credentials from `Authorization: Basic <base64>` header
+- **Integration**: Works with existing AuthenticationStrategyRegistry
+
+## New Features
+
+### BasicAuthenticationStrategy
+
+**File:** `packages/core/src/components/auth/authenticate/strategies/basic.strategy.ts`
+
+New authentication strategy that:
+- Extracts credentials from `Authorization: Basic <base64>` header
+- Decodes base64-encoded `username:password` format
+- Verifies credentials using custom `verifyCredentials` function
+- Returns user profile on successful authentication
+
+### BasicTokenService
+
+**File:** `packages/core/src/components/auth/authenticate/services/basic-token.service.ts`
+
+Service handling credential extraction and verification:
+- Parses `Authorization` header with `Basic` scheme
+- Decodes base64 credentials to `username:password`
+- Supports custom credential verification logic
+
+## Usage
+
+### Step 1: Configure Basic Auth in Controller
+
+```typescript
+import { Authentication, ControllerFactory } from '@venizia/ignis';
+
+const _Controller = ControllerFactory.defineCrudController({
+  repository: { name: UserRepository.name },
+  controller: { name: 'UserController', basePath: '/users' },
+
+  // Enable basic auth for all routes
+  authStrategies: [Authentication.STRATEGY_BASIC],
+
+  // Or per-route configuration
+  routes: {
+    create: {
+      authStrategies: [Authentication.STRATEGY_BASIC],
+    },
+  },
+});
+```
+
+### Step 2: Implement Credential Verification
+
+```typescript
+import { BasicTokenService } from '@venizia/ignis';
+
+// Custom credential verification
+const verifyCredentials = async (username: string, password: string) => {
+  const user = await userRepository.findOne({ where: { username } });
+
+  if (!user || !await comparePassword(password, user.passwordHash)) {
+    throw new HttpErrors.Unauthorized('Invalid credentials');
+  }
+
+  return { id: user.id, username: user.username };
+};
+```
+
+### Step 3: Client Usage
+
+```bash
+# Base64 encode credentials: username:password
+curl -X GET http://api.example.com/users \
+  -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ="
+```
+
+## Files Changed
+
+### Core Package (`packages/core`)
+
+| File | Changes |
+|------|---------|
+| `src/components/auth/authenticate/strategies/basic.strategy.ts` | New BasicAuthenticationStrategy |
+| `src/components/auth/authenticate/services/basic-token.service.ts` | New BasicTokenService |
+| `src/components/auth/authenticate/common/keys.ts` | Added STRATEGY_BASIC constant |
+| `src/components/auth/index.ts` | Export basic auth components |
+
+## Security Considerations
+
+- Basic Auth transmits credentials in base64 (NOT encrypted)
+- Always use HTTPS in production
+- Consider rate limiting to prevent brute force attacks
+- For sensitive APIs, prefer JWT or OAuth2 strategies

package/wiki/changelogs/2026-01-07-controller-route-customization.md

@@ -0,0 +1,209 @@
+---
+title: Controller Route Customization
+description: Enhanced request/response customization for CRUD controllers with typed method overrides
+---
+
+# Changelog - 2026-01-07
+
+## Controller Factory Route Customization
+
+This release enhances the Controller Factory with comprehensive request/response schema customization and introduces helper types for strongly-typed method overrides.
+
+## Overview
+
+- **Route Customization**: New `request` and `response` configuration for all CRUD routes
+- **Helper Types**: Added `THandlerContext` and `TInferSchema` for typed method overrides
+- **Generic Definitions**: Controllers now preserve route definition types for better IDE support
+- **Compact Descriptions**: OpenAPI route descriptions made more concise
+- **Response Metadata**: Added meaningful response descriptions for API explorers
+
+## New Features
+
+### Enhanced Route Customization
+
+**Files:**
+- `packages/core/src/base/controllers/factory/definition.ts`
+- `packages/core/src/base/controllers/common/types.ts`
+
+**Problem:** Users could only customize `requestBody` and `schema` (response). No way to customize query parameters, headers, or path parameters.
+
+**Solution:** New unified `request` and `response` configuration objects:
+
+```typescript
+routes: {
+  create: {
+    authStrategies: ['jwt'],
+    request: {
+      body: CreateUserSchema,      // Custom request body
+      headers: CustomHeadersSchema, // Custom headers
+    },
+    response: {
+      schema: PublicUserSchema,    // Custom response body
+    },
+  },
+  find: {
+    skipAuth: true,
+    request: {
+      query: CustomQuerySchema,    // Custom query parameters
+    },
+    response: {
+      schema: z.array(PublicUserSchema),
+    },
+  },
+}
+```
+
+**Customizable Components per Route:**
+
+| Route | query | headers | params | body | response |
+|-------|-------|---------|--------|------|----------|
+| COUNT | ✅ | ✅ | - | - | ✅ |
+| FIND | ✅ | ✅ | - | - | ✅ |
+| FIND_BY_ID | ✅ | ✅ | ✅ | - | ✅ |
+| FIND_ONE | ✅ | ✅ | - | - | ✅ |
+| CREATE | - | ✅ | - | ✅ | ✅ |
+| UPDATE_BY_ID | - | ✅ | ✅ | ✅ | ✅ |
+| UPDATE_BY | ✅ | ✅ | - | ✅ | ✅ |
+| DELETE_BY_ID | - | ✅ | ✅ | - | ✅ |
+| DELETE_BY | ✅ | ✅ | - | - | ✅ |
+
+### Helper Types for Method Overrides
+
+**File:** `packages/core/src/base/controllers/common/types.ts`
+
+**Problem:** When overriding CRUD methods, the context type was not strongly typed.
+
+**Solution:** New helper types for extracting context types from route definitions:
+
+```typescript
+// Extract definitions type from controller
+type TRouteDefinitions = InstanceType<typeof _Controller>['definitions'];
+
+// Use THandlerContext for typed method overrides
+override async create(opts: { context: THandlerContext<TRouteDefinitions, 'CREATE'> }) {
+  const { context } = opts;
+
+  // Use TInferSchema for typed request body
+  const data = context.req.valid('json') as TInferSchema<typeof CreateSchema>;
+
+  // data.code, data.name are now strongly typed!
+  return super.create(opts);
+}
+```
+
+**Available Route Keys:**
+- `'COUNT'`, `'FIND'`, `'FIND_BY_ID'`, `'FIND_ONE'`
+- `'CREATE'`, `'UPDATE_BY_ID'`, `'UPDATE_BY'`
+- `'DELETE_BY_ID'`, `'DELETE_BY'`
+
+### Generic Controller Definitions
+
+**Files:**
+- `packages/core/src/base/controllers/abstract.ts`
+- `packages/core/src/base/controllers/base.ts`
+- `packages/core/src/base/controllers/factory/controller.ts`
+
+**Problem:** Route definition types were lost, preventing proper type inference in overridden methods.
+
+**Solution:** Added `Definitions` generic parameter to `AbstractController` and `BaseController`:
+
+```typescript
+export abstract class AbstractController<
+  RouteEnv extends Env = Env,
+  RouteSchema extends Schema = {},
+  BasePath extends string = '/',
+  ConfigurableOptions extends object = {},
+  Definitions extends Record<string, TAuthRouteConfig<RouteConfig>> = Record<...>,
+>
+```
+
+The `definitions` property now preserves the actual route definition types.
+
+### Compact OpenAPI Descriptions
+
+**File:** `packages/core/src/base/controllers/factory/definition.ts`
+
+**Before:**
+```typescript
+description: 'Returns the total count of records matching the optional where condition. Useful for pagination metadata or checking data existence without fetching records.'
+```
+
+**After:**
+```typescript
+description: 'Count records matching where condition'
+```
+
+All route descriptions are now concise and easy to read in API explorers.
+
+### Response Metadata
+
+**File:** `packages/core/src/base/controllers/factory/definition.ts`
+
+Added meaningful response descriptions for OpenAPI:
+
+| Route | Response Description |
+|-------|---------------------|
+| COUNT | Total count of matching records |
+| FIND | Array of matching records (with optional count) |
+| FIND_BY_ID | Single record matching ID or null |
+| FIND_ONE | First matching record or null |
+| CREATE | Created record with generated fields (id, createdAt, etc.) |
+| UPDATE_BY_ID | Updated record with all current fields |
+| UPDATE_BY | Array of updated records |
+| DELETE_BY_ID | Deleted record data |
+| DELETE_BY | Array of deleted records |
+
+## Files Changed
+
+### Core Package (`packages/core`)
+
+| File | Changes |
+|------|---------|
+| `src/base/controllers/abstract.ts` | Added `Definitions` generic parameter |
+| `src/base/controllers/base.ts` | Added `Definitions` generic parameter |
+| `src/base/controllers/common/types.ts` | Added `THandlerContext`, `TInferSchema`, route config types |
+| `src/base/controllers/factory/controller.ts` | Made `ICrudControllerOptions` generic, added type casts |
+| `src/base/controllers/factory/definition.ts` | Updated route configs, compact descriptions, response metadata |
+
+### Examples (`examples/vert`)
+
+| File | Changes |
+|------|---------|
+| `src/controllers/configuration.controller.ts` | Updated to use new route customization syntax |
+
+## Migration Guide
+
+### Step 1: Update Route Configuration Syntax
+
+**Before:**
+```typescript
+routes: {
+  create: {
+    requestBody: CreateSchema,
+    schema: ResponseSchema,
+  }
+}
+```
+
+**After:**
+```typescript
+routes: {
+  create: {
+    request: { body: CreateSchema },
+    response: { schema: ResponseSchema },
+  }
+}
+```
+
+### Step 2: Use Helper Types for Method Overrides
+
+```typescript
+// Extract definitions type
+type TRouteDefinitions = InstanceType<typeof _Controller>['definitions'];
+
+// Use THandlerContext in method signature
+override async create(opts: { context: THandlerContext<TRouteDefinitions, 'CREATE'> }) {
+  const data = context.req.valid('json') as TInferSchema<typeof CreateSchema>;
+  // ...
+}
+```

package/wiki/changelogs/index.md

@@ -17,6 +17,9 @@ This section tracks the history of significant changes, refactors, and updates t
 
 | Date | Title | Type |
 |------|-------|------|
+| 2026-01-07 | [Controller Route Customization](./2026-01-07-controller-route-customization) | New Feature |
+| 2026-01-06 | [Basic Authentication Strategy](./2026-01-06-basic-authentication) | New Feature |
+| 2026-01-05 | [Range Queries & Content-Range Header](./2026-01-05-range-queries-content-range) | New Feature |
 | 2026-01-02 | [Default Filter & Repository Mixins](./2026-01-02-default-filter-and-repository-mixins) | New Feature |
 | 2025-12-31 | [JSON Path Filtering & Array Operators](./2025-12-31-json-path-filtering-array-operators) | New Feature |
 | 2025-12-31 | [String ID with Custom Generator](./2025-12-31-string-id-custom-generator) | Enhancement |

package/wiki/guides/core-concepts/components-guide.md

@@ -506,4 +506,4 @@ export class MyComponent extends BaseComponent {
 
 - **Best Practices:**
   - [Architectural Patterns](/best-practices/architectural-patterns) - Component architecture patterns
-  - [Code Style Standards](/best-practices/code-style-standards) - Component coding standards
+  - [Code Style Standards](/best-practices/code-style-standards/) - Component coding standards

package/wiki/guides/core-concepts/persistent/models.md

@@ -141,6 +141,16 @@ static override schema = pgTable('User', {
 | `generateDataTypeColumnDefs()` | `dataType`, `tValue`, `nValue`, etc. | Configuration tables |
 | `extraUserColumns()` | Combines audit + status + type | Full-featured entities |
 
+:::note User Audit Options
+The `generateUserAuditColumnDefs` enricher supports an `allowAnonymous` option (default: `true`). Set to `false` to require authenticated user context and throw errors for anonymous operations:
+```typescript
+...generateUserAuditColumnDefs({
+  created: { dataType: 'string', columnName: 'created_by', allowAnonymous: false },
+  modified: { dataType: 'string', columnName: 'modified_by', allowAnonymous: false },
+})
+```
+:::
+
 :::tip
 For a complete list of enrichers and options, see the [Schema Enrichers Reference](../../../references/base/models.md#schema-enrichers).
 :::

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

@@ -110,7 +110,7 @@ export default eslintConfigs;
 > export default [...eslintConfigs, { rules: { 'no-console': 'warn' } }];
 > ```
 
-> **Deep Dive:** See [Code Style Standards](/best-practices/code-style-standards) for detailed configuration options.
+> **Deep Dive:** See [Code Style Standards](/best-practices/code-style-standards/) for detailed configuration options.
 
 :::tip Coming from Express/Hono/Fastify?
 This setup might seem verbose compared to minimal frameworks. The trade-off: ~50 lines of config upfront gives you scalable architecture for 10-1000+ endpoints without spaghetti code. For quick prototypes (< 5 endpoints), use plain Hono instead.

package/wiki/guides/tutorials/testing.md

@@ -704,7 +704,7 @@ class CreateAndUpdateAndDeleteHandler extends TestCaseHandler {
 ## Next Steps
 
 - [Testing Reference](../../references/helpers/testing.md) - Complete API documentation
-- [Best Practices](../../best-practices/code-style-standards.md) - Code quality standards
+- [Best Practices](../../best-practices/code-style-standards/) - Code quality standards
 - [Troubleshooting](../../best-practices/troubleshooting-tips.md) - Common issues
 
 ## Summary

package/wiki/references/base/components.md

@@ -120,8 +120,8 @@ import { AnyObject, ValueOrPromise } from '@venizia/ignis-helpers';
 
 // Options interface for the component
 export interface IAuthenticateOptions {
-  alwaysAllowPaths: Array<string>;
-  tokenOptions: IJWTTokenServiceOptions;
+  jwtOptions?: IJWTTokenServiceOptions;
+  basicOptions?: IBasicTokenServiceOptions;
   restOptions?: {
     useAuthController?: boolean;
     controllerOpts?: TDefineAuthControllerOpts;
@@ -307,16 +307,13 @@ export class HealthCheckComponent extends BaseComponent {
 ```typescript
 // src/components/auth/authenticate/component.ts
 import { BaseApplication, BaseComponent, inject, CoreBindings, Binding, ValueOrPromise, getError } from '@venizia/ignis';
-import { AuthenticateBindingKeys, IAuthenticateOptions, IJWTTokenServiceOptions } from './common';
-import { JWTTokenService } from './services';
+import { AuthenticateBindingKeys, IAuthenticateOptions, IBasicTokenServiceOptions, IJWTTokenServiceOptions } from './common';
+import { BasicTokenService, JWTTokenService } from './services';
 import { defineAuthController } from './controllers';
 
 const DEFAULT_OPTIONS: IAuthenticateOptions = {
-  alwaysAllowPaths: [],
-  tokenOptions: {
-    applicationSecret: process.env.APP_ENV_APPLICATION_SECRET ?? '',
-    jwtSecret: process.env.APP_ENV_JWT_SECRET ?? '',
-    getTokenExpiresFn: () => parseInt(process.env.APP_ENV_JWT_EXPIRES_IN ?? '86400'),
+  restOptions: {
+    useAuthController: false,
   },
 };
 
@@ -336,37 +333,58 @@ export class AuthenticateComponent extends BaseComponent {
     });
   }
 
-  // Split complex logic into private methods
-  private defineAuth(): void {
-    const options = this.application.get<IAuthenticateOptions>({
-      key: AuthenticateBindingKeys.AUTHENTICATE_OPTIONS,
-    });
-
-    // Validate required configuration
-    if (!options?.tokenOptions.jwtSecret) {
+  // Validate at least one auth option is provided
+  private validateOptions(opts: IAuthenticateOptions): void {
+    if (!opts.jwtOptions && !opts.basicOptions) {
       throw getError({
-        message: '[defineAuth] Missing required jwtSecret configuration',
+        message: '[AuthenticateComponent] At least one of jwtOptions or basicOptions must be provided',
       });
     }
+  }
+
+  // Configure JWT authentication if jwtOptions is provided
+  private defineJWTAuth(opts: IAuthenticateOptions): void {
+    if (!opts.jwtOptions) return;
 
-    // Bind service options
     this.application
       .bind<IJWTTokenServiceOptions>({ key: AuthenticateBindingKeys.JWT_OPTIONS })
-      .toValue(options.tokenOptions);
-
-    // Register service
+      .toValue(opts.jwtOptions);
     this.application.service(JWTTokenService);
+  }
+
+  // Configure Basic authentication if basicOptions is provided
+  private defineBasicAuth(opts: IAuthenticateOptions): void {
+    if (!opts.basicOptions) return;
+
+    this.application
+      .bind<IBasicTokenServiceOptions>({ key: AuthenticateBindingKeys.BASIC_OPTIONS })
+      .toValue(opts.basicOptions);
+    this.application.service(BasicTokenService);
+  }
+
+  // Configure auth controllers if enabled
+  private defineControllers(opts: IAuthenticateOptions): void {
+    if (!opts.restOptions?.useAuthController) return;
 
-    // Conditionally register controller
-    if (options.restOptions?.useAuthController) {
-      this.application.controller(
-        defineAuthController(options.restOptions.controllerOpts),
-      );
+    // Auth controller requires JWT for token generation
+    if (!opts.jwtOptions) {
+      throw getError({
+        message: '[defineControllers] Auth controller requires jwtOptions to be configured',
+      });
     }
+
+    this.application.controller(defineAuthController(opts.restOptions.controllerOpts));
   }
 
   override binding(): ValueOrPromise<void> {
-    this.defineAuth();
+    const options = this.application.get<IAuthenticateOptions>({
+      key: AuthenticateBindingKeys.AUTHENTICATE_OPTIONS,
+    });
+
+    this.validateOptions(options);
+    this.defineJWTAuth(options);
+    this.defineBasicAuth(options);
+    this.defineControllers(options);
   }
 }
 ```
@@ -578,4 +596,4 @@ export * from './controller';
 
 - **Best Practices:**
   - [Architectural Patterns](/best-practices/architectural-patterns) - Component design patterns
-  - [Code Style Standards](/best-practices/code-style-standards) - Component coding standards
+  - [Code Style Standards](/best-practices/code-style-standards/) - Component coding standards