@venizia/ignis-docs 0.0.8-3 → 0.1.0

package/content/references/base/datasources.md

@@ -0,0 +1,527 @@
+---
+title: DataSources Reference
+description: Technical reference for the engine-neutral DataSource contract and the PostgreSQL connector implementation
+difficulty: intermediate
+---
+
+# Deep Dive: DataSources
+
+Technical reference for DataSource classes - managing database and search engine connections in IGNIS.
+
+> [!IMPORTANT] Base vs. Connectors
+> IGNIS splits datasources into an **engine-neutral root** (`src/base/datasources/`) and **per-engine connectors** (`src/connectors/{postgres,typesense}/datasources/`). `AbstractDataSource` has no SQL, no Drizzle, and no `pool` - those live only in the PostgreSQL connector. See [Connectors](./connectors) for the full base-vs-connectors architecture, dual-door exports, and how to add a new engine. This page documents the neutral contract plus the PostgreSQL connector in depth; see [Search & Typesense](/guides/core-concepts/persistent/search-typesense) for the other engine.
+
+**Files:** `packages/core/src/base/datasources/*.ts` (neutral) and `packages/core/src/connectors/postgres/datasources/*.ts` (PostgreSQL)
+
+## Quick Reference
+
+| Class/Interface | Purpose | Key Members |
+|-----------------|---------|-------------|
+| **IDataSource** | Engine-neutral contract for all datasources | `name`, `settings`, `schema`, `getSchema()`, `getSettings()`, `configure()` |
+| **AbstractDataSource** | Engine-neutral base implementation with logging | Extends `BaseHelper`, `getCapabilities()` defaults to `{ transactions: false }`, `beginTransaction()` defaults to `throwNotSupported(...)` |
+| **AbstractPostgresDataSource** | PostgreSQL-aware abstraction | Adds `connector`, `client`, `driver`, abstract `getConnectionString()`/`beginTransaction()` |
+| **BasePostgresDataSource** | Concrete class to extend for PostgreSQL | Auto-discovery, real transaction support, constructor with config. Canonical name - `BaseDataSource` is a compatibility alias re-exporting the same class |
+| **ITransaction** | Engine-neutral transaction contract | `isActive`, `commit()`, `rollback()` (no connector field) |
+| **IDatabaseTransaction** | PostgreSQL transaction object | Extends `ITransaction`, adds `connector`, `isolationLevel` |
+| **IsolationLevels** | Isolation level constants (PostgreSQL) | `READ_COMMITTED`, `REPEATABLE_READ`, `SERIALIZABLE` |
+
+## `IDataSource` Interface
+
+Engine-neutral contract implemented by every datasource in the framework, regardless of engine.
+
+**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 schema type (shape depends on the connector - Drizzle tables for PostgreSQL, collection definitions for typesense) |
+| `ConfigurableOptions` | `{}` | Options passed to `configure()` |
+
+### Properties & Methods
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `name` | `string` | Datasource name |
+| `settings` | `Settings` | Configuration object |
+| `schema` | `Schema` | Combined schema (auto-discovered or manual) |
+| `getSchema()` | `Schema` | Returns combined schema |
+| `getSettings()` | `Settings` | Returns connection settings |
+| `configure(opts?)` | `ValueOrPromise<void>` | Initializes the underlying connection (from `IConfigurable`) |
+
+> [!NOTE]
+> `getCapabilities()` and `beginTransaction()` are not part of the `IDataSource` interface - they are declared on `AbstractDataSource` (below), which every connector extends.
+
+## `AbstractDataSource` (Engine-Neutral Root)
+
+**File:** `packages/core/src/base/datasources/abstract.ts`
+
+Top-level abstract class implemented by every engine. Extends `BaseHelper` for scoped logging. Contains **no SQL, no Drizzle, and no connection-pool members** - those are added by each connector.
+
+```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 |
+| `schema` | `Schema` | public | Combined schema |
+
+**Abstract methods** (must be implemented by connectors):
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `configure(opts?)` | `ValueOrPromise<void>` | Initialize the underlying connection |
+| `getConnectionString()` | `ValueOrPromise<string>` | Return the connection URL |
+
+**Concrete methods (defaults, overridable by connectors):**
+
+| Method | Return Type | Default Behavior |
+|--------|-------------|-------------------|
+| `getSettings()` | `Settings` | Returns `this.settings` |
+| `getSchema()` | `Schema` | Returns `this.schema` (throws if not initialized) |
+| `getCapabilities()` | `IDataSourceCapabilities` | Returns `{ transactions: false }` |
+| `beginTransaction(opts?)` | `Promise<ITransaction>` | Calls `throwNotSupported({ scope: this.constructor.name, feature: 'Transactions', logger: this.logger })` - throws HTTP 501 with `messageCode: 'core.not_supported'` |
+
+> [!NOTE] NotSupported convention
+> Every capability an engine doesn't implement - transactions, row-level locking - uses the same `throwNotSupported` utility (`packages/core/src/utilities/error.utility.ts`), producing a consistent `501 Not Implemented` with `messageCode: 'core.not_supported'`. This is how the typesense connector signals "not applicable to this engine" instead of silently no-op-ing.
+
+### `IDataSourceCapabilities`
+
+```typescript
+interface IDataSourceCapabilities {
+  transactions: boolean;
+}
+```
+
+Only `BasePostgresDataSource` overrides `getCapabilities()` to return `{ transactions: true }`. The typesense datasources inherit the neutral default.
+
+## PostgreSQL Connector: `AbstractPostgresDataSource` & `BasePostgresDataSource`
+
+**Files:** `packages/core/src/connectors/postgres/datasources/abstract.ts`, `packages/core/src/connectors/postgres/datasources/base.ts`
+
+### `AbstractPostgresDataSource`
+
+Extends `AbstractDataSource` with PostgreSQL/Drizzle-specific members.
+
+```typescript
+abstract class AbstractPostgresDataSource<
+  Settings extends object = {},
+  Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema,
+  ConfigurableOptions extends object = {},
+> extends AbstractDataSource<Settings, Schema, ConfigurableOptions>
+```
+
+**Additional properties:**
+
+| Property | Type | Visibility | Description |
+|----------|------|------------|-------------|
+| `connector` | `TRelationalConnector<Schema>` | public | Drizzle ORM instance (any Drizzle pg driver satisfies this - see the driver seam below) |
+| `driver` | `IRelationalDriver` | protected | The connection driver (`node-postgres` or `postgres-js`); built by `useDriver()` |
+| `client` | `Client` (`Pool` by default) | protected | The raw driver client `configure()` built - a `pg.Pool`, or a postgres-js `Sql`. Assigning it alone is enough: a driver is resolved from it on first use. Absent once `useDriver()` wired a driver instead |
+
+> [!NOTE] Driver seam
+> `AbstractRelationalDataSource`/`BaseRelationalDataSource` (exported as `AbstractPostgresDataSource`/`BasePostgresDataSource`) now take a fourth generic - `<Settings, Schema, ConfigurableOptions, Client = Pool>` - so a `postgres-js` datasource can declare `Client = Sql` and keep `getClient()` honest. The protected `useDriver({ driver, schema? })` assigns `this.driver` **and** builds `this.connector` in one step. `pg` and `postgres` are both optional peer dependencies; concrete drivers live at `@venizia/ignis/postgres/node-postgres` and `@venizia/ignis/postgres/postgres-js`, and Supabase support at `@venizia/ignis/postgres/supabase`. See [Postgres Drivers & Supabase](/guides/core-concepts/persistent/postgres-drivers).
+
+**Additional abstract method:**
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `beginTransaction(opts?)` | `Promise<IDatabaseTransaction<Schema>>` | Start a new PostgreSQL transaction |
+
+### `BasePostgresDataSource` (canonical name; `BaseDataSource` is a compatibility alias)
+
+Extends `AbstractPostgresDataSource` with a constructor, **schema auto-discovery**, and a real `beginTransaction()` implementation backed by the connection pool.
+
+```typescript
+abstract class BasePostgresDataSource<
+  Settings extends object = {},
+  Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema,
+  ConfigurableOptions extends object = {},
+> extends AbstractPostgresDataSource<Settings, Schema, ConfigurableOptions>
+```
+
+> [!TIP] Naming
+> `BasePostgresDataSource` is the canonical, engine-carrying name - prefer it in new code. `import { BaseDataSource } from '@venizia/ignis'` (or `@venizia/ignis/postgres`) still resolves to the exact same class via a re-export in `connectors/postgres/datasources/index.ts` (`export { BasePostgresDataSource as BaseDataSource } from './base-datasource'`), so existing code is unaffected.
+
+#### Key Features
+
+| Feature | Description |
+|---------|--------------|
+| **Schema Auto-Discovery** | Schema is automatically built from registered `@repository` decorators |
+| **Manual Override** | You can manually provide schema in constructor for full control |
+| **Built-in Transaction Support** | `beginTransaction()` acquires its connection from the resolved driver; overrides `getCapabilities()` to return `{ transactions: true }` |
+
+> [!TIP]
+> 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
+
+```typescript
+constructor(opts: {
+  name: string;           // DataSource name (usually class name)
+  config: Settings;       // Database connection settings
+  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 `name` and `config`
+    -   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**:
+    -   Call `this.getSchema()` to get the auto-discovered schema
+    -   Create a `Pool` instance and assign it to `this.client` (required for transaction support)
+    -   Create the Drizzle connector from that client and the schema
+
+### Example Implementations
+
+#### Pattern 1: Auto-Discovery (Recommended)
+
+Simplest approach - schema is auto-discovered from repositories:
+
+```typescript
+// src/datasources/postgres.datasource.ts
+import { BasePostgresDataSource, datasource } from '@venizia/ignis';
+import { applicationEnvironment, int, ValueOrPromise } from '@venizia/ignis-helpers';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { Pool } from 'pg';
+
+interface IDataSourceConfigs {
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  password: string;
+  ssl: boolean;
+}
+
+/**
+ * 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 BasePostgresDataSource<IDataSourceConfigs> {
+  private readonly protocol = 'postgresql';
+
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      config: {
+        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!
+    });
+  }
+
+  override configure(): ValueOrPromise<void> {
+    // getSchema() auto-discovers models from @repository bindings
+    const schema = this.getSchema();
+
+    const dataSourceSchema = Object.keys(schema);
+    this.logger.debug(
+      '[configure] Auto-discovered schema | Schema + Relations (%s): %o',
+      dataSourceSchema.length,
+      dataSourceSchema,
+    );
+
+    // The client slot is what beginTransaction() resolves its driver from
+    this.client = new Pool(this.settings);
+    this.connector = drizzle({ client: this.client, schema });
+  }
+
+  override getConnectionString(): ValueOrPromise<string> {
+    const { host, port, user, password, database } = this.settings;
+    return `${this.protocol}://${user}:${password}@${host}:${port}/${database}`;
+  }
+}
+```
+
+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 BasePostgresDataSource<IDataSourceConfigs> {
+  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
+    this.client = new Pool(this.settings);
+    this.connector = drizzle({ client: this.client, schema: this.getSchema() });
+  }
+
+  override getConnectionString(): ValueOrPromise<string> {
+    // ...
+  }
+}
+```
+
+> [!IMPORTANT]
+> Your `configure()` must leave the datasource with a way to reach the database: either assign the raw client to `this.client`, or wire a driver with `this.useDriver({ driver })`. `beginTransaction()` resolves a driver lazily from whichever you provided. With neither, it throws `No driver and no client`.
+
+### `@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` | - | Driver name - `DataSourceDrivers` defines four constants: `'node-postgres'` and `'postgres-js'` (relational), `'typesense'` and `'meilisearch'` (search); any other engine-driver string is also accepted |
+| `autoDiscovery` | `boolean` | `true` | Enable/disable schema auto-discovery |
+
+### Abstract Methods
+
+When extending `BasePostgresDataSource`, these methods must be implemented:
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `configure(opts?)` | `ValueOrPromise<void>` | Initialize the client and Drizzle connector. Must set `this.client` (or call `this.useDriver()`) and `this.connector`. |
+| `getConnectionString()` | `ValueOrPromise<string>` | Return the database connection string. |
+
+### Helper Methods
+
+| 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` |
+
+### Protected Methods
+
+| 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. |
+
+## Connector Types
+
+**File:** `packages/core/src/connectors/postgres/datasources/common/types.ts`
+
+| Type | Description |
+|------|-------------|
+| `TRelationalConnector<Schema>` | Canonical connector type - a Drizzle `PgDatabase` that **every** pg driver (`node-postgres`, `postgres-js`) satisfies. Use this in new code. |
+| `TNodePostgresConnector<Schema>` | **`@deprecated`** compat alias for `TRelationalConnector<Schema>` |
+| `TNodePostgresTransactionConnector<Schema>` | **`@deprecated`** compat alias - was the `PoolClient`-specific transaction connector; now aliases `TRelationalConnector<Schema>` |
+| `TAnyConnector<Schema>` | Alias of `TRelationalConnector<Schema>` |
+| `TAnyDataSourceSchema` | `Record<string, any>` - base type for all schema objects (defined in `src/base/datasources/common/types.ts`, shared across engines) |
+
+### `DataSourceDrivers`
+
+Static class for driver validation (defined in `src/base/datasources/common/types.ts`, shared across engines):
+
+```typescript
+DataSourceDrivers.NODE_POSTGRES  // 'node-postgres'
+DataSourceDrivers.POSTGRES_JS    // 'postgres-js'
+DataSourceDrivers.TYPESENSE      // 'typesense'
+DataSourceDrivers.MEILISEARCH    // 'meilisearch'
+DataSourceDrivers.isValid('node-postgres')  // true
+```
+
+## Transaction Support
+
+Only engines that declare `getCapabilities().transactions === true` implement real transactions - currently just the PostgreSQL connector. Calling `beginTransaction()` on the typesense connector throws `NotSupported` (HTTP 501).
+
+### How It Works
+
+`BasePostgresDataSource.beginTransaction()` does the following:
+
+1. Resolves a driver from `this.client` (or the one `useDriver()` wired) and acquires a connection from it
+2. Executes `BEGIN TRANSACTION ISOLATION LEVEL <level>` on the client
+3. Creates a separate Drizzle connector scoped to that client
+4. Returns an `IDatabaseTransaction` object with `commit()`, `rollback()`, and the scoped `connector`
+
+When `commit()` or `rollback()` succeeds, the client is released back to the pool.
+
+> [!WARNING] `commit()`/`rollback()` throw on failure
+> A failed `COMMIT` or `ROLLBACK` **throws** (a failed `COMMIT` no longer resolves as success), and the poisoned connection is **destroyed** rather than returned to the pool - under the `node-postgres` driver, which can discard a connection; `postgres-js` has no destroy semantics and pools it anyway. A failed `BEGIN` also destroys the acquired connection rather than leaking it. Because `rollback()` can throw and is normally called from a `catch`, nest it in its own `try...catch` so the rollback error does not replace the original cause. See [Transactions](/guides/core-concepts/persistent/transactions) and [Postgres Drivers & Supabase](/guides/core-concepts/persistent/postgres-drivers).
+
+### Neutral vs. PostgreSQL Transaction Types
+
+`src/base` declares the engine-neutral shape; the PostgreSQL connector narrows it with connection details.
+
+```typescript
+// packages/core/src/base/datasources/common/types.ts - engine-neutral
+interface ITransaction<_Schema = unknown> {
+  isActive: boolean;
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+}
+
+// packages/core/src/connectors/postgres/datasources/common/types.ts - PostgreSQL
+interface IDatabaseTransaction<Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema>
+  extends ITransaction<Schema> {
+  connector: TRelationalConnector<Schema>;
+  isolationLevel: TIsolationLevel;
+}
+```
+
+| Type | Description |
+|------|-------------|
+| `ITransaction<Schema>` | Engine-neutral contract - `isActive`, `commit()`, `rollback()`. No connector field. |
+| `IDatabaseTransaction<Schema>` | PostgreSQL transaction object - extends `ITransaction` with `connector` and `isolationLevel` |
+| `IDatabaseTransactionOptions` | Options for starting a PostgreSQL transaction (`isolationLevel`); extends the neutral `ITransactionOptions` |
+| `IDatabaseExtraOptions` | Extends the neutral `IExtraOptions`, narrowing `transaction?: IDatabaseTransaction` |
+| `TIsolationLevel` | Union type: `'READ COMMITTED'` \| `'REPEATABLE READ'` \| `'SERIALIZABLE'` |
+| `IsolationLevels` | Static class with isolation level constants and validation |
+
+> [!NOTE]
+> `AbstractRepository`, `PersistableRepository`, and every other engine-neutral repository type parameter is named `TOptions`/`IExtraOptions` in `src/base`. The PostgreSQL connector's `PostgresBaseRepository` narrows `ExtraOptions` to default to `IDatabaseExtraOptions`, so repository code written against a `PostgresBaseRepository` subclass sees `IDatabaseTransaction` (with `connector`/`isolationLevel`) rather than the bare neutral `ITransaction`.
+
+### Isolation Levels
+
+Use the `IsolationLevels` static class for type-safe isolation level constants:
+
+```typescript
+import { IsolationLevels } from '@venizia/ignis';
+
+// Available levels
+IsolationLevels.READ_COMMITTED   // Default - prevents dirty reads
+IsolationLevels.REPEATABLE_READ  // Consistent reads within transaction
+IsolationLevels.SERIALIZABLE     // Strictest isolation
+
+// Validation
+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
+// Start transaction from datasource or repository
+const tx = await dataSource.beginTransaction({
+  isolationLevel: IsolationLevels.SERIALIZABLE
+});
+
+try {
+  // Use tx.connector for operations
+  await tx.connector.insert(userTable).values({ name: 'Alice' });
+  await tx.connector.insert(profileTable).values({ userId: '...', bio: 'Hello' });
+
+  await tx.commit();
+} catch (error) {
+  // rollback() throws if ROLLBACK itself fails - nest it so it never replaces the original cause
+  try {
+    await tx.rollback();
+  } catch (rollbackError) {
+    logger.error('Rollback failed | %s', rollbackError);
+  }
+  throw error;
+}
+```
+
+> **Note:** For most use cases, prefer using `repository.beginTransaction()` which provides a higher-level API. See [Repositories Reference](./repositories/#transactions) for details.
+
+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.
+
+## See Also
+
+- **Related Concepts:**
+  - [Connectors](./connectors) - Base-vs-connectors architecture, dual-door exports, aliases
+  - [DataSources Guide](/guides/core-concepts/persistent/datasources) - Creating DataSources tutorial
+  - [Repositories](/guides/core-concepts/persistent/repositories) - Using DataSources for database access
+  - [Models](/guides/core-concepts/persistent/models) - Entity schemas loaded by DataSource
+  - [Transactions](/guides/core-concepts/persistent/transactions) - Multi-operation database transactions
+  - [Search & Typesense](/guides/core-concepts/persistent/search-typesense) - The typesense connector
+
+- **References:**
+  - [Repositories API](/references/base/repositories/) - Data access layer
+  - [Environment Variables](/references/configuration/environment-variables) - Configuration management
+
+- **External Resources:**
+  - [Drizzle ORM Documentation](https://orm.drizzle.team/) - ORM configuration
+  - [node-postgres Documentation](https://node-postgres.com/) - Connection pooling guide
+
+- **Best Practices:**
+  - [Performance Optimization](/best-practices/performance-optimization) - Connection pool tuning
+  - [Security Guidelines](/best-practices/security-guidelines) - Database credential management
+
+- **Tutorials:**
+  - [Complete Installation](/guides/tutorials/complete-installation) - Database setup
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api) - DataSource configuration

package/{wiki → content}/references/base/dependency-injection.md

@@ -6,16 +6,16 @@ difficulty: advanced
 
 # Deep Dive: Dependency Injection
 
-Technical reference for the DI system in Ignis - managing resource lifecycles and dependency resolution.
+Technical reference for the DI system in IGNIS - managing resource lifecycles and dependency resolution.
 
 **Files:**
-- `packages/inversion/src/container.ts` — Base `Container` and `Binding` classes
-- `packages/inversion/src/registry.ts` — Base `MetadataRegistry`
-- `packages/inversion/src/metadata/injectors.ts` — Base `@inject` and `@injectable` decorators
-- `packages/inversion/src/common/types.ts` — `BindingScopes`, `BindingValueTypes`, `BindingKeys`, `IProvider`
-- `packages/core/src/helpers/inversion/container.ts` — Extended `Container` with `ApplicationLogger`
-- `packages/core/src/helpers/inversion/registry.ts` — Extended `MetadataRegistry` (singleton, with model/repository/datasource mixins)
-- `packages/core/src/base/metadata/injectors.ts` — Core `@inject` and `@injectable` (wired to extended registry)
+- `packages/inversion/src/container.ts` - Base `Container` and `Binding` classes
+- `packages/inversion/src/registry.ts` - Base `MetadataRegistry`
+- `packages/inversion/src/metadata/injectors.ts` - Base `@inject` and `@injectable` decorators
+- `packages/inversion/src/common/types.ts` - `BindingScopes`, `BindingValueTypes`, `BindingKeys`, `IProvider`
+- `packages/core/src/helpers/inversion/container.ts` - Extended `Container` with `ApplicationLogger`
+- `packages/core/src/helpers/inversion/registry.ts` - Extended `MetadataRegistry` (singleton, with model/repository/datasource mixins)
+- `packages/core/src/base/metadata/injectors.ts` - Core `@inject` and `@injectable` (wired to extended registry)
 
 ## Quick Reference
 
@@ -25,7 +25,7 @@ Technical reference for the DI system in Ignis - managing resource lifecycles an
 | **Binding** | Single registered dependency configuration | `toClass()`, `toValue()`, `toProvider()`, `setScope()`, `setTags()`, `getValue()`, `clearCache()` |
 | **@inject** | Decorator marking injection points | Applied to constructor parameters and class properties |
 | **@injectable** | Decorator marking a class as injectable | Stores scope and tag metadata |
-| **MetadataRegistry** | Stores decorator metadata | Singleton — base via `metadataRegistry` export, core via `MetadataRegistry.getInstance()` |
+| **MetadataRegistry** | Stores decorator metadata | Singleton - base via `metadataRegistry` export, core via `MetadataRegistry.getInstance()` |
 | **BindingKeys** | Utility for building namespaced keys | `BindingKeys.build({ namespace, key })` |
 | **Boot System** | Automatic artifact discovery and binding | Integrates with Container via tags and bindings |
 
@@ -58,7 +58,7 @@ const container = new Container({ scope: 'MyApp' }); // scope is optional, defau
 | :--- | :--- | :--- |
 | **`bind`** | `bind<T>({ key: string \| symbol }): Binding<T>` | Creates and registers a new `Binding` for the given key. Returns the `Binding` for fluent configuration. |
 | **`get`** | `get<T>({ key, isOptional? }): T` | Retrieves a resolved dependency. `key` can be a `string`, `symbol`, or `{ namespace, key }` object. Throws if not found and `isOptional` is `false` (default). Returns `undefined` if `isOptional` is `true` and not found. |
-| **`gets`** | `gets<T>({ bindings }): T[]` | Resolves multiple dependencies at once. Each entry in `bindings` accepts `{ key, isOptional? }`. All lookups are treated as optional (returns `undefined` for missing). |
+| **`gets`** | `gets<T extends unknown[]>({ bindings }): { [K in keyof T]: T[K] \| undefined }` | Resolves multiple dependencies at once. Each entry in `bindings` accepts `{ key, isOptional? }`. Returns a tuple-preserving array where missing bindings resolve to `undefined`. |
 | **`getBinding`** | `getBinding<T>({ key }): Binding<T> \| undefined` | Returns the raw `Binding` object without resolving it. `key` accepts `string`, `symbol`, or `{ namespace, key }`. |
 | **`set`** | `set<T>({ binding: Binding<T> }): void` | Directly sets a pre-built `Binding` into the container. |
 | **`isBound`** | `isBound({ key: string \| symbol }): boolean` | Checks if a binding exists for the given key. |
@@ -74,8 +74,8 @@ const container = new Container({ scope: 'MyApp' }); // scope is optional, defau
 
 When `container.instantiate(MyClass)` is called:
 
-1. **Constructor injection** — Reads `@inject` metadata from the class, sorts by parameter index, resolves each dependency from the container, and passes them as constructor arguments.
-2. **Property injection** — After the instance is created, reads property metadata, resolves each dependency, and assigns them directly to the instance properties.
+1. **Constructor injection** - Reads `@inject` metadata from the class by parameter index (the `Reflect`-stored array is already index-keyed, so there is no sort step), resolves each dependency from the container, and passes them as constructor arguments. If any index in range has no `@inject` metadata, `instantiate()` throws immediately rather than passing `undefined`.
+2. **Property injection** - After the instance is created, reads property metadata, resolves each dependency, and assigns them directly to the instance properties.
 
 ```typescript
 // Both constructor and property injection in action
@@ -90,6 +90,18 @@ class UserController {
 }
 ```
 
+> [!IMPORTANT]
+> **Every constructor parameter of a container-instantiated class must carry `@inject`.** Mixing decorated and undecorated parameters is forbidden - `@inject` stores its metadata at the parameter's index, so an undecorated parameter leaves a hole in that array, and there is no channel through which the container could supply it anyway (it would resolve to `undefined`). `instantiate()` refuses the shape by class name and parameter index instead of silently dereferencing the hole:
+>
+> ```
+> [NoteController] Constructor parameter 0 has no @inject | Every parameter of a container-instantiated
+> class must be decorated - the container cannot supply an undecorated one
+> ```
+>
+> The check lives in `instantiate()`, not in the `@inject` decorator itself: parameter decorators run right-to-left, so when `@inject` on parameter 1 runs, parameter 0 has not been visited yet and nothing at that point can know whether it will end up decorated.
+>
+> This does not apply to `@repository`-decorated classes whose constructor appears undecorated at index 0 - the `@repository` decorator programmatically writes that inject metadata (`registry.setInjectMetadata({ target, index: 0, ... })`) even though no literal `@inject` appears in source. See [Repositories](./repositories/).
+
 ## `Binding` Class
 
 A `Binding` represents a single registered dependency in the container. It provides a fluent API to configure *how* a dependency should be created and managed.
@@ -114,7 +126,7 @@ When a binding key contains a dot (e.g., `services.MyService`), the namespace po
 | **`toValue`** | `toValue(value: T): this` | Binds to a constant value (e.g., a config object, string, number). |
 | **`toProvider`** | `toProvider(value: ((container) => T) \| TClass<IProvider<T>>): this` | Binds to a factory function or a class implementing `IProvider<T>`. |
 | **`setScope`** | `setScope(scope: TBindingScope): this` | Sets the lifecycle scope (`'singleton'` or `'transient'`). |
-| **`setTags`** | `setTags(...tags: string[]): this` | Adds one or more tags to the binding. Tags are additive — calling this multiple times adds more tags. |
+| **`setTags`** | `setTags(...tags: string[]): this` | Adds one or more tags to the binding. Tags are additive - calling this multiple times adds more tags. |
 | **`getValue`** | `getValue(container?: Container): T` | Resolves the binding's value. For `CLASS` and `PROVIDER` types, a `container` argument is required. Respects singleton caching. |
 | **`clearCache`** | `clearCache(): void` | Clears the cached singleton instance (if any). Next `getValue()` call will re-create it. |
 | **`hasTag`** | `hasTag(tag: string): boolean` | Checks if the binding has a specific tag. |
@@ -192,7 +204,7 @@ This is also used internally by `container.get()` and `container.getBinding()` w
 
 ## `@inject` Decorator
 
-The `@inject` decorator marks where dependencies should be injected — either on constructor parameters or class properties.
+The `@inject` decorator marks where dependencies should be injected - either on constructor parameters or class properties.
 
 **File:** `packages/inversion/src/metadata/injectors.ts` (base) & `packages/core/src/base/metadata/injectors.ts` (core wrapper)
 
@@ -204,7 +216,7 @@ The `@inject` decorator marks where dependencies should be injected — either o
 
 | Parameter | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `key` | `string \| symbol` | — | The binding key to resolve from the container. |
+| `key` | `string \| symbol` | - | The binding key to resolve from the container. |
 | `isOptional` | `boolean` | `false` | If `true`, returns `undefined` instead of throwing when the binding is not found. |
 
 ### Constructor Parameter Injection
@@ -262,8 +274,8 @@ Marks a class as injectable and attaches optional metadata.
 
 | Parameter | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `scope` | `'singleton' \| 'transient'` | — | Optional scope hint for the binding. |
-| `tags` | `Record<string, any>` | — | Optional metadata tags. |
+| `scope` | `'singleton' \| 'transient'` | - | Optional scope hint for the binding. |
+| `tags` | `Record<string, any>` | - | Optional metadata tags. |
 
 ### Example
 
@@ -272,7 +284,7 @@ Marks a class as injectable and attaches optional metadata.
 class UserService extends BaseService {
   constructor(
     @inject({ key: 'repositories.UserRepository' })
-    private userRepo: UserRepository,
+    private userRepository: UserRepository,
   ) {
     super({ scope: UserService.name });
   }
@@ -390,16 +402,16 @@ This pattern allows the `Bootstrapper` to automatically discover and execute all
 Once artifacts are discovered and loaded, they're bound using consistent namespace patterns:
 
 ```typescript
-// Controllers — auto-tagged with 'controllers'
+// Controllers - auto-tagged with 'controllers'
 this.bind({ key: 'controllers.UserController' }).toClass(UserController);
 
-// Services — auto-tagged with 'services'
+// Services - auto-tagged with 'services'
 this.bind({ key: 'services.UserService' }).toClass(UserService);
 
-// Repositories — auto-tagged with 'repositories'
+// Repositories - auto-tagged with 'repositories'
 this.bind({ key: 'repositories.UserRepository' }).toClass(UserRepository);
 
-// Datasources — auto-tagged with 'datasources'
+// Datasources - auto-tagged with 'datasources'
 this.bind({ key: 'datasources.PostgresDataSource' }).toClass(PostgresDataSource);
 ```