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

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
 }
 ```

package/wiki/get-started/building-a-crud-api.md

@@ -134,12 +134,10 @@ export type TTodo = TTableObject<TTodoSchema>;
 
 // 4. Create the Entity class, decorated with @model
 @model({ type: 'entity' })
-export class Todo extends BaseEntity<TTodoSchema> {
-  static readonly TABLE_NAME = 'Todo';
-
-  constructor() {
-    super({ name: Todo.TABLE_NAME, schema: todoTable });
-  }
+export class Todo extends BaseEntity<typeof Todo.schema> {
+  static override schema = todoTable;
+  static override relations = () => todoRelations.definitions;
+  static override TABLE_NAME = 'Todo';
 }
 ```
 
@@ -203,7 +201,6 @@ Create `src/datasources/postgres.datasource.ts`:
 
 ```typescript
 // src/datasources/postgres.datasource.ts
-import { Todo, todoRelations, todoTable } from '@/models/todo.model';
 import {
   BaseDataSource,
   datasource,
@@ -214,61 +211,61 @@ import { drizzle } from 'drizzle-orm/node-postgres';
 import { Pool } from 'pg';
 
 interface IDSConfigs {
-  connection: {
-    host?: string;
-    port?: number;
-    user?: string;
-    password?: string;
-    database?: string;
-  };
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  password: string;
 }
 
-@datasource()
+/**
+ * PostgresDataSource with auto-discovery support.
+ *
+ * How it works:
+ * 1. @repository decorator binds model to datasource
+ * 2. When configure() is called, getSchema() auto-discovers all bound models
+ * 3. Drizzle is initialized with the auto-discovered schema
+ */
+@datasource({ driver: 'node-postgres' })
 export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
-      driver: 'node-postgres',
+      // Driver is read from @datasource decorator - no need to pass here!
       config: {
-        connection: {
-          host: process.env.APP_ENV_POSTGRES_HOST,
-          port: +(process.env.APP_ENV_POSTGRES_PORT ?? 5432),
-          user: process.env.APP_ENV_POSTGRES_USERNAME,
-          password: process.env.APP_ENV_POSTGRES_PASSWORD,
-          database: process.env.APP_ENV_POSTGRES_DATABASE,
-        },
+        host: process.env.APP_ENV_POSTGRES_HOST ?? 'localhost',
+        port: +(process.env.APP_ENV_POSTGRES_PORT ?? 5432),
+        database: process.env.APP_ENV_POSTGRES_DATABASE ?? 'todo_db',
+        user: process.env.APP_ENV_POSTGRES_USERNAME ?? 'postgres',
+        password: process.env.APP_ENV_POSTGRES_PASSWORD ?? '',
       },
-      // Register all your models and their relations here
-      schema: Object.assign(
-        {},
-        { [Todo.TABLE_NAME]: todoTable },
-        todoRelations.relations,
-      ),
+      // NO schema property - auto-discovered from @repository bindings!
     });
   }
 
   override configure(): ValueOrPromise<void> {
-    this.connector = drizzle({
-      client: new Pool(this.settings.connection),
-      schema: this.schema,
-    });
-  }
-
-  override async connect(): Promise<TNodePostgresConnector | undefined> {
-    await (this.connector.client as Pool).connect();
-    return this.connector;
-  }
-
-  override async disconnect(): Promise<void> {
-    await (this.connector.client as Pool).end();
+    // getSchema() auto-discovers models from @repository bindings
+    const schema = this.getSchema();
+
+    // Log discovered schema for debugging
+    const schemaKeys = Object.keys(schema);
+    this.logger.debug(
+      '[configure] Auto-discovered schema | Schema + Relations (%s): %o',
+      schemaKeys.length,
+      schemaKeys,
+    );
+
+    const client = new Pool(this.settings);
+    this.connector = drizzle({ client, schema });
   }
 }
 ```
 
 **Key Points:**
-- Registers `todoTable` and `todoRelations` in the schema
+- Schema is auto-discovered from `@repository` decorators - no manual registration needed
+- Uses `getSchema()` for lazy schema resolution (resolves when all models are loaded)
 - Uses environment variables for connection config
-- Implements connection lifecycle methods
+- Implements connection lifecycle methods (`connect()`, `disconnect()`)
 
 > **Deep Dive:** See [DataSources Reference](../references/base/datasources.md) for advanced configuration and multiple database support.
 
@@ -280,26 +277,15 @@ Create `src/repositories/todo.repository.ts`:
 
 ```typescript
 // src/repositories/todo.repository.ts
-import { Todo, todoRelations, TTodoSchema } from '@/models/todo.model';
-import {
-  DefaultCRUDRepository,
-  IDataSource,
-  inject,
-  repository,
-} from '@venizia/ignis';
-
-@repository()
-export class TodoRepository extends DefaultCRUDRepository<TTodoSchema> {
-  constructor(
-    @inject({ key: 'datasources.PostgresDataSource' })
-    dataSource: IDataSource,
-  ) {
-    super({
-      dataSource,
-      entityClass: Todo,
-      relations: todoRelations.definitions,
-    });
-  }
+import { Todo } from '@/models/todo.model';
+import { PostgresDataSource } from '@/datasources/postgres.datasource';
+import { DefaultCRUDRepository, repository } from '@venizia/ignis';
+
+// Both 'model' and 'dataSource' are required for schema auto-discovery
+@repository({ model: Todo, dataSource: PostgresDataSource })
+export class TodoRepository extends DefaultCRUDRepository<typeof Todo.schema> {
+  // No constructor needed! DataSource and relations are auto-resolved
+  // from the @repository decorator and entity's static properties
 }
 ```
 
@@ -358,15 +344,15 @@ export class TodoController extends _Controller {
 **Auto-generated Endpoints:**
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/todos` | List all todos |
-| GET | `/todos/:id` | Get todo by ID |
-| GET | `/todos/find-one` | Find one todo by filter |
-| GET | `/todos/count` | Count todos |
-| POST | `/todos` | Create todo |
-| PATCH | `/todos/:id` | Update todo by ID |
-| PATCH | `/todos` | Update multiple todos |
-| DELETE | `/todos/:id` | Delete todo by ID |
-| DELETE | `/todos` | Delete multiple todos |
+| GET | `/todos` | List all todos (find) |
+| GET | `/todos/:id` | Get todo by ID (findById) |
+| GET | `/todos/find-one` | Find one todo by filter (findOne) |
+| GET | `/todos/count` | Count todos (count) |
+| POST | `/todos` | Create todo (create) |
+| PATCH | `/todos/:id` | Update todo by ID (updateById) |
+| PATCH | `/todos` | Update multiple todos by filter (updateBy) |
+| DELETE | `/todos/:id` | Delete todo by ID (deleteById) |
+| DELETE | `/todos` | Delete multiple todos by filter (deleteBy) |
 
 > **Deep Dive:** See [ControllerFactory Reference](../references/base/controllers.md#controllerfactory) for customization options.
 
@@ -639,8 +625,7 @@ Now that you've built the Todo API, try building a **User** feature on your own!
 
 **Challenge checklist:**
 - [ ] Create `src/models/user.model.ts`
-- [ ] Update `PostgresDataSource` to include User schema
-- [ ] Create `src/repositories/user.repository.ts`
+- [ ] Create `src/repositories/user.repository.ts` (this auto-registers User with PostgresDataSource)
 - [ ] Create `src/controllers/user.controller.ts`
 - [ ] Register repository and controller in `application.ts`
 - [ ] Run migration: `bun run migrate:dev`