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

package/wiki/references/base/datasources.md

@@ -8,9 +8,9 @@ Technical reference for DataSource classes - managing database connections in Ig
 
 | Class/Interface | Purpose | Key Members |
 |-----------------|---------|-------------|
-| **IDataSource** | Contract for all datasources | `name`, `settings`, `connector`, `schema`, `configure()` |
+| **IDataSource** | Contract for all datasources | `name`, `settings`, `connector`, `getSchema()`, `configure()` |
 | **AbstractDataSource** | Base implementation with logging | Extends `BaseHelper` |
-| **BaseDataSource** | Concrete class to extend | Constructor accepts `name`, `driver`, `config`, `schema` |
+| **BaseDataSource** | Concrete class to extend | Auto-discovery, driver from decorator |
 
 ## `IDataSource` Interface
 
@@ -25,7 +25,7 @@ Contract for all datasource classes in the framework.
 | `name` | `string` | Datasource name |
 | `settings` | `object` | Configuration object |
 | `connector` | `TDatabaseConnector` | Database connector instance (e.g., Drizzle) |
-| `schema` | `object` | Combined Drizzle schema (tables + relations) |
+| `getSchema()` | Method | Returns combined Drizzle schema (auto-discovered or manual) |
 | `configure()` | Method | Initializes the `connector` |
 | `getConnectionString()` | Method | Returns connection string |
 
@@ -39,29 +39,60 @@ This is the top-level abstract class that implements the `IDataSource` interface
 
 ### `BaseDataSource`
 
-This class extends `AbstractDataSource` and provides a constructor that standardizes how datasources are created. When you create your own datasource, you extend `BaseDataSource`.
+This class extends `AbstractDataSource` and provides a constructor with **auto-discovery** support. When you create your own datasource, you extend `BaseDataSource`.
 
-### Constructor and Configuration Flow
+#### Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **Driver Auto-Read** | Driver is read from `@datasource` decorator - no need to pass in constructor |
+| **Schema Auto-Discovery** | Schema is automatically built from registered `@repository` decorators |
+| **Manual Override** | You can still manually provide schema in constructor for full control |
+
+### Constructor Options
+
+```typescript
+constructor(opts: {
+  name: string;           // DataSource name (usually class name)
+  config: Settings;       // Database connection settings
+  driver?: TDataSourceDriver;  // Optional - read from @datasource if not provided
+  schema?: Schema;        // Optional - auto-discovered if not provided
+})
+```
+
+### Schema Auto-Discovery
+
+When you use `@repository({ model: YourModel, dataSource: YourDataSource })`, the framework automatically:
+
+1. Registers the model-datasource binding in the MetadataRegistry
+2. When `getSchema()` is called, discovers all models bound to this datasource
+3. Builds the combined schema (tables + relations) automatically
+
+**This means you no longer need to manually merge tables and relations in the DataSource constructor!**
+
+### Configuration Flow
 
 1.  **Your DataSource's `constructor` is called**:
-    -   You call `super()` with the `name`, `driver`, `config` (connection settings), and the crucial `schema` object.
-    -   The `schema` object **must** contain all your Drizzle tables and `relations` definitions.
+    -   You call `super()` with `name` and `config`
+    -   Driver is automatically read from `@datasource` decorator
+    -   Schema is auto-discovered from `@repository` bindings (or manually provided)
 
 2.  **`Application.registerDataSources()` is called during startup**:
-    -   The application gets your `DataSource` instance from the DI container.
-    -   It calls the `configure()` method on your instance.
+    -   The application gets your `DataSource` instance from the DI container
+    -   It calls the `configure()` method on your instance
 
 3.  **Your `configure()` method runs**:
-    -   This is where you instantiate the Drizzle ORM.
-    -   You pass the `this.settings` (your config) and `this.schema` to Drizzle, creating the `this.connector`.
+    -   This is where you instantiate the Drizzle ORM
+    -   Use `this.getSchema()` to get the auto-discovered schema and pass to Drizzle
+
+### Example Implementations
 
-### Example Implementation
+#### Pattern 1: Auto-Discovery (Recommended)
+
+Simplest approach - schema is auto-discovered from repositories:
 
 ```typescript
 // src/datasources/postgres.datasource.ts
-import {
-  // ... import your models and relations
-} from '@/models/entities';
 import {
   BaseDataSource,
   datasource,
@@ -71,35 +102,166 @@ import {
 import { drizzle } from 'drizzle-orm/node-postgres';
 import { Pool } from 'pg';
 
-// Decorator to mark this class as a datasource for DI
-@datasource()
-export class PostgresDataSource extends BaseDataSource<
-  TNodePostgresConnector, // Type of the connector
-  IDSConfigs              // Type of the config object
-> {
+interface IDSConfigs {
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  password: string;
+}
+
+/**
+ * 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',
-      config: { /* ... connection details from environment ... */ },
-      schema: {
-        // Register all tables and relations here
-        usersTable,
-        configurationTable,
-        ...configurationRelations,
+      // Driver is read from @datasource decorator - no need to pass here!
+      config: {
+        host: process.env.APP_ENV_POSTGRES_HOST ?? 'localhost',
+        port: +(process.env.APP_ENV_POSTGRES_PORT ?? 5432),
+        database: process.env.APP_ENV_POSTGRES_DATABASE ?? 'mydb',
+        user: process.env.APP_ENV_POSTGRES_USERNAME ?? 'postgres',
+        password: process.env.APP_ENV_POSTGRES_PASSWORD ?? '',
       },
+      // NO schema property - auto-discovered from @repository bindings!
     });
   }
 
-  // This method is called by the application at startup
   override configure(): ValueOrPromise<void> {
-    this.connector = drizzle({
-      client: new Pool(this.settings),
-      schema: this.schema,
+    // 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 });
+  }
+}
+```
+
+With this pattern, when you define repositories:
+
+```typescript
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {}
+
+@repository({ model: Configuration, dataSource: PostgresDataSource })
+export class ConfigurationRepository extends DefaultCRUDRepository<typeof Configuration.schema> {}
+```
+
+The `PostgresDataSource.schema` will automatically include User and Configuration tables and their relations.
+
+#### Pattern 2: Manual Schema (Full Control)
+
+When you need explicit control over schema (e.g., subset of models, custom ordering):
+
+```typescript
+import {
+  User, userTable, userRelations,
+  Configuration, configurationTable, configurationRelations,
+} from '@/models/entities';
+
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      config: {
+        host: process.env.APP_ENV_POSTGRES_HOST ?? 'localhost',
+        port: +(process.env.APP_ENV_POSTGRES_PORT ?? 5432),
+        database: process.env.APP_ENV_POSTGRES_DATABASE ?? 'mydb',
+        user: process.env.APP_ENV_POSTGRES_USERNAME ?? 'postgres',
+        password: process.env.APP_ENV_POSTGRES_PASSWORD ?? '',
+      },
+      // Manually provide schema using spread syntax
+      schema: {
+        [User.TABLE_NAME]: userTable,
+        [Configuration.TABLE_NAME]: configurationTable,
+        ...userRelations.relations,
+        ...configurationRelations.relations,
+      },
     });
   }
-  // ...
+
+  override configure(): ValueOrPromise<void> {
+    // When schema is manually provided, getSchema() returns it directly
+    const client = new Pool(this.settings);
+    this.connector = drizzle({ client, schema: this.getSchema() });
+  }
 }
 ```
 
+### @datasource Decorator
+
+The `@datasource` decorator registers datasource metadata:
+
+```typescript
+@datasource({
+  driver: 'node-postgres',       // Required - database driver
+  autoDiscovery?: true           // Optional - defaults to true
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `driver` | `TDataSourceDriver` | - | Database driver name |
+| `autoDiscovery` | `boolean` | `true` | Enable/disable schema auto-discovery |
+
+### Abstract Methods
+
+These methods must be implemented in your datasource class:
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `configure(opts?)` | `ValueOrPromise<void>` | Initialize the Drizzle ORM connector. Called during application startup. |
+| `getConnectionString()` | `ValueOrPromise<string>` | Return the database connection string. |
+
+### Optional Override Methods
+
+These methods can be optionally overridden for connection lifecycle management:
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `connect()` | `Promise<Connector \| undefined>` | Establish database connection. Useful for connection pooling. |
+| `disconnect()` | `Promise<void>` | Close database connection gracefully. |
+
+```typescript
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+  // ... constructor and configure() ...
+
+  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();
+  }
+}
+```
+
+### Helper Methods
+
+| Method | Description |
+|--------|-------------|
+| `getSchema()` | Returns the schema (auto-discovers if not manually provided) |
+| `getSettings()` | Returns connection settings |
+| `getConnector()` | Returns the Drizzle connector |
+| `hasDiscoverableModels()` | Returns `true` if there are models registered for this datasource |
+
 This architecture ensures that datasources are configured consistently and that the fully-initialized Drizzle connector, aware of all schemas and relations, is available to repositories for querying.

package/wiki/references/base/dependency-injection.md

@@ -4,9 +4,9 @@ Technical reference for the DI system in Ignis - managing resource lifecycles an
 
 **Files:**
 - `packages/inversion/src/container.ts` (base Container and Binding classes)
-- `packages/helpers/src/helpers/inversion/container.ts` (extended Container with ApplicationLogger)
+- `packages/core/src/helpers/inversion/container.ts` (extended Container with ApplicationLogger)
 - `packages/core/src/base/metadata/injectors.ts` (@inject, @injectable decorators)
-- `packages/helpers/src/helpers/inversion/registry.ts` (MetadataRegistry)
+- `packages/core/src/helpers/inversion/registry.ts` (MetadataRegistry)
 
 ## Quick Reference
 
@@ -21,7 +21,7 @@ Technical reference for the DI system in Ignis - managing resource lifecycles an
 
 Heart of the DI system - registry managing all application resources.
 
-**File:** `packages/inversion/src/container.ts`
+**File:** `packages/inversion/src/container.ts` (Base) & `packages/core/src/helpers/inversion/container.ts` (Extended)
 
 ### Key Methods
 
@@ -74,11 +74,11 @@ This entire process is managed by the framework when your application starts up,
 
 The `MetadataRegistry` is a crucial part of the DI and routing systems. It's a singleton class responsible for storing and retrieving all the metadata attached by decorators like `@inject`, `@controller`, `@get`, etc.
 
--   **File:** `packages/helpers/src/helpers/inversion/registry.ts`
+-   **File:** `packages/core/src/helpers/inversion/registry.ts`
 
 ### Role in DI
 
 -   When you use a decorator (e.g., `@inject`), it calls a method on the `MetadataRegistry.getInstance()` to store information about the injection (like the binding key and target property/parameter).
 -   When the `Container` instantiates a class, it queries the `MetadataRegistry` to find out which dependencies need to be injected and where.
 
-You typically won't interact with the `MetadataRegistry` directly, but it's the underlying mechanism that makes the decorator-based DI and routing systems work seamlessly.
+You typically won't interact with the `MetadataRegistry` directly, but it's the underlying mechanism that makes the decorator-based DI and routing systems work seamlessly.