@venizia/ignis-docs 0.0.7-2 → 0.0.8-0

package/wiki/references/base/datasources.md

@@ -15,10 +15,10 @@ Technical reference for DataSource classes - managing database connections in Ig
 | Class/Interface | Purpose | Key Members |
 |-----------------|---------|-------------|
 | **IDataSource** | Contract for all datasources | `name`, `settings`, `connector`, `getSchema()`, `configure()`, `beginTransaction()` |
-| **AbstractDataSource** | Base implementation with logging | Extends `BaseHelper` |
-| **BaseDataSource** | Concrete class to extend | Auto-discovery, driver from decorator, transaction support |
-| **ITransaction** | Transaction object | `connector`, `isActive`, `commit()`, `rollback()` |
-| **IsolationLevels** | Isolation level constants | `READ_UNCOMMITTED`, `READ_COMMITTED`, `REPEATABLE_READ`, `SERIALIZABLE` |
+| **AbstractDataSource** | Base implementation with logging | Extends `BaseHelper`, declares abstract methods |
+| **BaseDataSource** | Concrete class to extend | Auto-discovery, transaction support, constructor with config |
+| **ITransaction** | Transaction object | `connector`, `isActive`, `isolationLevel`, `commit()`, `rollback()` |
+| **IsolationLevels** | Isolation level constants | `READ_COMMITTED`, `REPEATABLE_READ`, `SERIALIZABLE` |
 
 ## `IDataSource` Interface
 
@@ -26,20 +26,36 @@ Contract for all datasource classes in the framework.
 
 **File:** `packages/core/src/base/datasources/common/types.ts`
 
+### Type Parameters
+
+```typescript
+interface IDataSource<
+  Settings extends object = {},
+  Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema,
+  ConfigurableOptions extends object = {},
+> extends IConfigurable<ConfigurableOptions>
+```
+
+| Type Parameter | Default | Description |
+|----------------|---------|-------------|
+| `Settings` | `{}` | Connection configuration type (host, port, etc.) |
+| `Schema` | `TAnyDataSourceSchema` | Combined Drizzle schema type (tables + relations) |
+| `ConfigurableOptions` | `{}` | Options passed to `configure()` |
+
 ### Properties & Methods
 
 | Member | Type | Description |
 |--------|------|-------------|
 | `name` | `string` | Datasource name |
-| `settings` | `object` | Configuration object |
-| `connector` | `TNodePostgresConnector` | Database connector instance (Drizzle) |
+| `settings` | `Settings` | Configuration object |
+| `connector` | `TNodePostgresConnector<Schema>` | Drizzle ORM connector instance |
 | `schema` | `Schema` | Combined Drizzle schema (auto-discovered or manual) |
-| `getSchema()` | Method | Returns combined Drizzle schema |
-| `getSettings()` | Method | Returns connection settings |
-| `getConnector()` | Method | Returns the Drizzle connector |
-| `configure()` | Method | Initializes the `connector` |
-| `getConnectionString()` | Method | Returns connection string |
-| `beginTransaction(opts?)` | Method | Starts a new database transaction |
+| `getSchema()` | `Schema` | Returns combined Drizzle schema |
+| `getSettings()` | `Settings` | Returns connection settings |
+| `getConnector()` | `TNodePostgresConnector<Schema>` | Returns the Drizzle connector |
+| `getConnectionString()` | `ValueOrPromise<string>` | Returns connection string |
+| `configure(opts?)` | `ValueOrPromise<void>` | Initializes pool and connector |
+| `beginTransaction(opts?)` | `Promise<ITransaction<Schema>>` | Starts a new database transaction |
 
 ## `AbstractDataSource` & `BaseDataSource`
 
@@ -47,22 +63,64 @@ Contract for all datasource classes in the framework.
 
 ### `AbstractDataSource`
 
-This is the top-level abstract class that implements the `IDataSource` interface. It initializes the `BaseHelper` for logging and sets up the basic properties.
+Top-level abstract class that implements `IDataSource`. Extends `BaseHelper` for scoped logging. Declares the core properties and abstract methods.
+
+```typescript
+abstract class AbstractDataSource<
+  Settings extends object = {},
+  Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema,
+  ConfigurableOptions extends object = {},
+> extends BaseHelper implements IDataSource<Settings, Schema, ConfigurableOptions>
+```
+
+**Properties:**
+
+| Property | Type | Visibility | Description |
+|----------|------|------------|-------------|
+| `name` | `string` | public | Datasource identifier |
+| `settings` | `Settings` | public | Connection configuration |
+| `connector` | `TNodePostgresConnector<Schema>` | public | Drizzle ORM instance |
+| `schema` | `Schema` | public | Combined schema (tables + relations) |
+| `pool` | `Pool` | protected | node-postgres connection pool |
+
+**Abstract methods** (must be implemented by subclasses):
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `configure(opts?)` | `ValueOrPromise<void>` | Initialize pool and Drizzle connector |
+| `getConnectionString()` | `ValueOrPromise<string>` | Return the database connection URL |
+| `beginTransaction(opts?)` | `Promise<ITransaction<Schema>>` | Start a new transaction |
+
+**Concrete methods:**
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `getSettings()` | `Settings` | Returns `this.settings` |
+| `getConnector()` | `TNodePostgresConnector<Schema>` | Returns `this.connector` |
+| `getSchema()` | `Schema` | Returns `this.schema` (throws if not initialized) |
 
 ### `BaseDataSource`
 
-This class extends `AbstractDataSource` and provides a constructor with **auto-discovery** support. When you create your own datasource, you extend `BaseDataSource`.
+Extends `AbstractDataSource` with a constructor, **schema auto-discovery**, and a default `beginTransaction()` implementation.
+
+```typescript
+abstract class BaseDataSource<
+  Settings extends object = {},
+  Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema,
+  ConfigurableOptions extends object = {},
+> extends AbstractDataSource<Settings, Schema, ConfigurableOptions>
+```
 
 #### 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 |
+| **Manual Override** | You can manually provide schema in constructor for full control |
+| **Built-in Transaction Support** | `beginTransaction()` implemented using the `pool` property |
 
 > [!TIP]
-> Set `metadata.autoDiscovery` to `false` in the `@datasource` decorator to disable automatic schema discovery. This is useful when you want to manually provide the schema.
+> Set `autoDiscovery` to `false` in the `@datasource` decorator to disable automatic schema discovery. This is useful when you want to manually provide the schema.
 
 ### Constructor Options
 
@@ -70,7 +128,6 @@ This class extends `AbstractDataSource` and provides a constructor with **auto-d
 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
 })
 ```
@@ -89,16 +146,16 @@ When you use `@repository({ model: YourModel, dataSource: YourDataSource })`, th
 
 1.  **Your DataSource's `constructor` is called**:
     -   You call `super()` with `name` and `config`
-    -   Driver is automatically read from `@datasource` decorator
-    -   Schema is auto-discovered from `@repository` bindings (or manually provided)
+    -   Schema is auto-discovered from `@repository` bindings (or manually provided via `schema`)
 
 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
 
 3.  **Your `configure()` method runs**:
-    -   This is where you instantiate the Drizzle ORM
-    -   Use `this.getSchema()` to get the auto-discovered schema and pass to Drizzle
+    -   Call `this.getSchema()` to get the auto-discovered schema
+    -   Create a `Pool` instance and assign it to `this.pool` (required for transaction support)
+    -   Create the Drizzle connector with the pool and schema
 
 ### Example Implementations
 
@@ -108,12 +165,8 @@ Simplest approach - schema is auto-discovered from repositories:
 
 ```typescript
 // src/datasources/postgres.datasource.ts
-import {
-  BaseDataSource,
-  datasource,
-  TNodePostgresConnector,
-  ValueOrPromise,
-} from '@venizia/ignis';
+import { BaseDataSource, datasource, ValueOrPromise } from '@venizia/ignis';
+import { applicationEnvironment, int } from '@venizia/ignis-helpers';
 import { drizzle } from 'drizzle-orm/node-postgres';
 import { Pool } from 'pg';
 
@@ -123,6 +176,7 @@ interface IDSConfigs {
   database: string;
   user: string;
   password: string;
+  ssl: boolean;
 }
 
 /**
@@ -134,17 +188,19 @@ interface IDSConfigs {
  * 3. Drizzle is initialized with the auto-discovered schema
  */
 @datasource({ driver: 'node-postgres' })
-export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
+  private readonly protocol = 'postgresql';
+
   constructor() {
     super({
       name: PostgresDataSource.name,
-      // 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 ?? '',
+        host: applicationEnvironment.get<string>('APP_ENV_POSTGRES_HOST'),
+        port: int(applicationEnvironment.get<string>('APP_ENV_POSTGRES_PORT')),
+        database: applicationEnvironment.get<string>('APP_ENV_POSTGRES_DATABASE'),
+        user: applicationEnvironment.get<string>('APP_ENV_POSTGRES_USERNAME'),
+        password: applicationEnvironment.get<string>('APP_ENV_POSTGRES_PASSWORD'),
+        ssl: false,
       },
       // NO schema property - auto-discovered from @repository bindings!
     });
@@ -154,16 +210,21 @@ export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, I
     // getSchema() auto-discovers models from @repository bindings
     const schema = this.getSchema();
 
-    // Log discovered schema for debugging
-    const schemaKeys = Object.keys(schema);
+    const dsSchema = Object.keys(schema);
     this.logger.debug(
       '[configure] Auto-discovered schema | Schema + Relations (%s): %o',
-      schemaKeys.length,
-      schemaKeys,
+      dsSchema.length,
+      dsSchema,
     );
 
-    const client = new Pool(this.settings);
-    this.connector = drizzle({ client, schema });
+    // Store pool reference for transaction support
+    this.pool = new Pool(this.settings);
+    this.connector = drizzle({ client: this.pool, schema });
+  }
+
+  override getConnectionString(): ValueOrPromise<string> {
+    const { host, port, user, password, database } = this.settings;
+    return `${this.protocol}://${user}:${password}@${host}:${port}/${database}`;
   }
 }
 ```
@@ -191,7 +252,7 @@ import {
 } from '@/models/entities';
 
 @datasource({ driver: 'node-postgres' })
-export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
@@ -214,13 +275,20 @@ export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, I
 
   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() });
+    this.pool = new Pool(this.settings);
+    this.connector = drizzle({ client: this.pool, schema: this.getSchema() });
+  }
+
+  override getConnectionString(): ValueOrPromise<string> {
+    // ...
   }
 }
 ```
 
-### @datasource Decorator
+> [!IMPORTANT]
+> You must assign `this.pool` in your `configure()` method. The built-in `beginTransaction()` uses `this.pool` to acquire a `PoolClient` for transaction isolation. If `this.pool` is not set, `beginTransaction()` will throw an error.
+
+### `@datasource` Decorator
 
 The `@datasource` decorator registers datasource metadata:
 
@@ -233,65 +301,75 @@ The `@datasource` decorator registers datasource metadata:
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `driver` | `TDataSourceDriver` | - | Database driver name |
+| `driver` | `TDataSourceDriver` | - | Database driver name (currently only `'node-postgres'`) |
 | `autoDiscovery` | `boolean` | `true` | Enable/disable schema auto-discovery |
 
 ### Abstract Methods
 
-These methods must be implemented in your datasource class:
+When extending `BaseDataSource`, these methods must be implemented:
 
 | Method | Return Type | Description |
 |--------|-------------|-------------|
-| `configure(opts?)` | `ValueOrPromise<void>` | Initialize the Drizzle ORM connector. Called during application startup. |
+| `configure(opts?)` | `ValueOrPromise<void>` | Initialize pool and Drizzle connector. Must set `this.pool` and `this.connector`. |
 | `getConnectionString()` | `ValueOrPromise<string>` | Return the database connection string. |
 
-### Optional Override Methods
+### Helper Methods
 
-These methods can be optionally overridden for connection lifecycle management:
+| Method | Description |
+|--------|-------------|
+| `getSchema()` | Returns the schema (auto-discovers via `discoverSchema()` if not manually provided) |
+| `getSettings()` | Returns connection settings |
+| `getConnector()` | Returns the Drizzle connector |
+| `hasDiscoverableModels()` | Returns `true` if there are models registered for this datasource via `@repository` |
 
-| Method | Return Type | Description |
-|--------|-------------|-------------|
-| `connect()` | `Promise<Connector \| undefined>` | Establish database connection. Useful for connection pooling. |
-| `disconnect()` | `Promise<void>` | Close database connection gracefully. |
+### Protected Methods
 
-```typescript
-@datasource({ driver: 'node-postgres' })
-export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
-  // ... constructor and configure() ...
+| Method | Description |
+|--------|-------------|
+| `discoverSchema()` | Queries the `MetadataRegistry` for all `@repository` bindings targeting this datasource, then calls `registry.buildSchema()` to merge tables and relations into a single schema object. |
 
-  override async connect(): Promise<TNodePostgresConnector | undefined> {
-    await (this.connector.client as Pool).connect();
-    return this.connector;
-  }
+## Connector Types
 
-  override async disconnect(): Promise<void> {
-    await (this.connector.client as Pool).end();
-  }
-}
-```
+**File:** `packages/core/src/base/datasources/common/types.ts`
 
-### Helper Methods
+| Type | Description |
+|------|-------------|
+| `TNodePostgresConnector<Schema>` | Drizzle connector using `NodePgClient` (Pool or PoolClient) |
+| `TNodePostgresTransactionConnector<Schema>` | Drizzle connector using `PoolClient` specifically (for transaction isolation) |
+| `TAnyConnector<Schema>` | Union of both connector types |
+| `TAnyDataSourceSchema` | `Record<string, any>` — base type for all schema objects |
 
-| 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 |
+### `DataSourceDrivers`
+
+Static class for driver validation:
+
+```typescript
+DataSourceDrivers.NODE_POSTGRES  // 'node-postgres'
+DataSourceDrivers.isValid('node-postgres')  // true
+```
 
 ## Transaction Support
 
 DataSources provide built-in transaction management through the `beginTransaction()` method. This allows you to perform atomic operations across multiple repositories.
 
-### Transaction Types
+### How It Works
 
-**File:** `packages/core/src/base/datasources/common/types.ts`
+`BaseDataSource.beginTransaction()` does the following:
+
+1. Acquires a `PoolClient` from `this.pool`
+2. Executes `BEGIN TRANSACTION ISOLATION LEVEL <level>` on the client
+3. Creates a separate Drizzle connector scoped to that client
+4. Returns an `ITransaction` object with `commit()`, `rollback()`, and the scoped `connector`
+
+When `commit()` or `rollback()` is called, the client is released back to the pool.
+
+### Transaction Types
 
 | Type | Description |
 |------|-------------|
 | `ITransaction<Schema>` | Transaction object with `commit()`, `rollback()`, and `connector` |
 | `ITransactionOptions` | Options for starting a transaction (e.g., `isolationLevel`) |
-| `TIsolationLevel` | Union type: `'READ UNCOMMITTED'` \| `'READ COMMITTED'` \| `'REPEATABLE READ'` \| `'SERIALIZABLE'` |
+| `TIsolationLevel` | Union type: `'READ COMMITTED'` \| `'REPEATABLE READ'` \| `'SERIALIZABLE'` |
 | `IsolationLevels` | Static class with isolation level constants and validation |
 
 ### ITransaction Interface
@@ -299,7 +377,7 @@ DataSources provide built-in transaction management through the `beginTransactio
 ```typescript
 interface ITransaction<Schema> {
   connector: TNodePostgresTransactionConnector<Schema>;
-  isActive: boolean;
+  isActive: boolean;       // read-only getter, false after commit/rollback
   isolationLevel: TIsolationLevel;
 
   commit(): Promise<void>;
@@ -315,7 +393,6 @@ Use the `IsolationLevels` static class for type-safe isolation level constants:
 import { IsolationLevels } from '@venizia/ignis';
 
 // Available levels
-IsolationLevels.READ_UNCOMMITTED // Allows dirty reads (least strict)
 IsolationLevels.READ_COMMITTED   // Default - prevents dirty reads
 IsolationLevels.REPEATABLE_READ  // Consistent reads within transaction
 IsolationLevels.SERIALIZABLE     // Strictest isolation
@@ -325,6 +402,9 @@ IsolationLevels.isValid('READ COMMITTED'); // true
 IsolationLevels.isValid('INVALID');        // false
 ```
 
+> [!NOTE]
+> The default isolation level is `READ COMMITTED` when no `isolationLevel` option is provided.
+
 ### Usage Example
 
 ```typescript