@xfcfam/xf-sql 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Israel Sanjurjo and the XF contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# `@xfcfam/xf-sql`
+
+SQL Access Layer Generalization for the **XF Architecture Model**.
+Encapsulates the [Kysely](https://kysely.dev) query builder behind a
+single XF-canonical class plus a typed Exception hierarchy.
+
+**Dialect-agnostic.** xf-sql talks to any database for which Kysely
+has a dialect implementation. Pair it with one of the adapter
+packages:
+
+- [`@xfcfam/xf-sql-postgres`](https://www.npmjs.com/package/@xfcfam/xf-sql-postgres) — Postgres via `pg`
+- (future) `@xfcfam/xf-sql-mysql`, `@xfcfam/xf-sql-sqlite`, …
+
+Or supply any Kysely `Dialect` directly to `DatabaseRepository`.
+
+Peer dependency: `@xfcfam/xf`. `kysely` is a direct (bundled) dependency.
+
+## Install
+
+```bash
+pnpm add @xfcfam/xf @xfcfam/xf-sql kysely
+# plus one dialect adapter, e.g.
+pnpm add @xfcfam/xf-sql-postgres pg
+```
+
+## What ships here
+
+| Export | Role |
+|---|---|
+| `DatabaseRepository<Schema>` | Access Layer Generalization. Constructor `({ dialect })`. Protected `db: Kysely<Schema>`. `exec(op)` wrapper that funnels errors through `translateError`. Overridable hooks: `onConnected`, `onDisconnected`, `onQuery`, `onError`. |
+| `TransactionalDatabaseRepository<Schema>` | Adds `transaction(callback)` that commits / rolls back the Kysely transaction and translates errors. Overridable hooks: `onTransactionStart`, `onTransactionCommit`, `onTransactionRollback`. |
+| `DatabaseException` | Base class for every typed DB error. |
+| `ConnectionException` | Database unreachable (DNS, refused, TLS, timeout). |
+| `UniqueViolationException` | `UNIQUE` / `PRIMARY KEY` constraint violated. Carries `constraint`, `table`, `column`. |
+| `ForeignKeyViolationException` | `FOREIGN KEY` constraint violated. Carries `constraint`, `table`. |
+| `CheckViolationException` | `CHECK` constraint violated. Carries `constraint`, `table`. |
+| `NotNullViolationException` | `NOT NULL` column set to `NULL`. Carries `table`, `column`. |
+| `DeadlockException` | DB-detected deadlock; typically retryable. |
+
+## Quick usage
+
+```typescript
+import { TransactionalDatabaseRepository, UniqueViolationException } from '@xfcfam/xf-sql'
+import { PostgresDialect } from 'kysely'
+import { Pool } from 'pg'
+
+interface Schema {
+  users: { id: number; name: string; email: string; created_at: Date }
+}
+
+export class UsersDb extends TransactionalDatabaseRepository<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.exec(() =>
+      this.db.selectFrom('users').where('id', '=', id).selectAll().executeTakeFirstOrThrow()
+    )
+  }
+
+  createUser(input: { name: string; email: string }) {
+    return this.exec(() =>
+      this.db
+        .insertInto('users')
+        .values({ ...input, created_at: new Date() })
+        .returningAll()
+        .executeTakeFirstOrThrow()
+    )
+  }
+}
+```
+
+> The example above uses the generic `DatabaseRepository` with a
+> raw Kysely dialect. In a real project you would typically extend
+> `PostgresDatabaseRepository` from `@xfcfam/xf-sql-postgres`, which
+> wires the dialect and translates Postgres errors automatically.
+
+## Batching pattern (deferred writes)
+
+When a workload generates many small writes, batching them into a
+single transaction can cut latency and load on the database
+dramatically. xf-sql doesn't ship a dedicated "batch repository" —
+batching is a Business-Layer concern (a policy on **when** to write),
+not a SQL protocol concern. Compose the building blocks:
+
+- **`BatchedBusiness<T>`** from `@xfcfam/xf` accumulates items in
+  memory and flushes them by size, by time, manually or on terminate.
+  Dialect-agnostic — works with Postgres, MySQL, SQLite, anything.
+- **`TransactionalDatabaseRepository`** in the consumer's Access
+  Layer executes the flush as a single transaction.
+
+```typescript
+import { BatchedBusiness } from '@xfcfam/xf'
+import { R } from '../R.js'                  // your Access injection
+
+interface AuditEvent { actor: string; action: string; at: Date }
+
+export class AuditBatchBusiness extends BatchedBusiness<AuditEvent> {
+  constructor() {
+    super({
+      maxSize: 500,          // flush when 500 events queued, OR
+      maxAgeMs: 5_000,       // every 5 seconds, whichever comes first
+      onErrorPolicy: 'retain',
+      flush: batch => R.auditDb.recordMany(batch),  // single TX on the receiving Repository
+    })
+  }
+
+  record(event: AuditEvent) { this.add(event) }
+
+  protected override onFlushStart(batch: readonly AuditEvent[], reason) {
+    console.log(`[audit] flushing ${batch.length} events (${reason})`)
+  }
+  protected override onFlushError(batch, err) {
+    console.error(`[audit] flush failed, ${batch.length} events retained`, err)
+  }
+}
+```
+
+And on the receiving Repository:
+
+```typescript
+import { TransactionalDatabaseRepository } from '@xfcfam/xf-sql'
+
+export class AuditDb extends TransactionalDatabaseRepository<Schema> {
+  recordMany(batch: readonly AuditEvent[]) {
+    return this.transaction(async (trx) => {
+      await trx.insertInto('audit').values([...batch]).execute()
+    })
+  }
+}
+```
+
+This pattern is **fully compatible across dialects** — `AuditBatchBusiness`
+doesn't know whether the target is Postgres, MySQL or SQLite. Swap the
+dialect adapter, the business component stays unchanged.
+
+## Error translation
+
+xf-sql defines the Exception types but **does not translate driver
+errors itself** — it doesn't know about Postgres SQLSTATEs or MySQL
+error numbers. Either:
+
+- Use a dialect adapter (e.g. `PostgresDatabaseRepository`) that
+  overrides `translateError` for you, **or**
+- Override `translateError(err)` in your own subclass and map the
+  driver's error shape to the `*Exception` types above.
+
+Wrap queries in `this.exec(() => …)` so the translation runs.
+Transactions are wrapped automatically by
+`TransactionalDatabaseRepository.transaction`.
+
+## Documentation
+
+- Specification — [xfcfam.org](https://xfcfam.org)
+- Kysely docs — [kysely.dev](https://kysely.dev)
+- Source — [github.com/xfcfam/lib-npm](https://github.com/xfcfam/lib-npm)
+
+## License
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@xfcfam/xf-sql` — SQL Access Layer Generalization for the XF
+ * Architecture Model.
+ *
+ * Encapsulates the [Kysely](https://kysely.dev) query builder behind
+ * an XF-canonical Generalization (`DatabaseRepository`) plus a
+ * transaction-aware specialisation (`TransactionalDatabaseRepository`)
+ * and a typed Exception hierarchy.
+ *
+ * xf-sql is **dialect-agnostic**: pair it with one of the dialect
+ * adapter packages (`@xfcfam/xf-sql-postgres`,
+ * `@xfcfam/xf-sql-mysql`, …) or supply any Kysely `Dialect` directly.
+ *
+ * Peer dependency: `@xfcfam/xf`. `kysely` is a direct (bundled) dependency.
+ */
+export { DatabaseRepository } from './src/repository/general/DatabaseRepository.js';
+export type { DatabaseOptions } from './src/repository/general/DatabaseRepository.js';
+export { TransactionalDatabaseRepository } from './src/repository/general/TransactionalDatabaseRepository.js';
+export { DatabaseException } from './src/repository/transfers/DatabaseException.js';
+export { ConnectionException } from './src/repository/transfers/ConnectionException.js';
+export { UniqueViolationException } from './src/repository/transfers/UniqueViolationException.js';
+export { ForeignKeyViolationException } from './src/repository/transfers/ForeignKeyViolationException.js';
+export { CheckViolationException } from './src/repository/transfers/CheckViolationException.js';
+export { NotNullViolationException } from './src/repository/transfers/NotNullViolationException.js';
+export { DeadlockException } from './src/repository/transfers/DeadlockException.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAA;AACnF,YAAY,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAA;AACrF,OAAO,EAAE,+BAA+B,EAAE,MAAM,6DAA6D,CAAA;AAG7G,OAAO,EAAE,iBAAiB,EAAE,MAAiB,iDAAiD,CAAA;AAC9F,OAAO,EAAE,mBAAmB,EAAE,MAAe,mDAAmD,CAAA;AAChG,OAAO,EAAE,wBAAwB,EAAE,MAAU,wDAAwD,CAAA;AACrG,OAAO,EAAE,4BAA4B,EAAE,MAAM,4DAA4D,CAAA;AACzG,OAAO,EAAE,uBAAuB,EAAE,MAAW,uDAAuD,CAAA;AACpG,OAAO,EAAE,yBAAyB,EAAE,MAAS,yDAAyD,CAAA;AACtG,OAAO,EAAE,iBAAiB,EAAE,MAAiB,iDAAiD,CAAA"}

package/dist/index.js

@@ -0,0 +1,27 @@
+/**
+ * `@xfcfam/xf-sql` — SQL Access Layer Generalization for the XF
+ * Architecture Model.
+ *
+ * Encapsulates the [Kysely](https://kysely.dev) query builder behind
+ * an XF-canonical Generalization (`DatabaseRepository`) plus a
+ * transaction-aware specialisation (`TransactionalDatabaseRepository`)
+ * and a typed Exception hierarchy.
+ *
+ * xf-sql is **dialect-agnostic**: pair it with one of the dialect
+ * adapter packages (`@xfcfam/xf-sql-postgres`,
+ * `@xfcfam/xf-sql-mysql`, …) or supply any Kysely `Dialect` directly.
+ *
+ * Peer dependency: `@xfcfam/xf`. `kysely` is a direct (bundled) dependency.
+ */
+// ── Access — base ─────────────────────────────────────────
+export { DatabaseRepository } from './src/repository/general/DatabaseRepository.js';
+export { TransactionalDatabaseRepository } from './src/repository/general/TransactionalDatabaseRepository.js';
+// ── Access — structs (Exceptions) ─────────────────────────
+export { DatabaseException } from './src/repository/transfers/DatabaseException.js';
+export { ConnectionException } from './src/repository/transfers/ConnectionException.js';
+export { UniqueViolationException } from './src/repository/transfers/UniqueViolationException.js';
+export { ForeignKeyViolationException } from './src/repository/transfers/ForeignKeyViolationException.js';
+export { CheckViolationException } from './src/repository/transfers/CheckViolationException.js';
+export { NotNullViolationException } from './src/repository/transfers/NotNullViolationException.js';
+export { DeadlockException } from './src/repository/transfers/DeadlockException.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,6DAA6D;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAA;AAEnF,OAAO,EAAE,+BAA+B,EAAE,MAAM,6DAA6D,CAAA;AAE7G,6DAA6D;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAiB,iDAAiD,CAAA;AAC9F,OAAO,EAAE,mBAAmB,EAAE,MAAe,mDAAmD,CAAA;AAChG,OAAO,EAAE,wBAAwB,EAAE,MAAU,wDAAwD,CAAA;AACrG,OAAO,EAAE,4BAA4B,EAAE,MAAM,4DAA4D,CAAA;AACzG,OAAO,EAAE,uBAAuB,EAAE,MAAW,uDAAuD,CAAA;AACpG,OAAO,EAAE,yBAAyB,EAAE,MAAS,yDAAyD,CAAA;AACtG,OAAO,EAAE,iBAAiB,EAAE,MAAiB,iDAAiD,CAAA"}

package/dist/src/api/A.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Interaction Layer Injection — placeholder.
+ *
+ * `A` is the canonical injection of the Interaction Layer. `@xfcfam/xf-sql`
+ * is a library that contributes Generalizations and Transfer objects;
+ * it does not own any Logical of this layer, so its own `A` declares
+ * no static slots. The class is kept structurally complete (private
+ * constructor + empty `init` / `terminate`) so the artefact passes XF
+ * validation. It is NOT exported from the package — consumers import
+ * `A` from their own artefact.
+ */
+export declare class A {
+    private constructor();
+    static init(): Promise<void>;
+    static terminate(): Promise<void>;
+}
+//# sourceMappingURL=A.d.ts.map

package/dist/src/api/A.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"A.d.ts","sourceRoot":"","sources":["../../../src/api/A.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,qBAAa,CAAC;IACZ,OAAO;WACM,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;WACrB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CACxC"}

package/dist/src/api/A.js

@@ -0,0 +1,17 @@
+/**
+ * Interaction Layer Injection — placeholder.
+ *
+ * `A` is the canonical injection of the Interaction Layer. `@xfcfam/xf-sql`
+ * is a library that contributes Generalizations and Transfer objects;
+ * it does not own any Logical of this layer, so its own `A` declares
+ * no static slots. The class is kept structurally complete (private
+ * constructor + empty `init` / `terminate`) so the artefact passes XF
+ * validation. It is NOT exported from the package — consumers import
+ * `A` from their own artefact.
+ */
+export class A {
+    constructor() { }
+    static async init() { }
+    static async terminate() { }
+}
+//# sourceMappingURL=A.js.map

package/dist/src/api/A.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"A.js","sourceRoot":"","sources":["../../../src/api/A.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,CAAC;IACZ,gBAAuB,CAAC;IACxB,MAAM,CAAC,KAAK,CAAC,IAAI,KAAmB,CAAC;IACrC,MAAM,CAAC,KAAK,CAAC,SAAS,KAAmB,CAAC;CAC3C"}

package/dist/src/business/B.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Business Layer Injection — placeholder.
+ *
+ * `B` is the canonical injection of the Business Layer. `@xfcfam/xf-sql`
+ * is a library that contributes Generalizations and Transfer objects;
+ * it does not own any Logical of this layer, so its own `B` declares
+ * no static slots. The class is kept structurally complete (private
+ * constructor + empty `init` / `terminate`) so the artefact passes XF
+ * validation. It is NOT exported from the package — consumers import
+ * `B` from their own artefact.
+ */
+export declare class B {
+    private constructor();
+    static init(): Promise<void>;
+    static terminate(): Promise<void>;
+}
+//# sourceMappingURL=B.d.ts.map

package/dist/src/business/B.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"B.d.ts","sourceRoot":"","sources":["../../../src/business/B.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,qBAAa,CAAC;IACZ,OAAO;WACM,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;WACrB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CACxC"}

package/dist/src/business/B.js

@@ -0,0 +1,17 @@
+/**
+ * Business Layer Injection — placeholder.
+ *
+ * `B` is the canonical injection of the Business Layer. `@xfcfam/xf-sql`
+ * is a library that contributes Generalizations and Transfer objects;
+ * it does not own any Logical of this layer, so its own `B` declares
+ * no static slots. The class is kept structurally complete (private
+ * constructor + empty `init` / `terminate`) so the artefact passes XF
+ * validation. It is NOT exported from the package — consumers import
+ * `B` from their own artefact.
+ */
+export class B {
+    constructor() { }
+    static async init() { }
+    static async terminate() { }
+}
+//# sourceMappingURL=B.js.map

package/dist/src/business/B.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"B.js","sourceRoot":"","sources":["../../../src/business/B.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,CAAC;IACZ,gBAAuB,CAAC;IACxB,MAAM,CAAC,KAAK,CAAC,IAAI,KAAmB,CAAC;IACrC,MAAM,CAAC,KAAK,CAAC,SAAS,KAAmB,CAAC;CAC3C"}

package/dist/src/repository/R.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Access Layer Injection — placeholder.
+ *
+ * `R` is the canonical injection of the Access Layer. `@xfcfam/xf-sql`
+ * is a library that contributes Generalizations and Transfer objects;
+ * it does not own any Logical of this layer, so its own `R` declares
+ * no static slots. The class is kept structurally complete (private
+ * constructor + empty `init` / `terminate`) so the artefact passes XF
+ * validation. It is NOT exported from the package — consumers import
+ * `R` from their own artefact.
+ */
+export declare class R {
+    private constructor();
+    static init(): Promise<void>;
+    static terminate(): Promise<void>;
+}
+//# sourceMappingURL=R.d.ts.map

package/dist/src/repository/R.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"R.d.ts","sourceRoot":"","sources":["../../../src/repository/R.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,qBAAa,CAAC;IACZ,OAAO;WACM,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;WACrB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CACxC"}

package/dist/src/repository/R.js

@@ -0,0 +1,17 @@
+/**
+ * Access Layer Injection — placeholder.
+ *
+ * `R` is the canonical injection of the Access Layer. `@xfcfam/xf-sql`
+ * is a library that contributes Generalizations and Transfer objects;
+ * it does not own any Logical of this layer, so its own `R` declares
+ * no static slots. The class is kept structurally complete (private
+ * constructor + empty `init` / `terminate`) so the artefact passes XF
+ * validation. It is NOT exported from the package — consumers import
+ * `R` from their own artefact.
+ */
+export class R {
+    constructor() { }
+    static async init() { }
+    static async terminate() { }
+}
+//# sourceMappingURL=R.js.map

package/dist/src/repository/R.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"R.js","sourceRoot":"","sources":["../../../src/repository/R.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,CAAC;IACZ,gBAAuB,CAAC;IACxB,MAAM,CAAC,KAAK,CAAC,IAAI,KAAmB,CAAC;IACrC,MAAM,CAAC,KAAK,CAAC,SAAS,KAAmB,CAAC;CAC3C"}

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

@@ -0,0 +1,184 @@
+import { Repository } from '@xfarch/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 `@xfarch/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
+ * `@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 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.
+     */
+    protected onError(_operation: string, _error: unknown): void;
+}
+//# sourceMappingURL=DatabaseRepository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DatabaseRepository.d.ts","sourceRoot":"","sources":["../../../../src/repository/base/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;;;;;;;;OAQG;IACH,SAAS,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;CAC7D"}