@venizia/ignis-docs 0.0.1-9 → 0.0.2

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

@@ -1,278 +0,0 @@
-# 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*