@venizia/ignis-docs 0.0.3 → 0.0.4-1

package/wiki/best-practices/performance-optimization.md

@@ -0,0 +1,196 @@
+# Performance Optimization
+
+Optimize your Ignis application for speed and scalability.
+
+## 1. Measure Performance
+
+Identify bottlenecks before optimizing:
+
+```typescript
+import { executeWithPerformanceMeasure } from '@venizia/ignis';
+
+await executeWithPerformanceMeasure({
+  logger: this.logger,
+  scope: 'DataProcessing',
+  description: 'Process large dataset',
+  task: async () => {
+    await processLargeDataset();
+  },
+});
+```
+
+Logs execution time automatically.
+
+> **Deep Dive:** See [Performance Utility](../references/utilities/performance.md) for advanced profiling.
+
+## 2. Offload CPU-Intensive Tasks
+
+Prevent blocking the event loop with Worker Threads:
+
+**Use Worker Threads for:**
+- Complex calculations or crypto operations
+- Large file/data processing
+- Any synchronous task > 5ms
+
+> **Deep Dive:** See [Worker Thread Helper](../references/helpers/worker-thread.md) for implementation guide.
+
+## 3. Optimize Database Queries
+
+| Technique | Example | Impact |
+|-----------|---------|--------|
+| **Select specific fields** | `fields: { id: true, name: true }` | Reduce data transfer |
+| **Use indexes** | Create indexes on WHERE/JOIN columns | 10-100x faster queries |
+| **Mandatory Limit** | `limit: 20` | Prevent fetching massive datasets |
+| **Paginate results** | `limit: 20, offset: 0` | Prevent memory overflow |
+| **Eager load relations** | `include: [{ relation: 'creator' }]` | Solve N+1 problem |
+
+### Query Operators Reference
+
+Ignis supports extensive query operators for filtering:
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `eq` | Equal (handles null) | `{ status: { eq: 'ACTIVE' } }` |
+| `ne`, `neq` | Not equal | `{ status: { ne: 'DELETED' } }` |
+| `gt`, `gte` | Greater than (or equal) | `{ age: { gte: 18 } }` |
+| `lt`, `lte` | Less than (or equal) | `{ price: { lt: 100 } }` |
+| `like` | SQL LIKE (case-sensitive) | `{ name: { like: '%john%' } }` |
+| `ilike` | Case-insensitive LIKE | `{ email: { ilike: '%@gmail%' } }` |
+| `nlike`, `nilike` | NOT LIKE variants | `{ name: { nlike: '%test%' } }` |
+| `regexp` | PostgreSQL regex (`~`) | `{ code: { regexp: '^[A-Z]+$' } }` |
+| `iregexp` | Case-insensitive regex (`~*`) | `{ name: { iregexp: '^john' } }` |
+| `in`, `inq` | Value in array | `{ status: { in: ['A', 'B'] } }` |
+| `nin` | Value NOT in array | `{ role: { nin: ['guest'] } }` |
+| `between` | Range (inclusive) | `{ age: { between: [18, 65] } }` |
+| `is`, `isn` | IS NULL / IS NOT NULL | `{ deletedAt: { is: null } }` |
+| `and`, `or` | Logical operators | `{ or: [{ a: 1 }, { b: 2 }] }` |
+
+**Complex Filter Example:**
+
+```typescript
+await repo.find({
+  filter: {
+    where: {
+      and: [
+        { status: { in: ['ACTIVE', 'PENDING'] } },
+        { createdAt: { gte: new Date('2024-01-01') } },
+        { or: [
+          { role: 'admin' },
+          { permissions: { ilike: '%manage%' } }
+        ]}
+      ]
+    },
+    limit: 50,
+  },
+});
+```
+
+### JSON Path Filtering
+
+Filter by nested JSON/JSONB fields using PostgreSQL's `#>` operator:
+
+```typescript
+// Order by nested JSON path
+await repo.find({
+  filter: {
+    order: ['metadata.nested[0].field ASC'],
+  },
+});
+
+// The framework uses PostgreSQL #> operator for path extraction
+// metadata #> '{nested,0,field}'
+```
+
+> [!TIP]
+> **Avoid Deep Nesting:** While Ignis supports deeply nested `include` filters, each level adds significant overhead to query construction and result mapping. We strongly recommend a **maximum of 2 levels** (e.g., `User -> Orders -> Items`). For more complex data fetching, consider separate queries.
+
+**Example:**
+```typescript
+await userRepository.find({
+  filter: {
+    fields: { id: true, name: true, email: true },  // ✅ Specific fields
+    where: { status: 'ACTIVE' },
+    limit: 20,                                       // ✅ Mandatory limit
+    include: [{ 
+      relation: 'orders',
+      scope: {
+        include: [{ relation: 'items' }]             // ✅ Level 2 (Recommended limit)
+      }
+    }],
+  },
+});
+```
+
+## 4. Implement Caching
+
+Reduce database load with caching:
+
+| Cache Type | Use Case | Implementation |
+|-----------|----------|----------------|
+| **Redis** | Distributed cache, session storage | [Redis Helper](../references/helpers/redis.md) |
+| **In-Memory** | Single-process cache | `MemoryStorageHelper` |
+
+**Example:**
+```typescript
+// Cache expensive query results
+const cached = await redis.get('users:active');
+if (!cached) {
+  const users = await userRepository.find({ where: { active: true } });
+  await redis.set('users:active', users, 300); // 5 min TTL
+}
+```
+
+## 5. Production Settings
+
+| Setting | Value | Why |
+|---------|-------|-----|
+| `NODE_ENV` | `production` | Enables library optimizations |
+| Process Manager | PM2, systemd, Docker | Auto-restart, cluster mode |
+| Cluster Mode | CPU cores | Utilize all CPUs |
+
+**PM2 Cluster Mode:**
+```bash
+pm2 start dist/index.js -i max  # Use all CPU cores
+```
+
+## 6. Transaction Support
+
+Use transactions to ensure atomicity across multiple database operations:
+
+```typescript
+// Start a transaction
+const tx = await userRepository.beginTransaction({
+  isolationLevel: 'READ COMMITTED', // or 'REPEATABLE READ' | 'SERIALIZABLE'
+});
+
+try {
+  // Pass transaction to all operations
+  const user = await userRepository.create({
+    data: { name: 'John', email: 'john@example.com' },
+    options: { transaction: tx },
+  });
+
+  await orderRepository.create({
+    data: { userId: user.data.id, total: 100 },
+    options: { transaction: tx },
+  });
+
+  // Commit if all operations succeed
+  await tx.commit();
+} catch (error) {
+  // Rollback on any failure
+  await tx.rollback();
+  throw error;
+}
+```
+
+**Transaction Isolation Levels:**
+
+| Level | Description | Use Case |
+|-------|-------------|----------|
+| `READ COMMITTED` | See committed data only (default) | Most CRUD operations |
+| `REPEATABLE READ` | Consistent reads within transaction | Reports, aggregations |
+| `SERIALIZABLE` | Full isolation, may retry | Financial transactions |
+
+> [!WARNING]
+> Higher isolation levels reduce concurrency. Use `READ COMMITTED` unless you have specific consistency requirements.

package/wiki/best-practices/security-guidelines.md

@@ -0,0 +1,218 @@
+# Security Guidelines
+
+Critical security practices to protect your Ignis application.
+
+## 1. Secret Management
+
+**Never hard-code secrets.** Use environment variables for all sensitive data.
+
+| Environment | Where to Store Secrets |
+|-------------|----------------------|
+| Development | `.env` file (add to `.gitignore`) |
+| Production | Cloud provider's secret manager (AWS Secrets Manager, Azure Key Vault, etc.) |
+
+**Example `.env`:**
+```bash
+APP_ENV_APPLICATION_SECRET=your_strong_random_secret_here
+APP_ENV_JWT_SECRET=another_strong_random_secret_here
+APP_ENV_POSTGRES_PASSWORD=database_password_here
+```
+
+**Generate strong secrets:**
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+```
+
+## 2. Input Validation
+
+**Always validate incoming data** with Zod schemas. Ignis automatically rejects invalid requests.
+
+```typescript
+import { z } from '@hono/zod-openapi';
+import { jsonContent, jsonResponse } from '@venizia/ignis';
+
+const CreateUserRoute = {
+  method: 'post',
+  path: '/users',
+  request: {
+    body: jsonContent({
+      schema: z.object({
+        email: z.string().email(),           // Valid email
+        age: z.number().int().min(18),       // Adult only
+        role: z.enum(['user', 'admin']),     // Whitelist
+      }),
+    }),
+  },
+  responses: jsonResponse({ /* ... */ }),
+} as const;
+```
+
+**Validation happens automatically** - invalid requests never reach your handler.
+
+## 3. Authentication & Authorization
+
+Protect sensitive endpoints with `AuthenticateComponent`.
+
+**Setup:**
+```typescript
+// application.ts
+this.component(AuthenticateComponent);
+```
+
+**Protect routes:**
+```typescript
+const SecureRoute = {
+  path: '/admin/users',
+  authStrategies: [Authentication.STRATEGY_JWT], // Requires JWT
+  // ...
+};
+```
+
+> **Deep Dive:** See [Authentication Component](../references/components/authentication.md) for full setup guide.
+
+**Access user in protected routes:**
+```typescript
+import { Authentication, IJWTTokenPayload, ApplicationError, getError } from '@venizia/ignis';
+
+const user = c.get(Authentication.CURRENT_USER) as IJWTTokenPayload;
+if (!user.roles.includes('admin')) {
+    throw getError({ statusCode: 403, message: 'Forbidden' });
+}
+```
+
+## 4. Protecting Sensitive Data with Hidden Properties
+
+Configure model properties that should **never be returned** through repository queries. Hidden properties are excluded at the SQL level - they never leave the database.
+
+```typescript
+@model({
+  type: 'entity',
+  settings: {
+    hiddenProperties: ['password', 'apiSecret', 'internalToken'],
+  },
+})
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = pgTable('User', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    email: text('email').notNull(),
+    password: text('password'),      // Never returned via repository
+    apiSecret: text('api_secret'),   // Never returned via repository
+  });
+}
+```
+
+**Why SQL-level exclusion matters:**
+
+| Approach | Security Level | Data Exposure Risk |
+|----------|---------------|-------------------|
+| Post-query filtering (JS) | Low | Data passes through network/memory |
+| **SQL-level exclusion** | **High** | **Data never leaves database** |
+
+**When you legitimately need hidden data** (e.g., password verification), use the connector directly:
+
+```typescript
+// For authentication - access password via connector
+const connector = userRepo.getConnector();
+const [user] = await connector
+  .select({ id: User.schema.id, password: User.schema.password })
+  .from(User.schema)
+  .where(eq(User.schema.email, email));
+```
+
+> **Reference:** See [Hidden Properties](../references/base/models.md#hidden-properties) for complete documentation.
+
+## 5. File Upload Security
+
+When handling file uploads, prevent **path traversal attacks** and ensure safe file handling.
+
+### Path Traversal Prevention
+
+**Problem:** Malicious filenames like `../../../etc/passwd` can write files outside intended directories.
+
+**Solution:** Use `sanitizeFilename()` to strip dangerous patterns:
+
+```typescript
+import { sanitizeFilename } from '@venizia/ignis';
+
+// ❌ DANGEROUS - User-controlled filename
+const unsafeFilename = req.body.filename; // Could be "../../../etc/passwd"
+fs.writeFileSync(`./uploads/${unsafeFilename}`, data);
+
+// ✅ SAFE - Sanitized filename
+const safeFilename = sanitizeFilename(req.body.filename);
+fs.writeFileSync(`./uploads/${safeFilename}`, data);
+```
+
+**What `sanitizeFilename()` does:**
+- Extracts basename (removes directory paths)
+- Removes dangerous characters (`../`, special chars)
+- Replaces consecutive dots with single dot
+- Returns `'download'` for empty/suspicious patterns
+
+### Safe File Download Headers
+
+Use `createContentDispositionHeader()` for secure download responses:
+
+```typescript
+import { createContentDispositionHeader, sanitizeFilename } from '@venizia/ignis';
+
+async downloadFile(c: Context) {
+  const filename = sanitizeFilename(c.req.param('filename'));
+  const fileBuffer = await fs.readFile(`./uploads/${filename}`);
+
+  return new Response(fileBuffer, {
+    headers: {
+      'Content-Type': 'application/octet-stream',
+      'Content-Disposition': createContentDispositionHeader({
+        filename: filename,
+        type: 'attachment',
+      }),
+    },
+  });
+}
+```
+
+### Built-in Multipart Parsing
+
+Use `parseMultipartBody()` for safe file uploads with automatic sanitization:
+
+```typescript
+import { parseMultipartBody } from '@venizia/ignis';
+
+async uploadFile(c: Context) {
+  const files = await parseMultipartBody({
+    context: c,
+    storage: 'disk',        // or 'memory' for buffer
+    uploadDir: './uploads', // Target directory
+  });
+
+  // Files are saved with sanitized names: timestamp-random-sanitized_name.ext
+  return c.json({ uploaded: files.map(f => f.filename) });
+}
+```
+
+**Security features:**
+- Automatic filename sanitization
+- Creates upload directory if missing
+- Generates unique filenames (prevents overwrites)
+- Returns file metadata (size, mimetype) for validation
+
+> **Reference:** See [Request Utility](../references/utilities/request.md) for full API documentation.
+
+## 6. Secure Dependencies
+
+Regularly audit and update dependencies:
+
+```bash
+# Check for vulnerabilities
+bun audit
+
+# Update dependencies
+bun update
+```
+
+**Critical packages to keep updated:**
+- `hono` - Web framework
+- `jose` - JWT handling
+- `drizzle-orm` - Database ORM
+- `@venizia/ignis` - Framework core

package/wiki/{get-started/best-practices → best-practices}/troubleshooting-tips.md

@@ -97,4 +97,100 @@ cat .env | grep APP_ENV
 - Use `try-catch` blocks to catch and log errors
 - Check database queries with Drizzle's logging: `{ logger: true }`
 
-> **Deep Dive:** See [Logger Helper](../../references/helpers/logger.md) for advanced logging configuration.
+> **Deep Dive:** See [Logger Helper](../references/helpers/logger.md) for advanced logging configuration.
+
+## 6. Request ID Tracking
+
+Every request in Ignis is automatically assigned a unique `requestId` for log correlation. The `RequestSpyMiddleware` logs this ID at the start and end of each request.
+
+**Log output format:**
+```
+[spy][abc123] START | Handling Request | forwardedIp: 192.168.1.1 | path: /api/users | method: GET
+[spy][abc123] DONE  | Handling Request | forwardedIp: 192.168.1.1 | path: /api/users | method: GET | Took: 45.2 (ms)
+```
+
+**Access request ID in handlers:**
+```typescript
+import { RequestSpyMiddleware } from '@venizia/ignis';
+
+// Inside a controller method
+async getUser(c: Context) {
+  const requestId = c.get(RequestSpyMiddleware.REQUEST_ID_KEY);
+  this.logger.info('[%s] Processing user request', requestId);
+  // ...
+}
+```
+
+**Filtering logs by request:**
+```bash
+# Find all logs for a specific request
+grep "abc123" logs/app.log
+
+# Extract request timing
+grep "\[spy\]\[abc123\]" logs/app.log
+```
+
+**Why this matters:**
+- Correlate logs across services in distributed systems
+- Debug specific user issues by their request ID
+- Measure request duration from START to DONE timestamps
+
+## 7. Validation Error Debugging
+
+When Zod validation fails, Ignis returns a structured error response. Understanding this format helps debug client-side issues.
+
+**Error response structure:**
+```json
+{
+  "statusCode": 422,
+  "message": "ValidationError",
+  "requestId": "abc123",
+  "details": {
+    "cause": [
+      {
+        "path": "email",
+        "message": "Invalid email",
+        "code": "invalid_string",
+        "expected": "email",
+        "received": "string"
+      }
+    ]
+  }
+}
+```
+
+**Common validation error codes:**
+
+| Code | Meaning | Example |
+|------|---------|---------|
+| `invalid_type` | Wrong data type | Expected `number`, got `string` |
+| `invalid_string` | String format invalid | Invalid email or UUID format |
+| `too_small` | Value below minimum | String shorter than min length |
+| `too_big` | Value above maximum | Number exceeds max value |
+| `invalid_enum_value` | Value not in enum | Status must be 'ACTIVE' or 'INACTIVE' |
+| `unrecognized_keys` | Extra fields in request | Strict schema rejects unknown fields |
+
+**Debugging tips:**
+
+1. **Check the `path` field** - Shows which field failed validation
+2. **Compare `expected` vs `received`** - Identifies type mismatches
+3. **Review schema definition** - Ensure client sends correct format
+
+**Example: Debugging nested validation errors:**
+```json
+{
+  "details": {
+    "cause": [
+      {
+        "path": "address.zipCode",
+        "message": "Expected string, received number",
+        "code": "invalid_type",
+        "expected": "string",
+        "received": "number"
+      }
+    ]
+  }
+}
+```
+
+The `path` uses dot notation for nested objects. Here, `address.zipCode` means the `zipCode` field inside the `address` object is invalid.

package/wiki/changelogs/2025-12-16-initial-architecture.md

@@ -142,4 +142,4 @@ src/
 
 ## No Breaking Changes
 
-This document describes the initial state of the architecture.
+This document describes the initial state of the architecture.

package/wiki/changelogs/2025-12-16-model-repo-datasource-refactor.md

@@ -297,4 +297,4 @@ export class PostgresDataSource extends BaseDataSource {
     });
   }
 }
-```
+```

package/wiki/changelogs/2025-12-17-refactor.md

@@ -87,4 +87,4 @@ If you are using the DI system directly, add the new package to your dependencie
 
 ```bash
 npm install @venizia/ignis-inversion
-```
+```

package/wiki/changelogs/2025-12-18-performance-optimizations.md

@@ -11,7 +11,7 @@ This update focuses on performance improvements for the repository layer, reduci
 
 ## Overview
 
-- **WeakMap Cache**: `DrizzleFilterBuilder` now caches `getTableColumns()` results.
+- **WeakMap Cache**: `FilterBuilder` now caches `getTableColumns()` results.
 - **Core API for Flat Queries**: `ReadableRepository` uses faster Drizzle Core API when possible.
 - **Static schemaFactory Singleton**: `BaseEntity` shares a single `schemaFactory` instance across all entities.
 - **Async/Await Refactor**: Removed redundant Promise wrappers from repository methods.
@@ -27,7 +27,7 @@ This update focuses on performance improvements for the repository layer, reduci
 **Solution:** Added static WeakMap cache that stores column metadata per schema.
 
 ```typescript
-export class DrizzleFilterBuilder extends BaseHelper {
+export class FilterBuilder extends BaseHelper {
   // Static cache shared across all instances
   private static columnCache = new WeakMap<
     TTableSchemaWithId,
@@ -35,10 +35,10 @@ export class DrizzleFilterBuilder extends BaseHelper {
   >();
 
   private getColumns<Schema extends TTableSchemaWithId>(schema: Schema) {
-    let columns = DrizzleFilterBuilder.columnCache.get(schema);
+    let columns = FilterBuilder.columnCache.get(schema);
     if (!columns) {
       columns = getTableColumns(schema);
-      DrizzleFilterBuilder.columnCache.set(schema, columns);
+      FilterBuilder.columnCache.set(schema, columns);
     }
     return columns;
   }
@@ -127,4 +127,4 @@ return { count };
 
 ## No Breaking Changes
 
-All changes are internal optimizations. No API changes or migration required.
+All changes are internal optimizations. No API changes or migration required.

package/wiki/changelogs/2025-12-18-repository-validation-security.md

@@ -16,7 +16,7 @@ This update adds strict validation to the `@repository` decorator and fixes seve
 - **DataSource Auto-Discovery**: Schema is automatically built from `@repository` bindings.
 - **Filter Security**: Fixed empty IN array bypass, invalid column handling, BETWEEN validation.
 - **PostgreSQL Compatibility**: REGEXP now uses PostgreSQL POSIX operators.
-- **UUID Generation**: Now uses native PostgreSQL `uuid` type with `gen_random_uuid()`.
+- **String ID Generation**: Uses `text` column with customizable ID generator (default: `crypto.randomUUID()`).
 
 ## Breaking Changes
 
@@ -114,18 +114,24 @@ export class PostgresDataSource extends BaseDataSource<...> {
 }
 ```
 
-### UUID Type Improvement
+### String ID with Custom Generator
 
 **File:** `packages/core/src/base/models/enrichers/id.enricher.ts`
 
-**Problem:** JS-generated UUIDs were stored as text, which is less efficient.
+**Problem:** Need flexible ID generation with maximum database compatibility.
 
-**Solution:** Changed to native PostgreSQL `uuid` type with `gen_random_uuid()`.
+**Solution:** Uses `text` column with customizable ID generator (default: `crypto.randomUUID()`).
 
 ```typescript
-// After: uuid('id').defaultRandom().primaryKey()
+// Default: text('id').primaryKey().$defaultFn(() => crypto.randomUUID())
+// Custom: text('id').primaryKey().$defaultFn(() => nanoid())
 ```
 
+**Benefits:**
+- Maximum database compatibility with `text` column type
+- Customizable ID generation (UUID, nanoid, cuid, etc.)
+- Application-level ID generation via `$defaultFn()`
+
 ### Case-Insensitive REGEXP (IREGEXP)
 
 **File:** `packages/core/src/base/repositories/operators/query.ts`
@@ -188,7 +194,7 @@ await repo.find({ filter: { where: { age: { BETWEEN: [10] } } } });
 |------|---------|
 | `src/base/models/base.ts` | Static schema/relations support, IEntity interface |
 | `src/base/models/common/types.ts` | IEntity interface definition |
-| `src/base/models/enrichers/id.enricher.ts` | Native PostgreSQL UUID type |
+| `src/base/models/enrichers/id.enricher.ts` | Text column with customizable ID generator |
 | `src/base/repositories/core/base.ts` | Constructor signature change, relations auto-resolution |
 | `src/base/repositories/core/readable.ts` | Constructor change, getQueryInterface validation |
 | `src/base/repositories/core/persistable.ts` | Constructor change, log option, TypeScript overloads |
@@ -246,4 +252,4 @@ Replace MySQL-style REGEXP with PostgreSQL syntax:
 - `REGEXP` → uses `~` (case-sensitive)
 - `IREGEXP` → uses `~*` (case-insensitive)
 
-```
+```

package/wiki/changelogs/2025-12-26-nested-relations-and-generics.md

@@ -13,7 +13,7 @@ This update introduces support for deeply nested relation queries in repositorie
 
 - **Nested Inclusions**: `include` filters now work recursively to any depth.
 - **Generic Repository Methods**: `find<R>`, `findOne<R>`, etc. now support custom return types.
-- **DrizzleFilterBuilder Decoupling**: Decoupled filter builder from MetadataRegistry for cleaner architecture.
+- **FilterBuilder Decoupling**: Decoupled filter builder from MetadataRegistry for cleaner architecture.
 
 ## New Features
 
@@ -21,7 +21,7 @@ This update introduces support for deeply nested relation queries in repositorie
 
 **File:** `packages/core/src/base/repositories/operators/filter.ts`
 
-**Problem:** Previously, the `DrizzleFilterBuilder` could only resolve relations for the root entity. Nested includes (e.g., `include: [{ relation: 'a', scope: { include: [{ relation: 'b' }] } }]`) failed because it didn't know the schema of relation 'a'.
+**Problem:** Previously, the `FilterBuilder` could only resolve relations for the root entity. Nested includes (e.g., `include: [{ relation: 'a', scope: { include: [{ relation: 'b' }] } }]`) failed because it didn't know the schema of relation 'a'.
 
 **Solution:** The builder now accepts a `relationResolver` function (injected from the Repository) which allows it to dynamically lookup schemas and relations for any entity during recursive traversal.