@xfcfam/xf-sql 0.1.0

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

@@ -0,0 +1,224 @@
+import { Repository, NotInitializedException } from '@xfcfam/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
+ * `@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 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) {
+            await 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.
+     *
+     * 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.
+     */
+    onError(_operation, _error) { }
+}
+//# sourceMappingURL=DatabaseRepository.js.map

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

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

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

@@ -0,0 +1,91 @@
+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 '@xfcfam/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.
+     *
+     * The hook may be `async` — it is `await`ed before the original
+     * error is rethrown. If the hook itself throws, the exception is
+     * swallowed so the original transaction error is always the one
+     * propagated to the caller.
+     */
+    protected onTransactionRollback(_txId: string, _reason: unknown): void | Promise<void>;
+    private static makeTxId;
+}
+//# sourceMappingURL=TransactionalDatabaseRepository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TransactionalDatabaseRepository.d.ts","sourceRoot":"","sources":["../../../../src/repository/general/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;IAoBb;;;;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;;;;;;;;;;OAUG;IACH,SAAS,CAAC,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAItF,OAAO,CAAC,MAAM,CAAC,QAAQ;CAKxB"}

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

@@ -0,0 +1,114 @@
+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 '@xfcfam/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) {
+            try {
+                await this.onTransactionRollback(txId, err);
+            }
+            catch {
+                // A throwing rollback hook must not mask the original error.
+            }
+            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.
+     *
+     * The hook may be `async` — it is `await`ed before the original
+     * error is rethrown. If the hook itself throws, the exception is
+     * swallowed so the original transaction error is always the one
+     * propagated to the caller.
+     */
+    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/general/TransactionalDatabaseRepository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransactionalDatabaseRepository.js","sourceRoot":"","sources":["../../../../src/repository/general/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;gBACH,MAAM,IAAI,CAAC,qBAAqB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;YAC7C,CAAC;YAAC,MAAM,CAAC;gBACP,6DAA6D;YAC/D,CAAC;YACD,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;;;;;;;;;;OAUG;IACO,qBAAqB,CAAC,KAAa,EAAE,OAAgB,IAAyB,CAAC;IAEzF,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/structs/CheckViolationException.d.ts

@@ -0,0 +1,19 @@
+import { DatabaseException } from './DatabaseException.js';
+/**
+ * Thrown when an INSERT or UPDATE violates a CHECK constraint.
+ *
+ * The constraint name (when exposed by the driver) often matches the
+ * named CHECK in the schema, e.g. `users_age_positive_check`.
+ */
+export declare class CheckViolationException extends DatabaseException {
+    /** Name of the violated CHECK constraint, if known. */
+    readonly constraint?: string;
+    /** Table where the violation occurred, if known. */
+    readonly table?: string;
+    constructor(message: string, details?: {
+        constraint?: string;
+        table?: string;
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=CheckViolationException.d.ts.map

package/dist/src/repository/structs/CheckViolationException.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CheckViolationException.d.ts","sourceRoot":"","sources":["../../../../src/repository/structs/CheckViolationException.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAE1D;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,iBAAiB;IAC5D,uDAAuD;IACvD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,oDAAoD;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;gBAGrB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAOzE"}

package/dist/src/repository/structs/CheckViolationException.js

@@ -0,0 +1,22 @@
+import { DatabaseException } from './DatabaseException.js';
+/**
+ * Thrown when an INSERT or UPDATE violates a CHECK constraint.
+ *
+ * The constraint name (when exposed by the driver) often matches the
+ * named CHECK in the schema, e.g. `users_age_positive_check`.
+ */
+export class CheckViolationException extends DatabaseException {
+    /** Name of the violated CHECK constraint, if known. */
+    constraint;
+    /** Table where the violation occurred, if known. */
+    table;
+    constructor(message, details = {}) {
+        super(message, { cause: details.cause });
+        this.name = 'CheckViolationException';
+        if (details.constraint !== undefined)
+            this.constraint = details.constraint;
+        if (details.table !== undefined)
+            this.table = details.table;
+    }
+}
+//# sourceMappingURL=CheckViolationException.js.map

package/dist/src/repository/structs/CheckViolationException.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CheckViolationException.js","sourceRoot":"","sources":["../../../../src/repository/structs/CheckViolationException.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,OAAO,uBAAwB,SAAQ,iBAAiB;IAC5D,uDAAuD;IAC9C,UAAU,CAAS;IAC5B,oDAAoD;IAC3C,KAAK,CAAS;IAEvB,YACE,OAAe,EACf,UAAoE,EAAE;QAEtE,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAA;QACxC,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAA;QACrC,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS;YAAE,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAA;QAC1E,IAAI,OAAO,CAAC,KAAK,KAAU,SAAS;YAAE,IAAI,CAAC,KAAK,GAAQ,OAAO,CAAC,KAAK,CAAA;IACvE,CAAC;CACF"}

package/dist/src/repository/structs/ConnectionException.d.ts

@@ -0,0 +1,15 @@
+import { DatabaseException } from './DatabaseException.js';
+/**
+ * Thrown when the database is unreachable — DNS failure, TCP refused,
+ * TLS handshake failure, statement / connection timeout, etc.
+ *
+ * The original transport error is preserved as the standard
+ * `Error.cause`. Use this alongside `RetryableRepository.withRetry`
+ * to back off and retry on transient transport failures.
+ */
+export declare class ConnectionException extends DatabaseException {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=ConnectionException.d.ts.map

package/dist/src/repository/structs/ConnectionException.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConnectionException.d.ts","sourceRoot":"","sources":["../../../../src/repository/structs/ConnectionException.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAE1D;;;;;;;GAOG;AACH,qBAAa,mBAAoB,SAAQ,iBAAiB;gBAC5C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D"}

package/dist/src/repository/structs/ConnectionException.js

@@ -0,0 +1,16 @@
+import { DatabaseException } from './DatabaseException.js';
+/**
+ * Thrown when the database is unreachable — DNS failure, TCP refused,
+ * TLS handshake failure, statement / connection timeout, etc.
+ *
+ * The original transport error is preserved as the standard
+ * `Error.cause`. Use this alongside `RetryableRepository.withRetry`
+ * to back off and retry on transient transport failures.
+ */
+export class ConnectionException extends DatabaseException {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'ConnectionException';
+    }
+}
+//# sourceMappingURL=ConnectionException.js.map

package/dist/src/repository/structs/ConnectionException.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConnectionException.js","sourceRoot":"","sources":["../../../../src/repository/structs/ConnectionException.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAE1D;;;;;;;GAOG;AACH,MAAM,OAAO,mBAAoB,SAAQ,iBAAiB;IACxD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACnC,CAAC;CACF"}

package/dist/src/repository/structs/DatabaseException.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Base type for every database-related error raised through xf-sql.
+ *
+ * Every concrete dialect-specific Exception in `@xfarch/xf-sql` is a
+ * subclass of `DatabaseException`. Consumers can branch on the
+ * specific subclass (e.g. `UniqueViolationException`) or fall back to
+ * `instanceof DatabaseException` to catch any DB-originated error.
+ */
+export declare class DatabaseException extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=DatabaseException.d.ts.map

package/dist/src/repository/structs/DatabaseException.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DatabaseException.d.ts","sourceRoot":"","sources":["../../../../src/repository/structs/DatabaseException.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D"}

package/dist/src/repository/structs/DatabaseException.js

@@ -0,0 +1,15 @@
+/**
+ * Base type for every database-related error raised through xf-sql.
+ *
+ * Every concrete dialect-specific Exception in `@xfarch/xf-sql` is a
+ * subclass of `DatabaseException`. Consumers can branch on the
+ * specific subclass (e.g. `UniqueViolationException`) or fall back to
+ * `instanceof DatabaseException` to catch any DB-originated error.
+ */
+export class DatabaseException extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'DatabaseException';
+    }
+}
+//# sourceMappingURL=DatabaseException.js.map

package/dist/src/repository/structs/DatabaseException.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DatabaseException.js","sourceRoot":"","sources":["../../../../src/repository/structs/DatabaseException.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAA;IACjC,CAAC;CACF"}

package/dist/src/repository/structs/DeadlockException.d.ts

@@ -0,0 +1,16 @@
+import { DatabaseException } from './DatabaseException.js';
+/**
+ * Thrown when the database detects a deadlock and aborts one of the
+ * conflicting transactions.
+ *
+ * Deadlocks are typically retryable — the transaction can be re-run
+ * and will usually succeed once the conflicting party has finished.
+ * Pair with `RetryableRepository.withRetry` or
+ * `RetryRestRepository`-style policies in your Logical.
+ */
+export declare class DeadlockException extends DatabaseException {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=DeadlockException.d.ts.map

package/dist/src/repository/structs/DeadlockException.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeadlockException.d.ts","sourceRoot":"","sources":["../../../../src/repository/structs/DeadlockException.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAE1D;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,SAAQ,iBAAiB;gBAC1C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D"}

package/dist/src/repository/structs/DeadlockException.js

@@ -0,0 +1,17 @@
+import { DatabaseException } from './DatabaseException.js';
+/**
+ * Thrown when the database detects a deadlock and aborts one of the
+ * conflicting transactions.
+ *
+ * Deadlocks are typically retryable — the transaction can be re-run
+ * and will usually succeed once the conflicting party has finished.
+ * Pair with `RetryableRepository.withRetry` or
+ * `RetryRestRepository`-style policies in your Logical.
+ */
+export class DeadlockException extends DatabaseException {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'DeadlockException';
+    }
+}
+//# sourceMappingURL=DeadlockException.js.map

package/dist/src/repository/structs/DeadlockException.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeadlockException.js","sourceRoot":"","sources":["../../../../src/repository/structs/DeadlockException.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAE1D;;;;;;;;GAQG;AACH,MAAM,OAAO,iBAAkB,SAAQ,iBAAiB;IACtD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAA;IACjC,CAAC;CACF"}

package/dist/src/repository/structs/ForeignKeyViolationException.d.ts

@@ -0,0 +1,20 @@
+import { DatabaseException } from './DatabaseException.js';
+/**
+ * Thrown when an INSERT, UPDATE or DELETE violates a FOREIGN KEY
+ * constraint.
+ *
+ * Common scenarios: inserting a row that references a non-existent
+ * parent; deleting a row that is still referenced by children.
+ */
+export declare class ForeignKeyViolationException extends DatabaseException {
+    /** Name of the violated foreign-key constraint, if known. */
+    readonly constraint?: string;
+    /** Table where the violation occurred, if known. */
+    readonly table?: string;
+    constructor(message: string, details?: {
+        constraint?: string;
+        table?: string;
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=ForeignKeyViolationException.d.ts.map

package/dist/src/repository/structs/ForeignKeyViolationException.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ForeignKeyViolationException.d.ts","sourceRoot":"","sources":["../../../../src/repository/structs/ForeignKeyViolationException.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAE1D;;;;;;GAMG;AACH,qBAAa,4BAA6B,SAAQ,iBAAiB;IACjE,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,oDAAoD;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;gBAGrB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAOzE"}