@venizia/ignis-docs 0.0.1-8 → 0.0.1

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

@@ -0,0 +1,249 @@
+---
+title: Repository Validation & Security
+description: Strict validation for @repository decorator and security fixes for filter operators
+---
+
+# Changelog - 2025-12-18
+
+## Repository Validation & Security Improvements
+
+This update adds strict validation to the `@repository` decorator and fixes several security vulnerabilities in the filter operators.
+
+## Overview
+
+- **@repository Decorator**: Now requires both `model` AND `dataSource` for schema auto-discovery.
+- **Constructor Validation**: First parameter must extend `AbstractDataSource` (enforced via reflection).
+- **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()`.
+
+## Breaking Changes
+
+> [!WARNING]
+> This section contains changes that require migration or manual updates to existing code.
+
+### 1. Repository Constructor Signature
+
+**Before:**
+```typescript
+constructor(opts: {
+  entityClass: TClass<BaseEntity<EntitySchema>>;
+  relations: { [relationName: string]: TRelationConfig };
+  dataSource: IDataSource;
+})
+```
+
+**After:**
+```typescript
+constructor(ds?: IDataSource, opts?: { entityClass?: TClass<BaseEntity<EntitySchema>> })
+```
+
+### 2. @repository Decorator Requirements
+
+**Before:**
+```typescript
+// Would silently fail to register model
+@repository({ model: User })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {}
+```
+
+**After:**
+```typescript
+// Throws Error: Invalid metadata | Missing 'dataSource'
+@repository({ model: User })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {}
+
+// Correct
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {}
+```
+
+### 3. Constructor Parameter Type
+
+**Before:**
+```typescript
+constructor(
+  @inject({ key: 'datasources.PostgresDataSource' })
+  dataSource: any, // Would compile but is wrong
+)
+```
+
+**After:**
+```typescript
+constructor(
+  @inject({ key: 'datasources.PostgresDataSource' })
+  dataSource: PostgresDataSource, // Must be concrete DataSource type
+)
+```
+
+### 4. Filter Column Validation
+
+**Before:**
+```typescript
+// Silently ignored 'invalidColumn'
+await repo.find({ filter: { where: { invalidColumn: 'value' } } });
+```
+
+**After:**
+```typescript
+// Error: [toWhere] Table: User | Column NOT FOUND | key: 'invalidColumn'
+await repo.find({ filter: { where: { invalidColumn: 'value' } } });
+```
+
+## New Features
+
+### DataSource Schema Auto-Discovery
+
+**File:** `packages/core/src/base/datasources/base.ts`
+
+**Problem:** Manual schema merging was error-prone and verbose.
+
+**Solution:** DataSources automatically discover their schema from `@repository` bindings.
+
+```typescript
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource<...> {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      config: { /* ... */ },
+      // Schema auto-discovered from @repository decorators!
+    });
+  }
+}
+```
+
+### UUID Type Improvement
+
+**File:** `packages/core/src/base/models/enrichers/id.enricher.ts`
+
+**Problem:** JS-generated UUIDs were stored as text, which is less efficient.
+
+**Solution:** Changed to native PostgreSQL `uuid` type with `gen_random_uuid()`.
+
+```typescript
+// After: uuid('id').defaultRandom().primaryKey()
+```
+
+### Case-Insensitive REGEXP (IREGEXP)
+
+**File:** `packages/core/src/base/repositories/operators/query.ts`
+
+**Problem:** PostgreSQL regex matching is case-sensitive by default.
+
+**Solution:** Added `IREGEXP` operator for case-insensitive matching (`~*`).
+
+```typescript
+await repo.find({ filter: { where: { name: { IREGEXP: '^john' } } } });
+```
+
+### Repository Log Option
+
+**File:** `packages/core/src/base/repositories/core/persistable.ts`
+
+**Problem:** Debugging repository operations was difficult without logging.
+
+**Solution:** Added `log` option to all CRUD operations.
+
+```typescript
+await repo.create({
+  data: { name: 'John' },
+  options: {
+    log: { use: true, level: 'debug' }
+  }
+});
+```
+
+## Security Fixes
+
+### Empty IN Array Bypass
+
+**Vulnerability:** Empty `IN` arrays would return `true`, bypassing security filters.
+
+**Fix:** Empty `IN` arrays now return `sql\`false\``. 
+
+```typescript
+// Before: WHERE id IN () => true (bypass)
+// After: WHERE false => no records
+await repo.find({ filter: { where: { id: { IN: [] } } } });
+```
+
+### BETWEEN Validation
+
+**Vulnerability:** Invalid `BETWEEN` values could cause unexpected behavior.
+
+**Fix:** `BETWEEN` now validates input is an array of exactly 2 elements.
+
+```typescript
+// Throws: [BETWEEN] Invalid value: expected array of 2 elements
+await repo.find({ filter: { where: { age: { BETWEEN: [10] } } } });
+```
+
+## Files Changed
+
+### Core Package (`packages/core`)
+
+| File | Changes |
+|------|---------|
+| `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/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 |
+| `src/base/repositories/operators/filter.ts` | Column validation, error throwing |
+| `src/base/repositories/operators/query.ts` | REGEXP/IREGEXP fix, BETWEEN validation, IN empty array fix |
+| `src/base/datasources/base.ts` | Schema auto-discovery feature |
+| `src/base/metadata/persistents.ts` | Repository decorator validation, constructor type validation |
+
+### Examples (`examples/vert`)
+
+| File | Changes |
+|------|---------|
+| `src/repositories/user.repository.ts` | Updated to proper types |
+| `src/repositories/configuration.repository.ts` | Updated patterns |
+| `src/datasources/postgres.datasource.ts` | Using auto-discovery |
+
+## Migration Guide
+
+> [!NOTE]
+> Follow these steps if you're upgrading from a previous version.
+
+### Step 1: Update Repository Constructors
+
+The repository constructor signature has changed. Update all repository classes.
+
+```typescript
+// Option A: Zero boilerplate (recommended)
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
+  // No constructor needed!
+}
+
+// Option B: With explicit constructor
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
+  constructor(
+    @inject({ key: 'datasources.PostgresDataSource' }) ds: PostgresDataSource,
+  ) {
+    super(ds); // Just pass dataSource
+  }
+}
+```
+
+### Step 2: Update @repository Decorators
+
+Ensure all `@repository` decorators have both `model` and `dataSource`.
+
+```typescript
+@repository({ model: YourModel, dataSource: YourDataSource })
+```
+
+### Step 3: REGEXP Migration (PostgreSQL Users)
+
+Replace MySQL-style REGEXP with PostgreSQL syntax:
+- `REGEXP` → uses `~` (case-sensitive)
+- `IREGEXP` → uses `~*` (case-insensitive)
+
+```

package/wiki/changelogs/index.md

@@ -0,0 +1,33 @@
+---
+title: Changelogs
+description: History of significant changes, refactors, and updates to the Ignis framework
+---
+
+# Changelogs
+
+This section tracks the history of significant changes, refactors, and updates to the Ignis framework.
+
+## Planned Features
+
+| Feature | Description | Priority |
+|---------|-------------|----------|
+| [Transaction Support](./planned-transaction-support) | Loopback 4-style explicit transaction objects with isolation levels | Future |
+
+## Recent Changes
+
+| Date | Title | Type |
+|------|-------|------|
+| 2025-12-18 | [Performance Optimizations](./2025-12-18-performance-optimizations) | Enhancement |
+| 2025-12-18 | [Repository Validation & Security](./2025-12-18-repository-validation-security) | Breaking Change, Security |
+| 2025-12-17 | [Inversion of Control Refactor](./2025-12-17-refactor) | Refactor |
+| 2025-12-16 | [Model-Repository-DataSource Refactor](./2025-12-16-model-repo-datasource-refactor) | Breaking Change |
+| 2025-12-16 | [Initial Architecture](./2025-12-16-initial-architecture) | Documentation |
+
+## How to Read Changelogs
+
+Each changelog entry includes:
+- **Overview**: Summary of changes
+- **Breaking Changes**: Any changes that require migration
+- **New Features**: New capabilities added
+- **Files Changed**: List of modified files
+- **Migration Guide**: Steps to update existing code (if applicable)

package/wiki/changelogs/planned-transaction-support.md

@@ -0,0 +1,216 @@
+---
+title: Planned - Transaction Support
+description: Implementation plan for Loopback 4-style explicit transaction objects
+---
+
+# Planned: Transaction Support
+
+**Status:** Planned (Not Yet Implemented)
+**Priority:** Future Enhancement
+
+## Goal
+
+Implement Loopback 4-style explicit transaction objects, allowing transactions to be passed through multiple services/repositories instead of using Drizzle's callback-based approach.
+
+## Target API
+
+```typescript
+// Default isolation level (READ COMMITTED)
+const tx = await userRepo.beginTransaction();
+
+// Or with specific isolation level
+const tx = await userRepo.beginTransaction({
+  isolationLevel: 'SERIALIZABLE'
+});
+
+try {
+  await userRepo.create({ data, options: { transaction: tx } });
+  await profileRepo.create({ data, options: { transaction: tx } });
+  await tx.commit();
+} catch (err) {
+  await tx.rollback();
+  throw err;
+}
+```
+
+### Isolation Levels
+
+| Level | Description | Use Case |
+|-------|-------------|----------|
+| `READ COMMITTED` | Default. Sees only committed data at query start | General use, most common |
+| `REPEATABLE READ` | Sees snapshot from transaction start | Reports, consistent reads |
+| `SERIALIZABLE` | Strictest. Full isolation, may throw serialization errors | Financial transactions, critical data |
+
+---
+
+## Implementation Steps
+
+### Step 1: Define Transaction Types
+
+**File:** `packages/core/src/base/datasources/types.ts`
+
+```typescript
+/** PostgreSQL transaction isolation levels */
+export type TIsolationLevel = 'READ COMMITTED' | 'REPEATABLE READ' | 'SERIALIZABLE';
+
+/** Options for starting a transaction */
+export interface ITransactionOptions {
+  isolationLevel?: TIsolationLevel;
+}
+
+/** Transaction object returned by beginTransaction() */
+export interface ITransaction<Connector = TNodePostgresConnector> {
+  /** Isolated Drizzle instance bound to this transaction */
+  connector: Connector;
+
+  /** Commit the transaction */
+  commit(): Promise<void>;
+
+  /** Rollback the transaction */
+  rollback(): Promise<void>;
+
+  /** Check if transaction is still active */
+  isActive: boolean;
+
+  /** The isolation level used for this transaction */
+  isolationLevel: TIsolationLevel;
+}
+```
+
+### Step 2: Add `beginTransaction()` to DataSource
+
+**File:** `packages/core/src/base/datasources/base.ts`
+
+```typescript
+async beginTransaction(
+  opts?: ITransactionOptions
+): Promise<ITransaction<Connector>> {
+  // 1. Get raw client from pool
+  const pool = this.connector.client as Pool;
+  const client = await pool.connect();
+
+  // 2. Determine isolation level (default: READ COMMITTED)
+  const isolationLevel: TIsolationLevel = opts?.isolationLevel ?? 'READ COMMITTED';
+
+  // 3. Execute BEGIN with isolation level
+  await client.query(`BEGIN TRANSACTION ISOLATION LEVEL ${isolationLevel}`);
+
+  // 4. Create isolated Drizzle instance with this client
+  const txConnector = drizzle({ client, schema: this.schema });
+
+  // 5. Return transaction object
+  let isActive = true;
+
+  return {
+    connector: txConnector as Connector,
+    isActive,
+    isolationLevel,
+
+    async commit() {
+      if (!isActive) throw new Error('Transaction already ended');
+      try {
+        await client.query('COMMIT');
+      } finally {
+        isActive = false;
+        client.release();
+      }
+    },
+
+    async rollback() {
+      if (!isActive) throw new Error('Transaction already ended');
+      try {
+        await client.query('ROLLBACK');
+      } finally {
+        isActive = false;
+        client.release();
+      }
+    },
+  };
+}
+```
+
+### Step 3: Update Repository Base
+
+**File:** `packages/core/src/base/repositories/core/base.ts`
+
+```typescript
+// Add method to start transaction (delegates to DataSource)
+async beginTransaction(opts?: ITransactionOptions): Promise<ITransaction> {
+  return this.dataSource.beginTransaction(opts);
+}
+
+// Replace this.connector with getConnector(opts)
+protected getConnector(opts?: { transaction?: ITransaction }) {
+  if (opts?.transaction) {
+    if (!opts.transaction.isActive) {
+      throw getError({ message: 'Transaction is no longer active' });
+    }
+    return opts.transaction.connector;
+  }
+  return this.dataSource.connector;
+}
+```
+
+### Step 4: Update CRUD Options Types
+
+**File:** `packages/core/src/base/repositories/common/types.ts`
+
+```typescript
+export type TTransactionOption = {
+  transaction?: ITransaction;
+};
+
+// Add to existing option types
+export type TCreateOptions = TTransactionOption & {
+  shouldReturn?: boolean;
+  log?: TRepositoryLogOptions;
+};
+```
+
+### Step 5: Update CRUD Methods
+
+**Files:** `readable.ts`, `persistable.ts`
+
+Change all methods from:
+```typescript
+this.connector.insert(...)
+```
+
+To:
+```typescript
+this.getConnector(opts.options).insert(...)
+```
+
+---
+
+## Files to Modify
+
+| File | Changes |
+|------|---------|
+| `packages/core/src/base/datasources/types.ts` | Add `TIsolationLevel`, `ITransactionOptions`, `ITransaction` |
+| `packages/core/src/base/datasources/base.ts` | Add `beginTransaction(opts?)` method |
+| `packages/core/src/base/repositories/common/types.ts` | Add `TTransactionOption` |
+| `packages/core/src/base/repositories/core/base.ts` | Add `beginTransaction(opts?)`, `getConnector(opts)` |
+| `packages/core/src/base/repositories/core/readable.ts` | Use `getConnector(opts)` in all methods |
+| `packages/core/src/base/repositories/core/persistable.ts` | Use `getConnector(opts)` in all methods |
+
+---
+
+## Breaking Changes
+
+1. **`this.connector`** → `this.getConnector(opts)`
+   - Backward compatible when called without args
+
+2. **Options parameter** - Now includes optional `transaction` field
+   - Non-breaking: transaction is optional
+
+---
+
+## Benefits
+
+| Aspect | Current (Drizzle Callback) | After (Pass-through) |
+|--------|---------------------------|----------------------|
+| Service composition | Hard - all in one callback | Easy - pass tx anywhere |
+| Separation of concerns | Services must know each other | Services stay independent |
+| Testing | Complex mocking | Easy to mock tx object |
+| Code organization | Nested callbacks | Flat, sequential flow |

package/wiki/changelogs/template.md

@@ -0,0 +1,123 @@
+---
+title: [Short Title]
+description: [Brief description of the changes]
+---
+
+# Changelog - YYYY-MM-DD
+
+## [Main Title/Focus Area]
+
+[A brief, high-level summary of the changes in this release. What is the main focus?]
+
+## Overview
+
+- **[Change 1]**: Brief description
+- **[Change 2]**: Brief description
+- **[Change 3]**: Brief description
+
+## Breaking Changes
+
+> [!WARNING]
+> This section contains changes that require migration or manual updates to existing code.
+
+### 1. [Breaking Change Title]
+
+**Before:**
+```typescript
+// Code that no longer works or is deprecated
+```
+
+**After:**
+```typescript
+// New pattern
+```
+
+## New Features
+
+### [Feature Name]
+
+**File:** `packages/core/src/path/to/file.ts`
+
+**Problem:** [What problem does this solve?]
+
+**Solution:** [How does it solve it?]
+
+```typescript
+// Example usage
+```
+
+**Benefits:**
+- Benefit 1
+- Benefit 2
+
+## Security Fixes
+
+### [Security Issue Title]
+
+**Vulnerability:** [Describe the vulnerability]
+
+**Fix:** [Describe the fix]
+
+```typescript
+// Before: vulnerable code behavior
+// After: secure code behavior
+```
+
+## Performance Improvements
+
+### [Performance Improvement Title]
+
+**File:** `packages/core/src/path/to/file.ts`
+
+**Problem:** [What was slow/inefficient?]
+
+**Solution:** [How was it optimized?]
+
+| Scenario | Improvement |
+|----------|-------------|
+| [Use case 1] | [Improvement metric] |
+| [Use case 2] | [Improvement metric] |
+
+## Files Changed
+
+### Core Package (`packages/core`)
+
+| File | Changes |
+|------|---------|
+| `src/base/models/base.ts` | [Description of changes] |
+| `src/base/repositories/core/readable.ts` | [Description of changes] |
+
+### Helpers Package (`packages/helpers`)
+
+| File | Changes |
+|------|---------|
+| `src/utils/index.ts` | [Description of changes] |
+
+### Examples (`examples/vert`)
+
+| File | Changes |
+|------|---------|
+| `src/models/entities/user.model.ts` | [Description of changes] |
+
+## Migration Guide
+
+> [!NOTE]
+> Follow these steps if you're upgrading from a previous version.
+
+### Step 1: [Action Name]
+
+[Instructions]
+
+```typescript
+// Example of the change to apply
+```
+
+### Step 2: [Action Name]
+
+[Instructions]
+
+## No Breaking Changes
+
+[Use this section instead of "Breaking Changes" and "Migration Guide" if there are no breaking changes]
+
+All changes are internal optimizations. No API changes or migration required.

package/wiki/get-started/5-minute-quickstart.md

@@ -253,7 +253,7 @@ Open `http://localhost:3000/doc/explorer` to see interactive Swagger UI document
 })
 async greet(c: Context) {
   const { name } = await c.req.json();
-  return c.json({ greeting: `Hello, ${name}!` });
+  return c.json({ greeting: `Hello, ${name}!` }, HTTP.ResultCodes.RS_2.Ok);
 }
 ```
 

package/wiki/get-started/best-practices/api-usage-examples.md

@@ -52,6 +52,7 @@ import {
   get,
   post,
   TRouteContext,
+  HTTP,
 } from '@venizia/ignis';
 import { ROUTE_CONFIGS } from './definitions';
 
@@ -62,7 +63,7 @@ export class TestController extends BaseController {
   @get({ configs: ROUTE_CONFIGS['/4'] })
   getWithDecorator(context: TRouteContext<(typeof ROUTE_CONFIGS)['/4']>) {
     // context is fully typed!
-    return context.json({ message: 'Hello from decorator', method: 'GET' });
+    return context.json({ message: 'Hello from decorator', method: 'GET' }, HTTP.ResultCodes.RS_2.Ok);
   }
 
   @post({ configs: ROUTE_CONFIGS['/5'] })
@@ -71,11 +72,14 @@ export class TestController extends BaseController {
     const body = context.req.valid('json');
 
     // The response is validated against the schema
-    return context.json({
-      id: crypto.randomUUID(),
-      name: body.name,
-      age: body.age,
-    });
+    return context.json(
+      {
+        id: crypto.randomUUID(),
+        name: body.name,
+        age: body.age,
+      },
+      HTTP.ResultCodes.RS_2.Ok,
+    );
   }
 }
 ```
@@ -97,7 +101,7 @@ export class TestController extends BaseController {
     this.defineRoute({
       configs: ROUTE_CONFIGS['/1'],
       handler: context => {
-        return context.json({ message: 'Hello' });
+        return context.json({ message: 'Hello' }, HTTP.ResultCodes.RS_2.Ok);
       },
     });
 
@@ -106,7 +110,7 @@ export class TestController extends BaseController {
       configs: ROUTE_CONFIGS['/3'],
     }).to({
       handler: context => {
-        return context.json({ message: 'Hello 3' });
+        return context.json({ message: 'Hello 3' }, HTTP.ResultCodes.RS_2.Ok);
       },
     });
   }
@@ -260,5 +264,3 @@ export class PageController extends BaseController {
   }
 }
 ```
-
-```

package/wiki/get-started/best-practices/architectural-patterns.md

@@ -90,7 +90,7 @@ export class ConfigurationController extends _Controller {
     // an instance of ConfigurationRepository here.
     @inject({
       key: BindingKeys.build({
-        namespace: BindingNames...REPOSITORY,
+        namespace: BindingNamespaces.REPOSITORY,
         key: ConfigurationRepository.name,
       }),
     })
@@ -103,7 +103,7 @@ export class ConfigurationController extends _Controller {
 
 ## 3. Component-Based Modularity
 
-Components bundle related features into self-contained, pluggable modules.
+Components bundle a group of related, reusable, and pluggable features into self-contained modules. A single component can encapsulate multiple providers, services, controllers, and repositories, essentially functioning as a mini-application that can be easily "plugged in" to any Ignis project.
 
 **Built-in Components:**
 - `AuthenticateComponent` - JWT authentication