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

package/wiki/changelogs/v0.0.1-7-initial-architecture.md

@@ -0,0 +1,137 @@
+# v0.0.1-7 - Initial Architecture (Pre-Refactor)
+
+**Release Date**: 2025-12-16
+**Status**: Superseded by v0.0.1-8
+
+## Overview
+
+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.
+
+## 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
+
+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
+
+## 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
+
+---
+
+*This architecture was superseded by the Loopback 4-style refactor in v0.0.1-8*

package/wiki/changelogs/v0.0.1-8-model-repo-datasource-refactor.md

@@ -0,0 +1,278 @@
+# v0.0.1-8 - Model-Repository-DataSource Architecture Refactor
+
+**Release Date**: 2025-12-16
+**Status**: Current
+
+## Overview
+
+Major refactor following Loopback 4's architecture pattern where:
+- **Model** is self-contained with schema and relations
+- **Repository** connects Model to DataSource (defines the binding)
+- **DataSource** auto-discovers schemas from registered repositories
+
+This eliminates manual schema registration and simplifies the development workflow significantly.
+
+## Breaking Changes
+
+1. **Model static properties now require `override` keyword**
+   - `static override schema = pgTable(...)`
+   - `static override relations = () => ({...})`
+
+2. **Repository constructor is now optional**
+   - Old: Required `entityClass`, `relations`, `dataSource` parameters
+   - New: Auto-resolved from `@repository` decorator metadata
+
+3. **DataSource schema is now optional**
+   - Old: Required manual `schema` property with all models
+   - New: Auto-discovered from `@repository` bindings
+
+## New Features
+
+### Self-Contained Models
+
+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],
+    },
+  });
+}
+```
+
+### Repository Auto-Resolution
+
+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 } } });
+  }
+}
+```
+
+### DataSource Auto-Discovery
+
+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 });
+  }
+}
+```
+
+## 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
+
+### Step 1: Update Models
+
+**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 = () => ({...});
+}
+```
+
+### Step 2: Update Repositories
+
+**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!
+}
+```
+
+### Step 3: Update DataSources
+
+**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!
+    });
+  }
+}
+```
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Application                               │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │  preConfigure()                                            │  │
+│  │    this.dataSource(PostgresDataSource)                     │  │
+│  │    this.repository(UserRepository)        ──┐              │  │
+│  │    this.repository(ConfigurationRepository) │ Registers    │  │
+│  │                                             │ bindings     │  │
+│  └─────────────────────────────────────────────┼─────────────┘  │
+│                                                │                 │
+│  ┌─────────────────────────────────────────────▼─────────────┐  │
+│  │  MetadataRegistry                                          │  │
+│  │    modelRegistry: Map<tableName, {schema, relations}>      │  │
+│  │    repositoryBindings: Map<repoClass, {model, datasource}> │  │
+│  │    datasourceModels: Map<datasource, Set<modelNames>>      │  │
+│  └─────────────────────────────────────────────┬─────────────┘  │
+│                                                │                 │
+│  ┌─────────────────────────────────────────────▼─────────────┐  │
+│  │  DataSource.configure()                                    │  │
+│  │    schema = this.getSchema()  ◄── Auto-discovers from      │  │
+│  │                                   MetadataRegistry          │  │
+│  │    this.connector = drizzle({ schema })                    │  │
+│  └───────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Benefits
+
+1. **Simplified Model Definition**: Single class with static properties
+2. **No Manual Schema Registration**: DataSource auto-discovers models
+3. **Clear Repository Role**: Explicitly binds model to datasource
+4. **Better Type Safety**: Types flow from `static schema` through the system
+5. **Reduced Boilerplate**: No constructor needed for basic repositories
+6. **Follows Loopback 4 Pattern**: Familiar architecture for developers
+
+## Technical Details
+
+### IRelationDefinition Interface
+
+```typescript
+interface IRelationDefinition<TTarget = any> {
+  type: 'one' | 'many';
+  target: () => TClass<TTarget>;    // Lazy to avoid circular imports
+  fields?: AnyColumn[];
+  references?: () => AnyColumn[];   // Lazy to avoid circular imports
+  relationName?: string;
+}
+```
+
+### Repository Auto-Resolution Flow
+
+1. `@repository` decorator registers binding in `MetadataRegistry`
+2. When repository is instantiated, constructor checks for explicit opts
+3. If not provided, lazy getters resolve from `MetadataRegistry`:
+   - `entity` → resolved from `modelClass` in binding
+   - `relations` → built from model's `static relations()`
+   - `dataSource` → resolved from container using binding key
+
+### DataSource Auto-Discovery Flow
+
+1. `@repository` decorators register model-datasource bindings
+2. When `dataSource.configure()` is called, `getSchema()` is invoked
+3. `buildAutoDiscoveredSchema()` queries `MetadataRegistry` for all models bound to this datasource
+4. Schema is assembled from model schemas and relations
+
+---
+
+*This refactor was inspired by Loopback 4's architecture pattern*

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);
       },
     });
   }

package/wiki/get-started/best-practices/common-pitfalls.md

@@ -79,7 +79,7 @@ export class Application extends BaseApplication {
         const company = await this.companyRepository.findOrCreate(companyName);
         const user = await this.userRepository.create({ name, email, companyId: company.id });
         
-        return c.json(user);
+        return c.json(user, HTTP.ResultCodes.RS_2.Ok);
     }
     ```
 -   **Good:**
@@ -89,7 +89,7 @@ export class Application extends BaseApplication {
         const userData = c.req.valid('json');
         // Delegate to the service
         const newUser = await this.userService.createUser(userData);
-        return c.json(newUser);
+        return c.json(newUser, HTTP.ResultCodes.RS_2.Ok);
     }
     
     // In UserService

package/wiki/get-started/best-practices/data-modeling.md

@@ -14,22 +14,18 @@ import {
   model,
   TTableObject,
 } from '@venizia/ignis';
-import { configurationTable } from './schema'; // Your Drizzle schema
+import { configurationTable, configurationRelations } from './schema'; // Your Drizzle schema
 
 // Define types for TypeScript inference
 export type TConfigurationSchema = typeof configurationTable;
 export type TConfiguration = TTableObject<TConfigurationSchema>;
 
 @model({ type: 'entity', skipMigrate: false })
-export class Configuration extends BaseEntity<TConfigurationSchema> {
-  static readonly TABLE_NAME = Configuration.name;
-
-  constructor() {
-    super({
-      name: Configuration.TABLE_NAME,
-      schema: configurationTable,
-    });
-  }
+export class Configuration extends BaseEntity<typeof Configuration.schema> {
+  // Use static properties (recommended pattern)
+  static override schema = configurationTable;
+  static override relations = () => configurationRelations.definitions;
+  static override TABLE_NAME = 'Configuration';
 }
 ```
 
@@ -110,17 +106,15 @@ export const configurationRelations = createRelations({
 });
 ```
 
-This configuration is then passed directly to your Repository:
+This configuration is automatically used when you define your Repository with the `@repository` decorator:
 
 ```typescript
-@repository({})
-export class ConfigurationRepository extends DefaultCRUDRepository<TConfigurationSchema> {
-  constructor(@inject({ key: 'datasources.PostgresDataSource' }) dataSource: IDataSource) {
-    super({
-      dataSource,
-      entityClass: Configuration,
-      relations: configurationRelations.definitions, // <-- Injected here
-    });
-  }
+import { PostgresDataSource } from '@/datasources';
+
+// Both 'model' and 'dataSource' are required for schema auto-discovery
+@repository({ model: Configuration, dataSource: PostgresDataSource })
+export class ConfigurationRepository extends DefaultCRUDRepository<typeof Configuration.schema> {
+  // No constructor needed! DataSource and relations are auto-resolved
+  // from the @repository decorator and entity's static properties
 }
 ```