@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/references/base/datasources.md

@@ -1,28 +1,33 @@
 ---
 title: DataSources Reference
-description: Technical reference for DataSource classes and database connections
+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 connections in Ignis.
+Technical reference for DataSource classes - managing database and search engine connections in IGNIS.
 
-**Files:** `packages/core/src/base/datasources/*.ts`
+> [!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** | Contract for all datasources | `name`, `settings`, `connector`, `getSchema()`, `configure()`, `beginTransaction()` |
-| **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** | 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
 
-Contract for all datasource classes in the framework.
+Engine-neutral contract implemented by every datasource in the framework, regardless of engine.
 
 **File:** `packages/core/src/base/datasources/common/types.ts`
 
@@ -39,7 +44,7 @@ interface IDataSource<
 | Type Parameter | Default | Description |
 |----------------|---------|-------------|
 | `Settings` | `{}` | Connection configuration type (host, port, etc.) |
-| `Schema` | `TAnyDataSourceSchema` | Combined Drizzle schema type (tables + relations) |
+| `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
@@ -48,22 +53,19 @@ interface IDataSource<
 |--------|------|-------------|
 | `name` | `string` | Datasource name |
 | `settings` | `Settings` | Configuration object |
-| `connector` | `TNodePostgresConnector<Schema>` | Drizzle ORM connector instance |
-| `schema` | `Schema` | Combined Drizzle schema (auto-discovered or manual) |
-| `getSchema()` | `Schema` | Returns combined Drizzle schema |
+| `schema` | `Schema` | Combined schema (auto-discovered or manual) |
+| `getSchema()` | `Schema` | Returns combined 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 |
+| `configure(opts?)` | `ValueOrPromise<void>` | Initializes the underlying connection (from `IConfigurable`) |
 
-## `AbstractDataSource` & `BaseDataSource`
+> [!NOTE]
+> `getCapabilities()` and `beginTransaction()` are not part of the `IDataSource` interface - they are declared on `AbstractDataSource` (below), which every connector extends.
 
-**File:** `packages/core/src/base/datasources/base.ts`
+## `AbstractDataSource` (Engine-Neutral Root)
 
-### `AbstractDataSource`
+**File:** `packages/core/src/base/datasources/abstract.ts`
 
-Top-level abstract class that implements `IDataSource`. Extends `BaseHelper` for scoped logging. Declares the core properties and abstract methods.
+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<
@@ -79,45 +81,92 @@ abstract class AbstractDataSource<
 |----------|------|------------|-------------|
 | `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 |
+| `schema` | `Schema` | public | Combined schema |
 
-**Abstract methods** (must be implemented by subclasses):
+**Abstract methods** (must be implemented by connectors):
 
 | 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 |
+| `configure(opts?)` | `ValueOrPromise<void>` | Initialize the underlying connection |
+| `getConnectionString()` | `ValueOrPromise<string>` | Return the connection URL |
 
-**Concrete methods:**
+**Concrete methods (defaults, overridable by connectors):**
 
-| Method | Return Type | Description |
-|--------|-------------|-------------|
+| Method | Return Type | Default Behavior |
+|--------|-------------|-------------------|
 | `getSettings()` | `Settings` | Returns `this.settings` |
-| `getConnector()` | `TNodePostgresConnector<Schema>` | Returns `this.connector` |
 | `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`
 
-### `BaseDataSource`
+### `AbstractPostgresDataSource`
 
-Extends `AbstractDataSource` with a constructor, **schema auto-discovery**, and a default `beginTransaction()` implementation.
+Extends `AbstractDataSource` with PostgreSQL/Drizzle-specific members.
 
 ```typescript
-abstract class BaseDataSource<
+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 lazily by `wireDriverFromMetadata()` from the class named in `@datasource({ driver })`, or explicitly 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: `wireDriverFromMetadata()` instantiates the `@datasource({ driver })` class over 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. `@datasource({ driver })` names the driver **class** (`NodePostgresDriver` or `PostgresJsDriver`), never a string - a driver-name string cannot carry `pg`/`postgres` into the app's bundle, only a real class reference can. `configure()` only needs to assign `this.client`; the protected `wireDriverFromMetadata()` (called internally by `getConnector()`/`resolveDriver()`) instantiates the named class over it and builds `this.connector`, lazily and idempotently. The protected `useDriver({ driver, schema? })` stays available for a custom or third-party driver - it assigns `this.driver` **and** builds `this.connector` in one step, bypassing `@datasource({ driver })` entirely. `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()` implemented using the `pool` property |
+| **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.
@@ -153,9 +202,8 @@ When you use `@repository({ model: YourModel, dataSource: YourDataSource })`, th
     -   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.pool` (required for transaction support)
-    -   Create the Drizzle connector with the pool and schema
+    -   Create a `Pool` instance and assign it to `this.client` - that is the whole method
+    -   `getConnector()`/`beginTransaction()` lazily instantiate the class named in `@datasource({ driver })` over `this.client` and build the Drizzle connector from it - your `configure()` never touches `this.connector` directly
 
 ### Example Implementations
 
@@ -165,12 +213,12 @@ Simplest approach - schema is auto-discovered from repositories:
 
 ```typescript
 // src/datasources/postgres.datasource.ts
-import { BaseDataSource, datasource, ValueOrPromise } from '@venizia/ignis';
-import { applicationEnvironment, int } from '@venizia/ignis-helpers';
-import { drizzle } from 'drizzle-orm/node-postgres';
+import { BasePostgresDataSource, datasource } from '@venizia/ignis';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
+import { applicationEnvironment, int, ValueOrPromise } from '@venizia/ignis-helpers';
 import { Pool } from 'pg';
 
-interface IDSConfigs {
+interface IDataSourceConfigs {
   host: string;
   port: number;
   database: string;
@@ -184,11 +232,11 @@ interface IDSConfigs {
  *
  * 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
+ * 2. getSchema() auto-discovers all bound models when the driver/connector are wired
+ * 3. Naming NodePostgresDriver in @datasource is what wires the driver and Drizzle connector
  */
-@datasource({ driver: 'node-postgres' })
-export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
+@datasource({ driver: NodePostgresDriver })
+export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
   private readonly protocol = 'postgresql';
 
   constructor() {
@@ -207,19 +255,15 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   }
 
   override configure(): ValueOrPromise<void> {
-    // getSchema() auto-discovers models from @repository bindings
-    const schema = this.getSchema();
-
-    const dsSchema = Object.keys(schema);
+    const schema = Object.keys(this.getSchema());
     this.logger.debug(
       '[configure] Auto-discovered schema | Schema + Relations (%s): %o',
-      dsSchema.length,
-      dsSchema,
+      schema.length,
+      schema,
     );
 
-    // Store pool reference for transaction support
-    this.pool = new Pool(this.settings);
-    this.connector = drizzle({ client: this.pool, schema });
+    // That is all - the base class wires the driver + connector from @datasource({ driver }).
+    this.client = new Pool(this.settings);
   }
 
   override getConnectionString(): ValueOrPromise<string> {
@@ -246,13 +290,14 @@ The `PostgresDataSource.schema` will automatically include User and Configuratio
 When you need explicit control over schema (e.g., subset of models, custom ordering):
 
 ```typescript
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 import {
   User, userTable, userRelations,
   Configuration, configurationTable, configurationRelations,
 } from '@/models/entities';
 
-@datasource({ driver: 'node-postgres' })
-export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
+@datasource({ driver: NodePostgresDriver })
+export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
@@ -274,9 +319,8 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   }
 
   override configure(): ValueOrPromise<void> {
-    // When schema is manually provided, getSchema() returns it directly
-    this.pool = new Pool(this.settings);
-    this.connector = drizzle({ client: this.pool, schema: this.getSchema() });
+    // Manually-provided schema is used as-is by the connector the base class builds from this.client
+    this.client = new Pool(this.settings);
   }
 
   override getConnectionString(): ValueOrPromise<string> {
@@ -286,7 +330,7 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
 ```
 
 > [!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.
+> Your `configure()` must leave the datasource with a way to reach the database: either assign the raw client to `this.client` (paired with naming the driver class in `@datasource({ driver })`), or wire a driver directly with `this.useDriver({ driver })` for a custom or third-party driver. `getConnector()`/`beginTransaction()` resolve the driver lazily from whichever you provided. With neither, it throws `No driver and no client`.
 
 ### `@datasource` Decorator
 
@@ -294,23 +338,23 @@ The `@datasource` decorator registers datasource metadata:
 
 ```typescript
 @datasource({
-  driver: 'node-postgres',       // Required - database driver
+  driver: NodePostgresDriver,    // Required - driver CLASS (or a search engine's driver-name string)
   autoDiscovery?: true           // Optional - defaults to true
 })
 ```
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `driver` | `TDataSourceDriver` | - | Database driver name (currently only `'node-postgres'`) |
+| `driver` | `TDataSourceDriverClass` | - | The driver **class** - `NodePostgresDriver` or `PostgresJsDriver` (imported from `@venizia/ignis/postgres/node-postgres` / `.../postgres-js`), never a driver-name string. A class reference is the only thing that carries `pg`/`postgres` into the app's bundle. **Omit it for a search datasource**: `extends TypesenseDataSource` already names the engine, and is what carries `typesense` into the bundle |
 | `autoDiscovery` | `boolean` | `true` | Enable/disable schema auto-discovery |
 
 ### Abstract Methods
 
-When extending `BaseDataSource`, these methods must be implemented:
+When extending `BasePostgresDataSource`, these methods must be implemented:
 
 | Method | Return Type | Description |
 |--------|-------------|-------------|
-| `configure(opts?)` | `ValueOrPromise<void>` | Initialize pool and Drizzle connector. Must set `this.pool` and `this.connector`. |
+| `configure(opts?)` | `ValueOrPromise<void>` | Initialize the client. Must set `this.client` (the base class wires the driver and Drizzle connector from `@datasource({ driver })`), or call `this.useDriver()` directly for a custom driver. |
 | `getConnectionString()` | `ValueOrPromise<string>` | Return the database connection string. |
 
 ### Helper Methods
@@ -330,61 +374,81 @@ When extending `BaseDataSource`, these methods must be implemented:
 
 ## Connector Types
 
-**File:** `packages/core/src/base/datasources/common/types.ts`
+**File:** `packages/core/src/connectors/postgres/datasources/common/types.ts`
 
 | 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 |
+| `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:
+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
 ```
 
+> [!NOTE]
+> `NODE_POSTGRES`/`POSTGRES_JS` remain valid `TDataSourceDriver` string values, but `@datasource({ driver })` on a **relational** datasource no longer accepts them - it takes the `NodePostgresDriver`/`PostgresJsDriver` class instead (see [Postgres Drivers & Supabase](/guides/core-concepts/persistent/postgres-drivers)). Search connectors (`TYPESENSE`, `MEILISEARCH`) still take the driver-name string form.
+
 ## Transaction Support
 
-DataSources provide built-in transaction management through the `beginTransaction()` method. This allows you to perform atomic operations across multiple repositories.
+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
 
-`BaseDataSource.beginTransaction()` does the following:
+`BasePostgresDataSource.beginTransaction()` does the following:
 
-1. Acquires a `PoolClient` from `this.pool`
+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 `ITransaction` object with `commit()`, `rollback()`, and the scoped `connector`
+4. Returns an `IDatabaseTransaction` object with `commit()`, `rollback()`, and the scoped `connector`
 
-When `commit()` or `rollback()` is called, the client is released back to the pool.
+When `commit()` or `rollback()` succeeds, the client is released back to the pool.
 
-### Transaction Types
+> [!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).
 
-| Type | Description |
-|------|-------------|
-| `ITransaction<Schema>` | Transaction object with `commit()`, `rollback()`, and `connector` |
-| `ITransactionOptions` | Options for starting a transaction (e.g., `isolationLevel`) |
-| `TIsolationLevel` | Union type: `'READ COMMITTED'` \| `'REPEATABLE READ'` \| `'SERIALIZABLE'` |
-| `IsolationLevels` | Static class with isolation level constants and validation |
+### Neutral vs. PostgreSQL Transaction Types
 
-### ITransaction Interface
+`src/base` declares the engine-neutral shape; the PostgreSQL connector narrows it with connection details.
 
 ```typescript
-interface ITransaction<Schema> {
-  connector: TNodePostgresTransactionConnector<Schema>;
-  isActive: boolean;       // read-only getter, false after commit/rollback
-  isolationLevel: TIsolationLevel;
-
+// 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:
@@ -420,7 +484,12 @@ try {
 
   await tx.commit();
 } catch (error) {
-  await tx.rollback();
+  // 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;
 }
 ```
@@ -432,10 +501,12 @@ This architecture ensures that datasources are configured consistently and that
 ## 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

package/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);
 ```