@venizia/ignis-docs 0.0.1-8 → 0.0.1

package/LICENSE.md

@@ -33,6 +33,7 @@ This monorepo contains the following packages, all licensed under MIT:
 | Package | Description |
 |---------|-------------|
 | `@venizia/ignis` | Core framework - controllers, services, decorators |
+| `@venizia/ignis-boot` | Application bootstrapping & artifact auto-discovery |
 | `@venizia/ignis-helpers` | Utility helpers - logging, cron, Redis, queues, storage |
 | `@venizia/ignis-inversion` | Dependency Injection & IoC container |
 | `@venizia/dev-configs` | Shared ESLint, Prettier, TypeScript configurations |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/ignis-docs",
-  "version": "0.0.1-8",
+  "version": "0.0.1",
   "description": "Documentation and MCP Server for Ignis Framework",
   "keywords": [
     "ignis",
@@ -111,7 +111,7 @@
     "@braintree/sanitize-url": "^7.1.1",
     "@types/bun": "^1.3.4",
     "@types/glob": "^8.1.0",
-    "@venizia/dev-configs": "^0.0.1-4",
+    "@venizia/dev-configs": "^0.0.2",
     "eslint": "^9.36.0",
     "glob": "^10.4.2",
     "prettier": "^3.6.2",

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

@@ -0,0 +1,145 @@
+---
+title: Initial Architecture
+description: Documentation of the original Ignis architecture before the Model-Repository-DataSource refactor
+---
+
+# Changelog - 2025-12-16
+
+## Initial Architecture (Pre-Refactor)
+
+This documents the original architecture of the Ignis framework before the Model-Repository-DataSource refactor. This version required manual schema registration and explicit constructor parameters.
+
+## Overview
+
+- **Model Definition**: Three separate declarations (table, relations, class) for each model.
+- **DataSource Definition**: Required manual schema registration.
+- **Repository Definition**: Required explicit constructor injection.
+
+## Architecture Pattern
+
+### Model Definition
+
+Models were defined in three separate steps:
+
+```typescript
+// Step 1: Define table schema
+const TABLE_NAME = 'Configuration';
+
+export const configurationTable = pgTable(TABLE_NAME, {
+  ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+  ...generateTzColumnDefs(),
+  code: text('code').notNull(),
+  group: text('group').notNull(),
+});
+
+// Step 2: Define relations separately
+export const configurationRelations = createRelations({
+  source: configurationTable,
+  relations: [
+    {
+      name: 'creator',
+      type: RelationTypes.ONE,
+      schema: userTable,
+      metadata: {
+        fields: [configurationTable.createdBy],
+        references: [userTable.id],
+      },
+    },
+  ],
+});
+
+// Step 3: Create model class
+@model({ type: 'entity', skipMigrate: false })
+export class Configuration extends BaseEntity<typeof configurationTable> {
+  static readonly TABLE_NAME = Configuration.name;
+
+  constructor() {
+    super({
+      name: Configuration.TABLE_NAME,
+      schema: configurationTable,
+    });
+  }
+}
+```
+
+### DataSource Definition
+
+DataSources required manual schema registration:
+
+```typescript
+@datasource({})
+export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      driver: 'node-postgres',
+      config: { /* connection config */ },
+
+      // Manual schema registration - verbose and error-prone
+      schema: Object.assign(
+        {},
+        {
+          [User.TABLE_NAME]: userTable,
+          [Configuration.TABLE_NAME]: configurationTable,
+        },
+        {
+          userRelations: userRelations.relations,
+          configurationRelations: configurationRelations.relations,
+        },
+      ),
+    });
+  }
+}
+```
+
+### Repository Definition
+
+Repositories required explicit constructor injection:
+
+```typescript
+@repository({})
+export class ConfigurationRepository extends DefaultCRUDRepository<typeof configurationTable> {
+  constructor(@inject({ key: 'datasources.PostgresDataSource' }) dataSource: IDataSource) {
+    super({
+      dataSource,
+      entityClass: Configuration,
+      relations: configurationRelations.definitions,
+    });
+  }
+}
+```
+
+## Pain Points
+
+- **Verbose Model Definition**: Three separate declarations (table, relations, class) for each model
+- **Manual Schema Registration**: DataSource required explicit registration of every model and relation
+- **Unclear Repository Role**: Repository just wrapped datasource without defining the model-datasource binding
+- **Declaration Order Issues**: Had to declare table before relations, relations before class
+- **No Auto-Discovery**: Adding a new model required updates in multiple places
+- **Tight Coupling**: Changes to model structure required updates in datasource configuration
+
+## File Structure
+
+```
+src/
+├── models/
+│   └── entities/
+│       ├── user.model.ts          # Table + Relations + Class
+│       └── configuration.model.ts # Table + Relations + Class
+├── datasources/
+│   └── postgres.datasource.ts     # Manual schema assembly
+└── repositories/
+    ├── user.repository.ts         # Explicit constructor injection
+    └── configuration.repository.ts
+```
+
+## Dependencies
+
+- `@venizia/ignis-helpers`: Core utilities and types
+- `@venizia/ignis-inversion`: Dependency injection
+- `drizzle-orm`: ORM layer
+- `drizzle-zod`: Schema validation
+
+## No Breaking Changes
+
+This document describes the initial state of the architecture.

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

@@ -0,0 +1,300 @@
+---
+title: Model-Repository-DataSource Refactor
+description: Major architecture refactor following Loopback 4 patterns with auto-discovery
+---
+
+# Changelog - 2025-12-16
+
+## Model-Repository-DataSource Architecture Refactor
+
+Major architecture refactor following Loopback 4 patterns with auto-discovery.
+
+## Overview
+
+- **Self-Contained Models**: Model is self-contained with schema and relations.
+- **Repository Auto-Resolution**: Repository connects Model to DataSource (defines the binding).
+- **DataSource Auto-Discovery**: DataSource auto-discovers schemas from registered repositories.
+
+## Breaking Changes
+
+> [!WARNING]
+> This section contains changes that require migration or manual updates to existing code.
+
+### 1. Model Static Properties
+
+**Before:**
+```typescript
+const userTable = pgTable('User', {...});
+const userRelations = createRelations({...});
+
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof userTable> {
+  constructor() {
+    super({ name: 'User', schema: userTable });
+  }
+}
+```
+
+**After:**
+```typescript
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = pgTable('User', {...});
+  static override relations = () => ({...});
+}
+```
+
+### 2. Repository Constructor
+
+**Before:**
+```typescript
+@repository({})
+export class UserRepository extends DefaultCRUDRepository<typeof userTable> {
+  constructor(@inject({ key: 'datasources.PostgresDataSource' }) dataSource: IDataSource) {
+    super({ dataSource, entityClass: User, relations: userRelations.definitions });
+  }
+}
+```
+
+**After:**
+```typescript
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
+  // No constructor needed!
+}
+```
+
+### 3. DataSource Schema
+
+**Before:**
+```typescript
+@datasource({})
+export class PostgresDataSource extends BaseDataSource {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      driver: 'node-postgres',
+      config: {...},
+      schema: { User: userTable, userRelations: userRelations.relations, ... },
+    });
+  }
+}
+```
+
+**After:**
+```typescript
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      driver: 'node-postgres',
+      config: {...},
+      // NO schema - auto-discovered!
+    });
+  }
+}
+```
+
+## New Features
+
+### Self-Contained Models
+
+**File:** `packages/core/src/base/models/base.ts`
+
+**Problem:** Models were defined in three separate declarations (table, relations, class).
+
+**Solution:** Models now define schema and relations as static properties.
+
+```typescript
+@model({ type: 'entity' })
+export class Configuration extends BaseEntity<typeof Configuration.schema> {
+  static override schema = pgTable('Configuration', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    ...generateTzColumnDefs(),
+    code: text('code').notNull(),
+    group: text('group').notNull(),
+  });
+
+  static override relations = () => ({
+    creator: {
+      type: 'one' as const,
+      target: () => User,
+      fields: [Configuration.schema.createdBy],
+      references: () => [User.schema.id],
+    },
+  });
+}
+```
+
+**Benefits:**
+- Simplified Model Definition
+- Better Type Safety
+
+### Repository Auto-Resolution
+
+**File:** `packages/core/src/base/repositories/core/base.ts`
+
+**Problem:** Repositories required explicit constructor injection and parameter passing.
+
+**Solution:** Repositories now use `@repository` decorator for model-datasource binding.
+
+```typescript
+@repository({
+  model: Configuration,
+  dataSource: PostgresDataSource,
+})
+export class ConfigurationRepository extends DefaultCRUDRepository<typeof Configuration.schema> {
+  // No constructor needed!
+
+  async findByCode(code: string) {
+    return this.findOne({ filter: { where: { code } } });
+  }
+}
+```
+
+**Benefits:**
+- Reduced Boilerplate
+- Clear Repository Role
+
+### DataSource Auto-Discovery
+
+**File:** `packages/core/src/base/datasources/base.ts`
+
+**Problem:** DataSources required manual schema registration of every model and relation.
+
+**Solution:** DataSources automatically discover their schema from repository bindings.
+
+```typescript
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      driver: 'node-postgres',
+      config: { /* connection config */ },
+      // NO schema property - auto-discovered!
+    });
+  }
+
+  override configure(): ValueOrPromise<void> {
+    const schema = this.getSchema(); // Auto-discovers from @repository bindings
+    this.connector = drizzle({ client: new Pool(this.settings), schema });
+  }
+}
+```
+
+**Benefits:**
+- No Manual Schema Registration
+- Decoupled Models and DataSources
+
+## Files Changed
+
+### Core Package (`packages/core`)
+
+| File | Changes |
+|------|---------|
+| `src/base/models/base.ts` | Added static `schema`, `relations`, `TABLE_NAME` |
+| `src/base/datasources/base.ts` | Added auto-discovery via `buildAutoDiscoveredSchema()` |
+| `src/base/repositories/core/base.ts` | Added lazy resolution, static container reference |
+| `src/base/repositories/core/readable.ts` | Made constructor opts optional |
+| `src/base/repositories/core/persistable.ts` | Made constructor opts optional |
+| `src/base/repositories/core/default-crud.ts` | Added documentation |
+| `src/base/metadata/persistents.ts` | Updated decorators for auto-discovery |
+| `src/base/applications/base.ts` | Added `AbstractRepository.setContainer(this)` |
+| `src/components/static-asset/models/base.model.ts` | Updated to new pattern |
+
+### Helpers Package (`packages/helpers`)
+
+| File | Changes |
+|------|---------|
+| `src/helpers/inversion/common/types.ts` | Added `IModelMetadata`, `IRelationDefinition`, `IModelStatic`, `IRepositoryMetadata`, `IRepositoryBinding` |
+| `src/helpers/inversion/registry.ts` | Added `registerModel`, `registerRepositoryBinding`, `buildDataSourceSchema` |
+
+### Examples (`examples/vert`)
+
+| File | Changes |
+|------|---------|
+| `src/models/entities/user.model.ts` | Updated to static schema pattern |
+| `src/models/entities/configuration.model.ts` | Updated to static schema pattern |
+| `src/datasources/postgres.datasource.ts` | Removed manual schema registration |
+| `src/repositories/user.repository.ts` | Updated to use `@repository` decorator |
+| `src/repositories/configuration.repository.ts` | Updated to use `@repository` decorator |
+
+## Migration Guide
+
+> [!NOTE]
+> Follow these steps if you're upgrading from a previous version.
+
+### Step 1: Update Models
+
+Update models to use static properties for schema and relations.
+
+```typescript
+// From
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof userTable> {
+  constructor() {
+    super({ name: 'User', schema: userTable });
+  }
+}
+
+// To
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = pgTable('User', {...});
+  static override relations = () => ({...});
+}
+```
+
+### Step 2: Update Repositories
+
+Update repositories to use the `@repository` decorator with `model` and `dataSource`.
+
+```typescript
+// From
+@repository({})
+export class UserRepository extends DefaultCRUDRepository<typeof userTable> {
+  constructor(@inject({ key: 'datasources.PostgresDataSource' }) dataSource: IDataSource) {
+    super({ dataSource, entityClass: User, relations: userRelations.definitions });
+  }
+}
+
+// To
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
+  // No constructor needed!
+}
+```
+
+### Step 3: Update DataSources
+
+Remove manual schema registration from DataSources.
+
+```typescript
+// From
+@datasource({})
+export class PostgresDataSource extends BaseDataSource {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      driver: 'node-postgres',
+      config: {...},
+      schema: { User: userTable, userRelations: userRelations.relations, ... },
+    });
+  }
+}
+
+// To
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      driver: 'node-postgres',
+      config: {...},
+      // NO schema - auto-discovered!
+    });
+  }
+}
+```

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

@@ -0,0 +1,90 @@
+---
+title: Inversion of Control Refactor
+description: Dependency Injection system extracted to standalone package
+---
+
+# Changelog - 2025-12-17
+
+## Inversion of Control Refactor
+
+The Dependency Injection (DI) system has been extracted from `packages/helpers` into a standalone package `@venizia/ignis-inversion`.
+
+## Overview
+
+- **New Package**: `@venizia/ignis-inversion` created.
+- **Separation of Concerns**: `inversion` package has zero dependencies on the rest of the framework (except `lodash`, `reflect-metadata`, `zod`).
+- **Refactor**: `packages/core` now imports DI primitives from `@venizia/ignis-inversion`.
+
+## Breaking Changes
+
+> [!WARNING]
+> This section contains changes that require migration or manual updates to existing code.
+
+### 1. Deep Imports
+
+**Before:**
+```typescript
+import { inject } from '@venizia/ignis-helpers/src/helpers/inversion';
+```
+
+**After:**
+```typescript
+import { inject } from '@venizia/ignis-inversion';
+// OR via re-exports (if available)
+import { inject } from '@venizia/ignis';
+```
+
+Deep imports to `helpers/inversion` within `@venizia/ignis-helpers` will no longer work as the directory has been removed.
+
+## Files Changed
+
+### Core Package (`packages/core`)
+
+| File | Changes |
+|------|---------|
+| `src/helpers/inversion/` | Refactored to re-export from `@venizia/ignis-inversion` and add core extensions |
+| `src/mixins/server-config.mixin.ts` | Removed |
+
+### Helpers Package (`packages/helpers`)
+
+| File | Changes |
+|------|---------|
+| `src/helpers/inversion/` | **Deleted** (Moved to new package) |
+
+### Inversion Package (`packages/inversion`)
+
+| File | Changes |
+|------|---------|
+| `package.json` | **Created** |
+| `src/` | **Created** (Content moved from helpers) |
+
+### Examples (`examples/vert`)
+
+| File | Changes |
+|------|---------|
+| `package.json` | Added `@venizia/ignis-inversion` dependency |
+
+## Migration Guide
+
+> [!NOTE]
+> Follow these steps if you're upgrading from a previous version.
+
+### Step 1: Update Imports
+
+Check for any deep imports to `packages/helpers/src/helpers/inversion` and update them to point to `@venizia/ignis-inversion`.
+
+```typescript
+// Find
+from '@venizia/ignis-helpers/src/helpers/inversion'
+
+// Replace with
+from '@venizia/ignis-inversion'
+```
+
+### Step 2: Install New Package
+
+If you are using the DI system directly, add the new package to your dependencies.
+
+```bash
+npm install @venizia/ignis-inversion
+```

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

@@ -0,0 +1,130 @@
+---
+title: Performance Optimizations
+description: Repository layer performance improvements reducing GC pressure and improving query speed
+---
+
+# 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
+
+### 2. Core API for Flat Queries
+
+**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)
+```
+
+| Scenario | Improvement |
+|----------|-------------|
+| Simple `find()` queries | ~15-20% faster |
+
+### 3. Static schemaFactory Singleton
+
+**File:** `packages/core/src/base/models/base.ts`
+
+**Problem:** New `schemaFactory` was created for every `BaseEntity` instance, causing 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()`.
+
+**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
+
+## Files Changed
+
+### Core Package (`packages/core`)
+
+| File | Changes |
+|------|---------|
+| `src/base/repositories/operators/filter.ts` | WeakMap cache for `getTableColumns()` |
+| `src/base/repositories/core/readable.ts` | Core API optimization, async/await refactor |
+| `src/base/repositories/core/persistable.ts` | Async/await refactor |
+| `src/base/models/base.ts` | Static schemaFactory singleton |
+
+## No Breaking Changes
+
+All changes are internal optimizations. No API changes or migration required.