@xfcfam/xf-sql 0.1.0

package/dist/src/repository/base/DatabaseRepository.js

@@ -0,0 +1,216 @@
+import { Repository, NotInitializedException } from '@xfarch/xf';
+import { Kysely } from 'kysely';
+/**
+ * Base Generalization for the Access Layer when the underlying
+ * external system is a SQL database.
+ *
+ * Encapsulates the [Kysely](https://kysely.dev) query builder behind
+ * a single XF-canonical class. The implementer's concrete Logical
+ * extends this (or a dialect-specific subclass such as
+ * `PostgresDatabaseRepository`) and exposes domain-meaningful methods
+ * that compose queries against `this.db`, a `Kysely<Schema>` bound
+ * to the implementer's typed schema.
+ *
+ * Concrete dialect support lives in adapter packages — install one of
+ * `@xfarch/xf-sql-postgres`, `@xfarch/xf-sql-mysql`, etc., or supply
+ * any Kysely-compatible `Dialect` directly.
+ *
+ * ──────────────────────────────────────────────────────────────────
+ *  IMPORTANT — Required configuration for subclasses
+ * ──────────────────────────────────────────────────────────────────
+ * The underlying Kysely instance is held in a static private WeakMap
+ * and created inside {@link init}. If a subclass overrides `init()` /
+ * `terminate()`, it MUST chain through `super`:
+ *
+ *   async init()      { await super.init();      // own setup }
+ *   async terminate() { // own teardown;         await super.terminate() }
+ *
+ * Forgetting `super.init()` leaves `this.db` uninitialised and every
+ * query will throw {@link NotInitializedException}.
+ *
+ * ──────────────────────────────────────────────────────────────────
+ *  Overridable observation hooks
+ * ──────────────────────────────────────────────────────────────────
+ *  - {@link onConnected}     ← after `init()` creates the Kysely instance
+ *  - {@link onDisconnected}  ← after `terminate()` destroys it
+ *  - {@link onQuery}         ← for every query Kysely executes
+ *  - {@link onError}         ← for every {@link exec}-wrapped operation that rejects
+ *
+ *  Transaction hooks ({@link onTransactionStart} / Commit / Rollback)
+ *  live on {@link TransactionalDatabaseRepository}, the subclass that
+ *  exposes explicit transaction control.
+ *
+ * ──────────────────────────────────────────────────────────────────
+ *  Error translation
+ * ──────────────────────────────────────────────────────────────────
+ * Dialect-specific errors (driver Error objects) are not translated
+ * by this class — it does not know about Postgres SQLSTATEs, MySQL
+ * error numbers, etc. Use a dialect adapter subclass (such as
+ * `PostgresDatabaseRepository`) or override {@link translateError}
+ * yourself to map errors to the typed Exceptions exported from this
+ * package (`UniqueViolationException`, etc.).
+ *
+ * @typeParam Schema  Implementer-defined TypeScript interface mapping
+ *                    table names to their column shapes. See the
+ *                    Kysely docs for the conventions on
+ *                    `Generated`, `ColumnType`, etc.
+ *
+ * @example
+ * ```ts
+ * import { DatabaseRepository } from '@xfarch/xf-sql'
+ * import { PostgresDialect } from 'kysely'
+ * import { Pool } from 'pg'
+ *
+ * interface Schema {
+ *   users: { id: number; name: string; email: string }
+ * }
+ *
+ * export class UsersDb extends DatabaseRepository<Schema> {
+ *   constructor() {
+ *     super({
+ *       dialect: new PostgresDialect({
+ *         pool: new Pool({ connectionString: process.env.DATABASE_URL }),
+ *       }),
+ *     })
+ *   }
+ *   async init()      { await super.init() }
+ *   async terminate() { await super.terminate() }
+ *
+ *   getUser(id: number) {
+ *     return this.db
+ *       .selectFrom('users')
+ *       .where('id', '=', id)
+ *       .selectAll()
+ *       .executeTakeFirstOrThrow()
+ *   }
+ * }
+ * ```
+ */
+export class DatabaseRepository extends Repository {
+    static state = new WeakMap();
+    /** Options provided at construction time. */
+    options;
+    constructor(options) {
+        super(null);
+        this.options = options;
+    }
+    /**
+     * Typed Kysely instance bound to `Schema`. Use it to compose queries:
+     * `this.db.selectFrom('users')…`, `this.db.insertInto('users')…`.
+     * Throws if {@link init} has not been called.
+     */
+    get db() {
+        const s = DatabaseRepository.state.get(this);
+        if (s === undefined) {
+            throw new NotInitializedException('DatabaseRepository: init() was not called (or super.init() was skipped)');
+        }
+        return s.db;
+    }
+    /**
+     * Subclasses that override this method MUST call `await super.init()`
+     * **first**; otherwise {@link db} will throw on use.
+     */
+    async init() {
+        const db = new Kysely({
+            dialect: this.options.dialect,
+            log: (event) => {
+                if (event.level === 'query') {
+                    this.onQuery(event.query.sql, event.query.parameters);
+                }
+                else if (event.level === 'error') {
+                    // Kysely-emitted query errors are also routed through onError
+                    // for symmetry with exec() failures.
+                    this.onError('query', event.error);
+                }
+            },
+        });
+        DatabaseRepository.state.set(this, { db });
+        await this.onConnected();
+    }
+    /**
+     * Subclasses that override this method MUST call `await super.terminate()`
+     * **last** to release the connection pool held by the Kysely instance.
+     */
+    async terminate() {
+        const s = DatabaseRepository.state.get(this);
+        if (s !== undefined) {
+            await s.db.destroy();
+            DatabaseRepository.state.delete(this);
+            await this.onDisconnected();
+        }
+    }
+    /**
+     * Hook for dialect-specific error translation. Default
+     * implementation is identity (returns the input unchanged).
+     *
+     * Dialect adapter subclasses (such as `PostgresDatabaseRepository`)
+     * override this to map driver errors to the typed Exceptions
+     * exported from this package.
+     *
+     * Called automatically by {@link exec}; not called for direct
+     * `this.db.…` usage, where the implementer is responsible for
+     * wrapping queries in `this.exec(...)`.
+     */
+    translateError(err) {
+        return err;
+    }
+    /**
+     * Execute an operation against the database, translating any
+     * dialect-specific errors to xf-sql Exception types via
+     * {@link translateError}.
+     *
+     * Use this whenever you need automatic error translation. For raw
+     * Kysely access without translation, use {@link db} directly.
+     *
+     * @example
+     * ```ts
+     * async createUser(input: UserInput) {
+     *   return this.exec(() =>
+     *     this.db.insertInto('users').values(input).returningAll().executeTakeFirstOrThrow()
+     *   )
+     * }
+     * ```
+     */
+    async exec(op) {
+        try {
+            return await op();
+        }
+        catch (err) {
+            this.onError('exec', err);
+            throw this.translateError(err);
+        }
+    }
+    // ─── Overridable observation hooks ────────────────────────
+    /**
+     * Invoked after `init()` has created the Kysely instance. Default
+     * no-op. Override for connection-open telemetry, schema migrations,
+     * connection warmup, etc.
+     */
+    async onConnected() { }
+    /**
+     * Invoked after `terminate()` has destroyed the Kysely instance.
+     * Default no-op. Override for connection-close telemetry.
+     */
+    async onDisconnected() { }
+    /**
+     * Invoked for every query Kysely executes (both standalone and
+     * inside transactions). Receives the compiled SQL and the bound
+     * parameters. Default no-op.
+     *
+     * Use for audit logging or query profiling. The hook runs
+     * synchronously inside Kysely's pipeline — keep it cheap and avoid
+     * blocking work.
+     */
+    onQuery(_sql, _params) { }
+    /**
+     * Invoked when an `exec()`-wrapped operation rejects, or when
+     * Kysely emits a query-level error. The `operation` label
+     * distinguishes the source (`'exec'`, `'query'`, or the value
+     * supplied by a subclass). Default no-op.
+     *
+     * The hook fires before {@link translateError}; the (possibly
+     * untranslated) error is still re-thrown to the caller.
+     */
+    onError(_operation, _error) { }
+}
+//# sourceMappingURL=DatabaseRepository.js.map

package/dist/src/repository/base/DatabaseRepository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DatabaseRepository.js","sourceRoot":"","sources":["../../../../src/repository/base/DatabaseRepository.ts"],"names":[],"mappings":"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"}

package/dist/src/repository/base/TransactionalDatabaseRepository.d.ts

@@ -0,0 +1,86 @@
+import { type Transaction } from 'kysely';
+import { DatabaseRepository } from './DatabaseRepository.js';
+/**
+ * Generalization for SQL Access Layer components that need explicit
+ * transaction control on top of {@link DatabaseRepository}.
+ *
+ * Extends `DatabaseRepository<Schema>` and adds {@link transaction},
+ * a helper that runs a callback inside a Kysely transaction:
+ * commits on success, rolls back on throw.
+ *
+ * Error translation flows through {@link DatabaseRepository.translateError}
+ * — overriding it once on a dialect subclass covers both `exec` and
+ * `transaction`.
+ *
+ * ──────────────────────────────────────────────────────────────────
+ *  Overridable transaction hooks
+ * ──────────────────────────────────────────────────────────────────
+ *  - {@link onTransactionStart}    ← before the callback runs
+ *  - {@link onTransactionCommit}   ← after the callback resolves
+ *  - {@link onTransactionRollback} ← when the callback throws
+ *
+ * Each hook receives a `txId` — a short opaque identifier that
+ * correlates the three events of the same transaction. The id is
+ * generated per-call and has no meaning to the database (it's a
+ * sibling of telemetry trace ids, not of SQL `SAVEPOINT` names).
+ *
+ * @typeParam Schema  See {@link DatabaseRepository}.
+ *
+ * @example
+ * ```ts
+ * import { TransactionalDatabaseRepository } from '@xfarch/xf-sql'
+ *
+ * export class OrdersDb extends TransactionalDatabaseRepository<Schema> {
+ *   constructor() { super({ dialect: ... }) }
+ *   async init()      { await super.init() }
+ *   async terminate() { await super.terminate() }
+ *
+ *   async checkout(order: Order) {
+ *     return this.transaction(async (trx) => {
+ *       await trx.insertInto('orders').values(order).execute()
+ *       await trx.updateTable('inventory')
+ *         .set((eb) => ({ stock: eb('stock', '-', order.qty) }))
+ *         .where('sku', '=', order.sku)
+ *         .execute()
+ *       return order.id
+ *     })
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class TransactionalDatabaseRepository<Schema = unknown> extends DatabaseRepository<Schema> {
+    /**
+     * Run `callback` inside a database transaction. Commits if the
+     * callback resolves; rolls back if it throws.
+     *
+     * The argument passed to `callback` is a `Transaction<Schema>` —
+     * a Kysely-typed transaction handle. Use it (not `this.db`) for
+     * queries inside the transaction so they participate in the same
+     * unit of work.
+     *
+     * Errors thrown inside the callback are translated through
+     * {@link DatabaseRepository.translateError} before being rethrown.
+     */
+    protected transaction<R>(callback: (trx: Transaction<Schema>) => Promise<R>): Promise<R>;
+    /**
+     * Invoked just before the transaction callback runs. Default no-op.
+     * `txId` is a short opaque identifier that correlates the three
+     * events of the same transaction.
+     */
+    protected onTransactionStart(_txId: string): void;
+    /**
+     * Invoked after the transaction callback resolves successfully and
+     * the commit completes. `durationMs` measures the full lifetime of
+     * the transaction (including commit latency). Default no-op.
+     */
+    protected onTransactionCommit(_txId: string, _durationMs: number): void;
+    /**
+     * Invoked when the transaction callback throws and the rollback
+     * completes. `reason` is the original error (before
+     * {@link DatabaseRepository.translateError} is applied to the
+     * rethrow). Default no-op.
+     */
+    protected onTransactionRollback(_txId: string, _reason: unknown): void;
+    private static makeTxId;
+}
+//# sourceMappingURL=TransactionalDatabaseRepository.d.ts.map

package/dist/src/repository/base/TransactionalDatabaseRepository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransactionalDatabaseRepository.d.ts","sourceRoot":"","sources":["../../../../src/repository/base/TransactionalDatabaseRepository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAA;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,8BAAsB,+BAA+B,CAAC,MAAM,GAAG,OAAO,CACpE,SAAQ,kBAAkB,CAAC,MAAM,CAAC;IAElC;;;;;;;;;;;OAWG;cACa,WAAW,CAAC,CAAC,EAC3B,QAAQ,EAAE,CAAC,GAAG,EAAE,WAAW,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GACjD,OAAO,CAAC,CAAC,CAAC;IAgBb;;;;OAIG;IACH,SAAS,CAAC,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAEjD;;;;OAIG;IACH,SAAS,CAAC,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAEvE;;;;;OAKG;IACH,SAAS,CAAC,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAItE,OAAO,CAAC,MAAM,CAAC,QAAQ;CAKxB"}

package/dist/src/repository/base/TransactionalDatabaseRepository.js

@@ -0,0 +1,104 @@
+import { DatabaseRepository } from './DatabaseRepository.js';
+/**
+ * Generalization for SQL Access Layer components that need explicit
+ * transaction control on top of {@link DatabaseRepository}.
+ *
+ * Extends `DatabaseRepository<Schema>` and adds {@link transaction},
+ * a helper that runs a callback inside a Kysely transaction:
+ * commits on success, rolls back on throw.
+ *
+ * Error translation flows through {@link DatabaseRepository.translateError}
+ * — overriding it once on a dialect subclass covers both `exec` and
+ * `transaction`.
+ *
+ * ──────────────────────────────────────────────────────────────────
+ *  Overridable transaction hooks
+ * ──────────────────────────────────────────────────────────────────
+ *  - {@link onTransactionStart}    ← before the callback runs
+ *  - {@link onTransactionCommit}   ← after the callback resolves
+ *  - {@link onTransactionRollback} ← when the callback throws
+ *
+ * Each hook receives a `txId` — a short opaque identifier that
+ * correlates the three events of the same transaction. The id is
+ * generated per-call and has no meaning to the database (it's a
+ * sibling of telemetry trace ids, not of SQL `SAVEPOINT` names).
+ *
+ * @typeParam Schema  See {@link DatabaseRepository}.
+ *
+ * @example
+ * ```ts
+ * import { TransactionalDatabaseRepository } from '@xfarch/xf-sql'
+ *
+ * export class OrdersDb extends TransactionalDatabaseRepository<Schema> {
+ *   constructor() { super({ dialect: ... }) }
+ *   async init()      { await super.init() }
+ *   async terminate() { await super.terminate() }
+ *
+ *   async checkout(order: Order) {
+ *     return this.transaction(async (trx) => {
+ *       await trx.insertInto('orders').values(order).execute()
+ *       await trx.updateTable('inventory')
+ *         .set((eb) => ({ stock: eb('stock', '-', order.qty) }))
+ *         .where('sku', '=', order.sku)
+ *         .execute()
+ *       return order.id
+ *     })
+ *   }
+ * }
+ * ```
+ */
+export class TransactionalDatabaseRepository extends DatabaseRepository {
+    /**
+     * Run `callback` inside a database transaction. Commits if the
+     * callback resolves; rolls back if it throws.
+     *
+     * The argument passed to `callback` is a `Transaction<Schema>` —
+     * a Kysely-typed transaction handle. Use it (not `this.db`) for
+     * queries inside the transaction so they participate in the same
+     * unit of work.
+     *
+     * Errors thrown inside the callback are translated through
+     * {@link DatabaseRepository.translateError} before being rethrown.
+     */
+    async transaction(callback) {
+        const txId = TransactionalDatabaseRepository.makeTxId();
+        const startedAt = Date.now();
+        this.onTransactionStart(txId);
+        try {
+            const result = await this.db.transaction().execute(callback);
+            this.onTransactionCommit(txId, Date.now() - startedAt);
+            return result;
+        }
+        catch (err) {
+            this.onTransactionRollback(txId, err);
+            throw this.translateError(err);
+        }
+    }
+    // ─── Overridable transaction hooks ────────────────────────
+    /**
+     * Invoked just before the transaction callback runs. Default no-op.
+     * `txId` is a short opaque identifier that correlates the three
+     * events of the same transaction.
+     */
+    onTransactionStart(_txId) { }
+    /**
+     * Invoked after the transaction callback resolves successfully and
+     * the commit completes. `durationMs` measures the full lifetime of
+     * the transaction (including commit latency). Default no-op.
+     */
+    onTransactionCommit(_txId, _durationMs) { }
+    /**
+     * Invoked when the transaction callback throws and the rollback
+     * completes. `reason` is the original error (before
+     * {@link DatabaseRepository.translateError} is applied to the
+     * rethrow). Default no-op.
+     */
+    onTransactionRollback(_txId, _reason) { }
+    // ─── Internals ────────────────────────────────────────────
+    static makeTxId() {
+        const t = Date.now().toString(36);
+        const r = Math.floor(Math.random() * 0x100000).toString(36).padStart(4, '0');
+        return `tx-${t}-${r}`;
+    }
+}
+//# sourceMappingURL=TransactionalDatabaseRepository.js.map

package/dist/src/repository/base/TransactionalDatabaseRepository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransactionalDatabaseRepository.js","sourceRoot":"","sources":["../../../../src/repository/base/TransactionalDatabaseRepository.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,OAAgB,+BACpB,SAAQ,kBAA0B;IAElC;;;;;;;;;;;OAWG;IACO,KAAK,CAAC,WAAW,CACzB,QAAkD;QAElD,MAAM,IAAI,GAAG,+BAA+B,CAAC,QAAQ,EAAE,CAAA;QACvD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QAC5B,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAA;QAC7B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;YAC5D,IAAI,CAAC,mBAAmB,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,CAAA;YACtD,OAAO,MAAM,CAAA;QACf,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,qBAAqB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;YACrC,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAA;QAChC,CAAC;IACH,CAAC;IAED,6DAA6D;IAE7D;;;;OAIG;IACO,kBAAkB,CAAC,KAAa,IAAS,CAAC;IAEpD;;;;OAIG;IACO,mBAAmB,CAAC,KAAa,EAAE,WAAmB,IAAS,CAAC;IAE1E;;;;;OAKG;IACO,qBAAqB,CAAC,KAAa,EAAE,OAAgB,IAAS,CAAC;IAEzE,6DAA6D;IAErD,MAAM,CAAC,QAAQ;QACrB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;QACjC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;QAC5E,OAAO,MAAM,CAAC,IAAI,CAAC,EAAE,CAAA;IACvB,CAAC;CACF"}

package/dist/src/repository/general/DatabaseRepository.d.ts

@@ -0,0 +1,192 @@
+import { Repository } from '@xfcfam/xf';
+import { Kysely, type Dialect } from 'kysely';
+/**
+ * Configuration accepted by {@link DatabaseRepository}'s constructor.
+ *
+ * The `dialect` is the only required field. Dialect adapter packages
+ * such as `@xfcfam/xf-sql-postgres` build it for you behind a
+ * higher-level options shape.
+ */
+export interface DatabaseOptions {
+    /** Kysely Dialect implementation (Postgres, MySQL, SQLite, …). */
+    dialect: Dialect;
+}
+/**
+ * Base Generalization for the Access Layer when the underlying
+ * external system is a SQL database.
+ *
+ * Encapsulates the [Kysely](https://kysely.dev) query builder behind
+ * a single XF-canonical class. The implementer's concrete Logical
+ * extends this (or a dialect-specific subclass such as
+ * `PostgresDatabaseRepository`) and exposes domain-meaningful methods
+ * that compose queries against `this.db`, a `Kysely<Schema>` bound
+ * to the implementer's typed schema.
+ *
+ * Concrete dialect support lives in adapter packages — install one of
+ * `@xfcfam/xf-sql-postgres`, `@xfcfam/xf-sql-mysql`, etc., or supply
+ * any Kysely-compatible `Dialect` directly.
+ *
+ * ──────────────────────────────────────────────────────────────────
+ *  IMPORTANT — Required configuration for subclasses
+ * ──────────────────────────────────────────────────────────────────
+ * The underlying Kysely instance is held in a static private WeakMap
+ * and created inside {@link init}. If a subclass overrides `init()` /
+ * `terminate()`, it MUST chain through `super`:
+ *
+ *   async init()      { await super.init();      // own setup }
+ *   async terminate() { // own teardown;         await super.terminate() }
+ *
+ * Forgetting `super.init()` leaves `this.db` uninitialised and every
+ * query will throw {@link NotInitializedException}.
+ *
+ * ──────────────────────────────────────────────────────────────────
+ *  Overridable observation hooks
+ * ──────────────────────────────────────────────────────────────────
+ *  - {@link onConnected}     ← after `init()` creates the Kysely instance
+ *  - {@link onDisconnected}  ← after `terminate()` destroys it
+ *  - {@link onQuery}         ← for every query Kysely executes
+ *  - {@link onError}         ← for every {@link exec}-wrapped operation that rejects
+ *
+ *  Transaction hooks ({@link onTransactionStart} / Commit / Rollback)
+ *  live on {@link TransactionalDatabaseRepository}, the subclass that
+ *  exposes explicit transaction control.
+ *
+ * ──────────────────────────────────────────────────────────────────
+ *  Error translation
+ * ──────────────────────────────────────────────────────────────────
+ * Dialect-specific errors (driver Error objects) are not translated
+ * by this class — it does not know about Postgres SQLSTATEs, MySQL
+ * error numbers, etc. Use a dialect adapter subclass (such as
+ * `PostgresDatabaseRepository`) or override {@link translateError}
+ * yourself to map errors to the typed Exceptions exported from this
+ * package (`UniqueViolationException`, etc.).
+ *
+ * @typeParam Schema  Implementer-defined TypeScript interface mapping
+ *                    table names to their column shapes. See the
+ *                    Kysely docs for the conventions on
+ *                    `Generated`, `ColumnType`, etc.
+ *
+ * @example
+ * ```ts
+ * import { DatabaseRepository } from '@xfcfam/xf-sql'
+ * import { PostgresDialect } from 'kysely'
+ * import { Pool } from 'pg'
+ *
+ * interface Schema {
+ *   users: { id: number; name: string; email: string }
+ * }
+ *
+ * export class UsersDb extends DatabaseRepository<Schema> {
+ *   constructor() {
+ *     super({
+ *       dialect: new PostgresDialect({
+ *         pool: new Pool({ connectionString: process.env.DATABASE_URL }),
+ *       }),
+ *     })
+ *   }
+ *   async init()      { await super.init() }
+ *   async terminate() { await super.terminate() }
+ *
+ *   getUser(id: number) {
+ *     return this.db
+ *       .selectFrom('users')
+ *       .where('id', '=', id)
+ *       .selectAll()
+ *       .executeTakeFirstOrThrow()
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class DatabaseRepository<Schema = unknown> extends Repository<null> {
+    private static readonly state;
+    /** Options provided at construction time. */
+    protected readonly options: DatabaseOptions;
+    constructor(options: DatabaseOptions);
+    /**
+     * Typed Kysely instance bound to `Schema`. Use it to compose queries:
+     * `this.db.selectFrom('users')…`, `this.db.insertInto('users')…`.
+     * Throws if {@link init} has not been called.
+     */
+    protected get db(): Kysely<Schema>;
+    /**
+     * Subclasses that override this method MUST call `await super.init()`
+     * **first**; otherwise {@link db} will throw on use.
+     */
+    init(): Promise<void>;
+    /**
+     * Subclasses that override this method MUST call `await super.terminate()`
+     * **last** to release the connection pool held by the Kysely instance.
+     */
+    terminate(): Promise<void>;
+    /**
+     * Hook for dialect-specific error translation. Default
+     * implementation is identity (returns the input unchanged).
+     *
+     * Dialect adapter subclasses (such as `PostgresDatabaseRepository`)
+     * override this to map driver errors to the typed Exceptions
+     * exported from this package.
+     *
+     * Called automatically by {@link exec}; not called for direct
+     * `this.db.…` usage, where the implementer is responsible for
+     * wrapping queries in `this.exec(...)`.
+     */
+    protected translateError(err: unknown): unknown;
+    /**
+     * Execute an operation against the database, translating any
+     * dialect-specific errors to xf-sql Exception types via
+     * {@link translateError}.
+     *
+     * Use this whenever you need automatic error translation. For raw
+     * Kysely access without translation, use {@link db} directly.
+     *
+     * @example
+     * ```ts
+     * async createUser(input: UserInput) {
+     *   return this.exec(() =>
+     *     this.db.insertInto('users').values(input).returningAll().executeTakeFirstOrThrow()
+     *   )
+     * }
+     * ```
+     */
+    protected exec<R>(op: () => Promise<R>): Promise<R>;
+    /**
+     * Invoked after `init()` has created the Kysely instance. Default
+     * no-op. Override for connection-open telemetry, schema migrations,
+     * connection warmup, etc.
+     */
+    protected onConnected(): Promise<void>;
+    /**
+     * Invoked after `terminate()` has destroyed the Kysely instance.
+     * Default no-op. Override for connection-close telemetry.
+     */
+    protected onDisconnected(): Promise<void>;
+    /**
+     * Invoked for every query Kysely executes (both standalone and
+     * inside transactions). Receives the compiled SQL and the bound
+     * parameters. Default no-op.
+     *
+     * Use for audit logging or query profiling. The hook runs
+     * synchronously inside Kysely's pipeline — keep it cheap and avoid
+     * blocking work.
+     */
+    protected onQuery(_sql: string, _params: readonly unknown[]): void;
+    /**
+     * Invoked when an `exec()`-wrapped operation rejects, or when
+     * Kysely emits a query-level error. The `operation` label
+     * distinguishes the source (`'exec'`, `'query'`, or the value
+     * supplied by a subclass). Default no-op.
+     *
+     * The hook fires before {@link translateError}; the (possibly
+     * untranslated) error is still re-thrown to the caller.
+     *
+     * The hook may be `async` — the `exec()` call site `await`s it, so
+     * an async override is fully observed before the error is rethrown.
+     * Note: the Kysely log callback (`'query'` source) is synchronous by
+     * Kysely's API contract and cannot `await` the hook; async overrides
+     * that target only that source will execute fire-and-forget from that
+     * path. If reliable async observability of query-level Kysely errors
+     * is required, wrap the hook body with its own error handling.
+     */
+    protected onError(_operation: string, _error: unknown): void | Promise<void>;
+}
+//# sourceMappingURL=DatabaseRepository.d.ts.map

package/dist/src/repository/general/DatabaseRepository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DatabaseRepository.d.ts","sourceRoot":"","sources":["../../../../src/repository/general/DatabaseRepository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA2B,MAAM,YAAY,CAAA;AAChE,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAA;AAE7C;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAA;CACjB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,8BAAsB,kBAAkB,CAAC,MAAM,GAAG,OAAO,CAAE,SAAQ,UAAU,CAAC,IAAI,CAAC;IACjF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAuC;IAEpE,6CAA6C;IAC7C,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;gBAE/B,OAAO,EAAE,eAAe;IAKpC;;;;OAIG;IACH,SAAS,KAAK,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,CAMjC;IAED;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB3B;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAShC;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO;IAI/C;;;;;;;;;;;;;;;;OAgBG;cACa,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAWzD;;;;OAIG;cACa,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAE5C;;;OAGG;cACa,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAE/C;;;;;;;;OAQG;IACH,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAElE;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAC7E"}