@venizia/ignis-docs 0.0.1-9 → 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-9",
+  "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/{v0.0.1-7-initial-architecture.md → 2025-12-16-initial-architecture.md}

@@ -1,12 +1,20 @@
-# v0.0.1-7 - Initial Architecture (Pre-Refactor)
+---
+title: Initial Architecture
+description: Documentation of the original Ignis architecture before the Model-Repository-DataSource refactor
+---
 
-**Release Date**: 2025-12-16
-**Status**: Superseded by v0.0.1-8
+# Changelog - 2025-12-16
 
-## Overview
+## 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
@@ -103,12 +111,12 @@ export class ConfigurationRepository extends DefaultCRUDRepository<typeof config
 
 ## Pain Points
 
-1. **Verbose Model Definition**: Three separate declarations (table, relations, class) for each model
-2. **Manual Schema Registration**: DataSource required explicit registration of every model and relation
-3. **Unclear Repository Role**: Repository just wrapped datasource without defining the model-datasource binding
-4. **Declaration Order Issues**: Had to declare table before relations, relations before class
-5. **No Auto-Discovery**: Adding a new model required updates in multiple places
-6. **Tight Coupling**: Changes to model structure required updates in datasource configuration
+- **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
 
@@ -132,6 +140,6 @@ src/
 - `drizzle-orm`: ORM layer
 - `drizzle-zod`: Schema validation
 
----
+## No Breaking Changes
 
-*This architecture was superseded by the Loopback 4-style refactor in v0.0.1-8*
+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

@@ -1,22 +1,90 @@
+---
+title: Inversion of Control Refactor
+description: Dependency Injection system extracted to standalone package
+---
+
 # Changelog - 2025-12-17
 
-## Major Refactor: Inversion of Control
+## Inversion of Control Refactor
 
 The Dependency Injection (DI) system has been extracted from `packages/helpers` into a standalone package `@venizia/ignis-inversion`.
 
-### Changes
+## 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`.
 
--   **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.
+```typescript
+// Find
+from '@venizia/ignis-helpers/src/helpers/inversion'
 
-### Impact
+// Replace with
+from '@venizia/ignis-inversion'
+```
 
--   **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`).
+### Step 2: Install New Package
 
-## Other Changes
+If you are using the DI system directly, add the new package to your dependencies.
 
--   **Mixins**: `server-config.mixin.ts` removed from `packages/core`.
--   **Examples**: `examples/vert` updated to reflect latest core changes.
+```bash
+npm install @venizia/ignis-inversion
+```

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

@@ -1,3 +1,8 @@
+---
+title: Performance Optimizations
+description: Repository layer performance improvements reducing GC pressure and improving query speed
+---
+
 # Changelog - 2025-12-18
 
 ## Performance Optimizations
@@ -6,10 +11,10 @@ This update focuses on performance improvements for the repository layer, reduci
 
 ## 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
+- **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
 
@@ -19,7 +24,7 @@ This update focuses on performance improvements for the repository layer, reduci
 
 **Problem:** `getTableColumns()` was called on every filter operation, causing repeated reflection overhead.
 
-**Solution:** Added static WeakMap cache that stores column metadata per schema:
+**Solution:** Added static WeakMap cache that stores column metadata per schema.
 
 ```typescript
 export class DrizzleFilterBuilder extends BaseHelper {
@@ -44,18 +49,14 @@ export class DrizzleFilterBuilder extends BaseHelper {
 - 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)
+### 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):
+**Solution:** Automatically use Drizzle Core API for flat queries (no relations, no field selection).
 
 ```typescript
 // Automatic optimization - no code changes needed
@@ -69,41 +70,17 @@ const users = await repo.find({
 // 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>>;
-```
+| 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:
+**Problem:** New `schemaFactory` was created for every `BaseEntity` instance, causing memory overhead.
 
-```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:
+**Solution:** Lazy singleton pattern shared across all instances.
 
 ```typescript
 // After - shared singleton
@@ -120,22 +97,11 @@ protected static get schemaFactory(): ReturnType<typeof createSchemaFactory> {
 
 ### 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()`:
+**Files:** `packages/core/src/base/repositories/core/readable.ts`, `packages/core/src/base/repositories/core/persistable.ts`
 
-```typescript
-// Before - Anti-pattern
-return new Promise((resolve, reject) => {
-  this.connector.$count(this.entity.schema, where)
-    .then((count: number) => resolve({ count }))
-    .catch(reject);
-});
-```
+**Problem:** Every CRUD method wrapped existing promises in `new Promise()`.
 
-**Solution:** Direct async/await:
+**Solution:** Direct async/await.
 
 ```typescript
 // After - Clean and efficient
@@ -147,46 +113,18 @@ return { count };
 - 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
+### Core Package (`packages/core`)
 
-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) |
+| 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.
+All changes are internal optimizations. No API changes or migration required.