@venizia/ignis-docs 0.0.1-8 → 0.0.1-9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/ignis-docs",
-  "version": "0.0.1-8",
+  "version": "0.0.1-9",
   "description": "Documentation and MCP Server for Ignis Framework",
   "keywords": [
     "ignis",

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

@@ -0,0 +1,22 @@
+# Changelog - 2025-12-17
+
+## Major Refactor: Inversion of Control
+
+The Dependency Injection (DI) system has been extracted from `packages/helpers` into a standalone package `@venizia/ignis-inversion`.
+
+### Changes
+
+-   **New Package**: `@venizia/ignis-inversion` created.
+-   **Removed**: `packages/helpers/src/helpers/inversion` deleted.
+-   **Updated**: `packages/core` now imports DI primitives from `@venizia/ignis-inversion`.
+-   **Refactored**: `packages/core/src/helpers/inversion` now re-exports from the new package and adds core-specific extensions.
+
+### Impact
+
+-   **Imports**: Imports from `@venizia/ignis` or `@venizia/ignis-helpers` relating to `Binding`, `Container`, `inject` should generally remain compatible via re-exports, but deep imports to `helpers/inversion` will break.
+-   **Structure**: Clearer separation of concerns. `inversion` package has zero dependencies on the rest of the framework (except `lodash`, `reflect-metadata`, `zod`).
+
+## Other Changes
+
+-   **Mixins**: `server-config.mixin.ts` removed from `packages/core`.
+-   **Examples**: `examples/vert` updated to reflect latest core changes.

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

@@ -0,0 +1,192 @@
+# Changelog - 2025-12-18
+
+## Performance Optimizations
+
+This update focuses on performance improvements for the repository layer, reducing GC pressure and improving query execution speed.
+
+## Overview
+
+- **WeakMap Cache**: `DrizzleFilterBuilder` 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
+
+## Performance Improvements
+
+### 1. WeakMap Cache for Filter Builder
+
+**File:** `packages/core/src/base/repositories/operators/filter.ts`
+
+**Problem:** `getTableColumns()` was called on every filter operation, causing repeated reflection overhead.
+
+**Solution:** Added static WeakMap cache that stores column metadata per schema:
+
+```typescript
+export class DrizzleFilterBuilder extends BaseHelper {
+  // Static cache shared across all instances
+  private static columnCache = new WeakMap<
+    TTableSchemaWithId,
+    ReturnType<typeof getTableColumns>
+  >();
+
+  private getColumns<Schema extends TTableSchemaWithId>(schema: Schema) {
+    let columns = DrizzleFilterBuilder.columnCache.get(schema);
+    if (!columns) {
+      columns = getTableColumns(schema);
+      DrizzleFilterBuilder.columnCache.set(schema, columns);
+    }
+    return columns;
+  }
+}
+```
+
+**Benefits:**
+- First call: `getTableColumns(schema)` → cached
+- Subsequent calls: Retrieved from WeakMap (O(1) lookup)
+- WeakMap allows garbage collection when schema is no longer referenced
+- Especially beneficial for:
+  - High-concurrency environments
+  - Queries with nested AND/OR conditions (each recursion reuses cache)
+  - Multiple queries to the same table
+
+### 2. Core API for Flat Queries (~15-20% Faster)
+
+**File:** `packages/core/src/base/repositories/core/readable.ts`
+
+**Problem:** All queries used Drizzle's Query API, which has overhead for relational mapping even when not needed.
+
+**Solution:** Automatically use Drizzle Core API for flat queries (no relations, no field selection):
+
+```typescript
+// Automatic optimization - no code changes needed
+const users = await repo.find({
+  filter: {
+    where: { status: 'active' },
+    limit: 10,
+    order: ['createdAt DESC'],
+  }
+});
+// Uses: db.select().from(table).where(...).orderBy(...).limit(10)
+```
+
+**When Core API is used:**
+
+| Filter Options | API Used | Reason |
+|----------------|----------|--------|
+| `where`, `limit`, `order`, `offset` only | Core API | Flat query, no overhead |
+| Has `include` (relations) | Query API | Needs relational mapper |
+| Has `fields` selection | Query API | Core API field syntax differs |
+
+**New Protected Methods:**
+
+```typescript
+// Check if Core API can be used
+protected canUseCoreAPI(filter: TFilter<DataObject>): boolean;
+
+// Execute flat query using Core API
+protected async findWithCoreAPI(opts: {
+  filter: TFilter<DataObject>;
+  findOne?: boolean;
+}): Promise<Array<DataObject>>;
+```
+
+### 3. Static schemaFactory Singleton
+
+**File:** `packages/core/src/base/models/base.ts`
+
+**Problem:** New `schemaFactory` was created for every `BaseEntity` instance:
+
+```typescript
+// Before - created on every instantiation
+constructor(opts?: { name?: string; schema?: Schema }) {
+  this.schemaFactory = createSchemaFactory();  // Memory overhead!
+}
+```
+
+**Solution:** Lazy singleton pattern shared across all instances:
+
+```typescript
+// After - shared singleton
+private static _schemaFactory?: ReturnType<typeof createSchemaFactory>;
+protected static get schemaFactory(): ReturnType<typeof createSchemaFactory> {
+  return (BaseEntity._schemaFactory ??= createSchemaFactory());
+}
+```
+
+**Benefits:**
+- Single instance for all entities
+- Lazy initialization (created on first use)
+- Reduced memory footprint
+
+### 4. Async/Await Refactor
+
+**Files:**
+- `packages/core/src/base/repositories/core/readable.ts`
+- `packages/core/src/base/repositories/core/persistable.ts`
+
+**Problem:** Every CRUD method wrapped existing promises in `new Promise()`:
+
+```typescript
+// Before - Anti-pattern
+return new Promise((resolve, reject) => {
+  this.connector.$count(this.entity.schema, where)
+    .then((count: number) => resolve({ count }))
+    .catch(reject);
+});
+```
+
+**Solution:** Direct async/await:
+
+```typescript
+// After - Clean and efficient
+const count = await this.connector.$count(this.entity.schema, where);
+return { count };
+```
+
+**Benefits:**
+- Eliminates extra microtask queue entries
+- Reduces ~200-400 bytes memory per Promise on V8
+- Cleaner stack traces for debugging
+- For bulk operations, overhead reduction multiplies
+
+## Implementation Details
+
+### Type Safety in Core API
+
+The Core API implementation uses a controlled type assertion at the boundary:
+
+```typescript
+// Type assertion to PgTable is safe: EntitySchema extends TTableSchemaWithId which extends PgTable
+const table = schema as unknown as PgTable;
+let query = this.connector.select().from(table).$dynamic();
+```
+
+This approach:
+- Maintains type safety within the method
+- Uses `$dynamic()` for query building with proper types
+- Returns correctly typed `Promise<Array<DataObject>>`
+
+## Files Changed
+
+### Core Package - Repositories
+- `packages/core/src/base/repositories/operators/filter.ts` - WeakMap cache for `getTableColumns()`
+- `packages/core/src/base/repositories/core/readable.ts` - Core API optimization, async/await refactor
+- `packages/core/src/base/repositories/core/persistable.ts` - Async/await refactor
+
+### Core Package - Models
+- `packages/core/src/base/models/base.ts` - Static schemaFactory singleton
+
+## Benchmarks
+
+These optimizations target the following scenarios:
+
+| Scenario | Improvement |
+|----------|-------------|
+| Simple `find()` queries | ~15-20% faster (Core API) |
+| Repeated filter builds | Eliminates reflection overhead (WeakMap) |
+| Entity instantiation | Reduced memory per instance (schemaFactory) |
+| All CRUD operations | Reduced GC pressure (async/await) |
+
+## No Breaking Changes
+
+All changes are internal optimizations. No API changes or migration required.

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

@@ -0,0 +1,445 @@
+# 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 - no manual merging needed!
+- **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
+
+### 1. Repository Constructor Signature Changed
+
+**This is a major breaking change.** The constructor signature for all repository classes has changed.
+
+**Before:**
+```typescript
+constructor(opts: {
+  entityClass: TClass<BaseEntity<EntitySchema>>;
+  relations: { [relationName: string]: TRelationConfig };
+  dataSource: IDataSource;
+})
+```
+
+**After:**
+```typescript
+constructor(ds?: IDataSource, opts?: { entityClass?: TClass<BaseEntity<EntitySchema>> })
+```
+
+**Key changes:**
+- DataSource is now the first parameter (auto-injected from `@repository` decorator)
+- `relations` parameter removed - now auto-resolved from entity's static `relations` property
+- Both parameters are optional when using `@repository` decorator with `model` and `dataSource`
+
+**Migration:**
+```typescript
+// Before
+@repository({})
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
+  constructor(
+    @inject({ key: 'datasources.PostgresDataSource' }) ds: PostgresDataSource,
+  ) {
+    super({
+      entityClass: User,
+      relations: userRelations.definitions,
+      dataSource: ds,
+    });
+  }
+}
+
+// After - Zero boilerplate
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
+  // No constructor needed!
+}
+
+// After - 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, entity and relations auto-resolved
+  }
+}
+```
+
+### 2. @repository Decorator Requires Both `model` AND `dataSource`
+
+**Before (would silently fail to register model):**
+```typescript
+// ❌ This would not register User for schema auto-discovery
+@repository({ model: User })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {}
+```
+
+**After (throws error):**
+```typescript
+// Error: [@repository][UserRepository] Invalid metadata | Missing 'dataSource'
+@repository({ model: User })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {}
+
+// ✅ Correct usage
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {}
+```
+
+### 2. Constructor First Parameter Must Be DataSource Type
+
+When using explicit `@inject` in constructor, the first parameter **must** extend `AbstractDataSource`:
+
+**Before (would work with wrong type):**
+```typescript
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends ReadableRepository<typeof User.schema> {
+  constructor(
+    @inject({ key: 'datasources.PostgresDataSource' })
+    dataSource: any, // ❌ This would compile but is wrong
+  ) {
+    super(dataSource);
+  }
+}
+```
+
+**After (enforced at decorator time):**
+```typescript
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends ReadableRepository<typeof User.schema> {
+  constructor(
+    @inject({ key: 'datasources.PostgresDataSource' })
+    dataSource: PostgresDataSource, // ✅ Must be concrete DataSource type
+  ) {
+    super(dataSource);
+  }
+}
+```
+
+### 3. Filter Column Validation
+
+Invalid column names now throw errors instead of being silently ignored:
+
+**Before:**
+```typescript
+// Would silently ignore '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' } } });
+```
+
+## Security Fixes
+
+### Empty IN Array Bypass (CVE-like)
+
+**Vulnerability:** Empty `IN` arrays would return `true`, bypassing security filters.
+
+**Fix:** Empty `IN` arrays now return `sql\`false\``, correctly matching no records.
+
+```typescript
+// Before: WHERE id IN () => true (security bypass!)
+// After: WHERE false => no records (correct)
+await repo.find({ filter: { where: { id: { IN: [] } } } });
+```
+
+### BETWEEN Validation
+
+**Vulnerability:** Invalid `BETWEEN` values could cause unexpected behavior.
+
+**Fix:** BETWEEN now validates input is array of exactly 2 elements.
+
+```typescript
+// Throws: [BETWEEN] Invalid value: expected array of 2 elements
+await repo.find({ filter: { where: { age: { BETWEEN: [10] } } } });
+```
+
+### PostgreSQL REGEXP Compatibility
+
+**Issue:** MySQL-style REGEXP operator doesn't work in PostgreSQL.
+
+**Fix:** Now uses PostgreSQL POSIX regex operators:
+- `REGEXP` → `~` (case-sensitive)
+- `IREGEXP` → `~*` (case-insensitive, new!)
+
+```typescript
+// PostgreSQL-compatible regex
+await repo.find({ filter: { where: { name: { REGEXP: '^John' } } } });
+await repo.find({ filter: { where: { name: { IREGEXP: '^john' } } } }); // Case-insensitive
+```
+
+## New Features
+
+### DataSource Schema Auto-Discovery
+
+DataSources can now automatically discover their schema from registered `@repository` decorators:
+
+```typescript
+// Before: Manual schema merging required
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource<...> {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      config: { /* ... */ },
+      schema: Object.assign({}, // Manual merge!
+        { [User.TABLE_NAME]: userTable },
+        userRelations.relations,
+      ),
+    });
+  }
+}
+
+// After: Auto-discovery - no schema needed!
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource<...> {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      config: { /* ... */ },
+      // Schema auto-discovered from @repository decorators!
+    });
+  }
+}
+```
+
+When repositories are defined with `@repository({ model: User, dataSource: PostgresDataSource })`, the framework automatically builds the schema.
+
+### Schema Key Mismatch Validation
+
+Added helpful error when entity name doesn't match schema keys:
+
+```typescript
+// Error: [UserRepository] Schema key mismatch | Entity name 'User' not found in connector.query | Available keys: [Configuration, Post]
+```
+
+### UUID Type Improvement
+
+Changed from `text` type with JS-generated UUID to native PostgreSQL `uuid`:
+
+```typescript
+// Before: text('id').primaryKey().$defaultFn(() => crypto.randomUUID())
+// After: uuid('id').defaultRandom().primaryKey()
+```
+
+Benefits:
+- Native PostgreSQL UUID type (16 bytes vs 36 bytes)
+- Uses `gen_random_uuid()` - no extension required
+- Better indexing performance
+
+### Case-Insensitive REGEXP (IREGEXP)
+
+Added new `IREGEXP` operator for case-insensitive regex matching:
+
+```typescript
+// Case-sensitive (existing)
+await repo.find({ filter: { where: { name: { REGEXP: '^John' } } } });
+
+// Case-insensitive (new!)
+await repo.find({ filter: { where: { name: { IREGEXP: '^john' } } } });
+```
+
+### BaseEntity Static Schema & Relations
+
+Models can now define schema and relations as static properties, enabling cleaner syntax:
+
+```typescript
+// Before - Constructor-based schema
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof userTable> {
+  constructor() {
+    super({ name: 'User', schema: userTable });
+  }
+}
+
+// After - Static schema (recommended)
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = userTable;
+  static override relations = () => userRelations.definitions;
+  static override TABLE_NAME = 'User';
+}
+```
+
+Relations are now auto-resolved from the entity's static `relations` property - no need to pass them in repository constructor.
+
+### Repository Log Option
+
+All CRUD operations now support a `log` option for debugging:
+
+```typescript
+// Enable logging for a specific operation
+await repo.create({
+  data: { name: 'John' },
+  options: {
+    log: { use: true, level: 'debug' }
+  }
+});
+
+// Log output: [_create] Executing with opts: { data: [...], options: {...} }
+```
+
+**Available on:** `create`, `createAll`, `updateById`, `updateAll`, `deleteById`, `deleteAll`
+
+### Improved TypeScript Return Types
+
+Repository methods now have better type inference based on `shouldReturn`:
+
+```typescript
+// When shouldReturn: false - returns null
+const result1 = await repo.create({
+  data: { name: 'John' },
+  options: { shouldReturn: false }
+});
+// Type: Promise<TCount & { data: null }>
+
+// When shouldReturn: true (default) - returns the entity
+const result2 = await repo.create({
+  data: { name: 'John' },
+  options: { shouldReturn: true }
+});
+// Type: Promise<TCount & { data: User }>
+
+// TypeScript now correctly infers the return type!
+```
+
+### IEntity Interface
+
+New interface for model classes with static schema and relations:
+
+```typescript
+interface IEntity<Schema extends TTableSchemaWithId = TTableSchemaWithId> {
+  TABLE_NAME?: string;
+  schema: Schema;
+  relations?: TValueOrResolver<Array<TRelationConfig>>;
+}
+```
+
+## Files Changed
+
+### Core Package - Models
+- `packages/core/src/base/models/base.ts` - Static schema/relations support, IEntity interface
+- `packages/core/src/base/models/common/types.ts` - IEntity interface definition
+- `packages/core/src/base/models/enrichers/id.enricher.ts` - Native PostgreSQL UUID type
+- `packages/core/src/base/models/enrichers/tz.enricher.ts` - Type naming fix
+
+### Core Package - Repositories
+- `packages/core/src/base/repositories/core/base.ts` - Constructor signature change, relations auto-resolution
+- `packages/core/src/base/repositories/core/readable.ts` - Constructor change, getQueryInterface validation
+- `packages/core/src/base/repositories/core/persistable.ts` - Constructor change, log option, TypeScript overloads
+- `packages/core/src/base/repositories/core/default-crud.ts` - Documentation update
+- `packages/core/src/base/repositories/common/types.ts` - TRepositoryLogOptions, TypeScript overloads
+- `packages/core/src/base/repositories/operators/filter.ts` - Column validation, error throwing
+- `packages/core/src/base/repositories/operators/query.ts` - REGEXP/IREGEXP fix, BETWEEN validation, IN empty array fix
+
+### Core Package - DataSources & Metadata
+- `packages/core/src/base/datasources/base.ts` - Schema auto-discovery feature
+- `packages/core/src/base/metadata/persistents.ts` - Repository decorator validation, constructor type validation
+
+### Examples
+- `examples/vert/src/repositories/user.repository.ts` - Updated to proper types
+- `examples/vert/src/repositories/configuration.repository.ts` - Updated patterns
+- `examples/vert/src/datasources/postgres.datasource.ts` - Using auto-discovery
+- `examples/vert/src/models/entities/user.model.ts` - Static schema pattern
+- `examples/vert/src/models/entities/configuration.model.ts` - Static schema pattern
+
+## Migration Guide
+
+### Step 1: Update Repository Constructors (BREAKING)
+
+The repository constructor signature has changed:
+
+```typescript
+// Before
+@repository({})
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
+  constructor(
+    @inject({ key: 'datasources.PostgresDataSource' }) ds: PostgresDataSource,
+  ) {
+    super({
+      entityClass: User,
+      relations: userRelations.definitions,
+      dataSource: ds,
+    });
+  }
+}
+
+// After - Option A: Zero boilerplate (recommended)
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
+  // No constructor needed!
+}
+
+// After - 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 Model Definitions (Optional but Recommended)
+
+Add static properties to your models for relations auto-resolution:
+
+```typescript
+// Before
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof userTable> {
+  constructor() {
+    super({ name: 'User', schema: userTable });
+  }
+}
+
+// After - Static properties
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = userTable;
+  static override relations = () => userRelations.definitions;
+  static override TABLE_NAME = 'User';
+}
+```
+
+### Step 3: Update @repository Decorators
+
+Ensure all `@repository` decorators have both `model` and `dataSource`:
+
+```typescript
+// Find and update all occurrences
+@repository({ model: YourModel, dataSource: YourDataSource })
+```
+
+### Step 4: Fix Constructor Types
+
+If using explicit `@inject`, ensure first parameter has correct type:
+
+```typescript
+constructor(
+  @inject({ key: 'datasources.YourDataSource' })
+  dataSource: YourDataSource, // Not 'any' or 'object'
+) {}
+```
+
+### Step 5: Review Filter Queries
+
+Check for any queries using:
+- Empty `IN` arrays (now return no results instead of all)
+- Invalid column names (now throw errors)
+- `BETWEEN` with non-array or wrong-length values
+
+### Step 6: REGEXP Migration (PostgreSQL Users)
+
+Replace MySQL-style REGEXP with PostgreSQL syntax:
+- REGEXP already works (uses `~` operator)
+- For case-insensitive, use new `IREGEXP` (uses `~*` operator)

package/wiki/changelogs/index.md

@@ -0,0 +1,22 @@
+# Changelogs
+
+This section tracks the history of significant changes, refactors, and updates to the Ignis framework.
+
+## Version History
+
+| Version | Date | Description |
+|---------|------|-------------|
+| [2025-12-18 Performance](./2025-12-18-performance-optimizations.md) | 2025-12-18 | Performance Optimizations (Core API, WeakMap Cache) |
+| [2025-12-18](./2025-12-18-repository-validation-security.md) | 2025-12-18 | Repository Validation & Security Improvements |
+| [2025-12-17](./2025-12-17-refactor.md) | 2025-12-17 | Inversion of Control Refactor |
+| [v0.0.1-8](./v0.0.1-8-model-repo-datasource-refactor.md) | 2025-12-16 | Model-Repository-DataSource Architecture Refactor |
+| [v0.0.1-7](./v0.0.1-7-initial-architecture.md) | 2025-12-16 | Initial Architecture (Pre-Refactor) |
+
+## 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)