@xfcfam/xf-sql-postgres 0.1.0 → 0.1.1

package/README.md

@@ -5,15 +5,18 @@ Encapsulates `kysely`'s `PostgresDialect` over the [`pg`](https://node-postgres.
 driver and ships the SQLSTATE → typed-Exception translation so the
 Business Layer never sees `pg` errors.
 
-Peer dependencies: [`@xfcfam/xf`](https://www.npmjs.com/package/@xfcfam/xf),
-[`@xfcfam/xf-sql`](https://www.npmjs.com/package/@xfcfam/xf-sql),
-[`kysely`](https://kysely.dev).
-Runtime dependency: `pg`.
+Peer dependencies: [`@xfcfam/xf`](https://www.npmjs.com/package/@xfcfam/xf)
+and [`@xfcfam/xf-sql`](https://www.npmjs.com/package/@xfcfam/xf-sql). The
+[`pg`](https://node-postgres.com) driver and the
+[`kysely`](https://kysely.dev) query builder are **bundled and wired
+internally**: the adapter builds the `pg.Pool` and the `PostgresDialect`
+for you in its constructor, so the implementer never installs or imports
+either one (`kysely` arrives transitively through `@xfcfam/xf-sql`).
 
 ## Install
 
 ```bash
-pnpm add @xfcfam/xf @xfcfam/xf-sql @xfcfam/xf-sql-postgres kysely pg
+pnpm add @xfcfam/xf @xfcfam/xf-sql @xfcfam/xf-sql-postgres
 ```
 
 ## What ships here

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfcfam/xf-sql-postgres",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "PostgreSQL dialect adapter for @xfcfam/xf-sql. Encapsulates kysely's PostgresDialect and the `pg` driver. Translates Postgres SQLSTATE codes into the typed Exceptions of @xfcfam/xf-sql.",
   "author": "XF Contributors",
   "license": "MIT",
@@ -35,16 +35,16 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@xfcfam/xf-sql": "^0.1.0",
-    "@xfcfam/xf": "^0.2.0"
+    "@xfcfam/xf": "^0.2.0",
+    "@xfcfam/xf-sql": "^0.1.2"
   },
   "dependencies": {
     "pg": "^8.11.0"
   },
   "devDependencies": {
     "typescript": "^5.4.0",
-    "vitest": "^2.0.0",
-    "kysely": "^0.27.0",
+    "vitest": "^3.2.6",
+    "kysely": "^0.28.17",
     "@types/pg": "^8.11.0"
   },
   "scripts": {

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

@@ -1,91 +0,0 @@
-import { TransactionalDatabaseRepository } from '@xfarch/xf-sql';
-import { type PoolConfig } from 'pg';
-/**
- * Configuration accepted by {@link PostgresDatabaseRepository}'s
- * constructor.
- *
- * Either provide a `connectionString` (the simplest path), a full
- * `pg.PoolConfig`, or both — they are merged with the connection
- * string taking precedence for connection coordinates.
- */
-export interface PostgresOptions {
-    /** Postgres connection string (`postgres://user:pass@host:port/db?…`). */
-    connectionString?: string;
-    /** Extra `pg.PoolConfig` fields: `max`, `idleTimeoutMillis`, `ssl`, … */
-    pool?: PoolConfig;
-}
-/**
- * Ready-to-use Generalization for the Access Layer when the backing
- * store is **PostgreSQL**.
- *
- * Wraps `kysely`'s `PostgresDialect` over the `pg` driver behind a
- * single XF-canonical class. The implementer's concrete Logical
- * extends this and exposes domain-meaningful methods that compose
- * queries against `this.db`. Transactions via `this.transaction(...)`,
- * one-shot error translation via `this.exec(...)`.
- *
- * The default `translateError` maps Postgres SQLSTATE codes to the
- * typed Exceptions exported from `@xfarch/xf-sql`
- * (`UniqueViolationException`, `ForeignKeyViolationException`,
- * `CheckViolationException`, `NotNullViolationException`,
- * `DeadlockException`) and transport-level errors (`ECONNREFUSED`,
- * `ETIMEDOUT`, …) to `ConnectionException`. The implementer's
- * Business Layer never sees `pg` types.
- *
- * @typeParam Schema  Implementer-defined TypeScript interface mapping
- *                    table names to their column shapes.
- *
- * @example
- * ```ts
- * import { PostgresDatabaseRepository } from '@xfarch/xf-sql-postgres'
- * import { UniqueViolationException } from '@xfarch/xf-sql'
- *
- * interface Schema {
- *   users: { id: number; name: string; email: string; created_at: Date }
- * }
- *
- * export class UsersDb extends PostgresDatabaseRepository<Schema> {
- *   constructor() {
- *     super({
- *       connectionString: process.env.DATABASE_URL!,
- *       pool: { max: 10, idleTimeoutMillis: 30_000 },
- *     })
- *   }
- *   async init()      { await super.init() }       // ← required
- *   async terminate() { await super.terminate() }  // ← required
- *
- *   getUser(id: number) {
- *     return this.exec(() =>
- *       this.db.selectFrom('users').where('id', '=', id).selectAll().executeTakeFirstOrThrow()
- *     )
- *   }
- *
- *   async createUser(input: { name: string; email: string }) {
- *     try {
- *       return await this.exec(() =>
- *         this.db.insertInto('users').values({ ...input, created_at: new Date() }).returningAll().executeTakeFirstOrThrow()
- *       )
- *     } catch (err) {
- *       if (err instanceof UniqueViolationException && err.column === 'email') {
- *         throw new DomainError('Email already registered')
- *       }
- *       throw err
- *     }
- *   }
- * }
- * ```
- */
-export declare abstract class PostgresDatabaseRepository<Schema = unknown> extends TransactionalDatabaseRepository<Schema> {
-    constructor(options: PostgresOptions);
-    /**
-     * Translate `pg` / Kysely driver errors into the typed Exceptions
-     * exported from `@xfarch/xf-sql`. Delegates to
-     * {@link PostgresErrorUtils.translate}.
-     *
-     * Subclasses may override to layer additional mappings on top, but
-     * should `return super.translateError(err)` for unrecognised
-     * errors so the base policy still applies.
-     */
-    protected translateError(err: unknown): unknown;
-}
-//# sourceMappingURL=PostgresDatabaseRepository.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"PostgresDatabaseRepository.d.ts","sourceRoot":"","sources":["../../../../src/repository/base/PostgresDatabaseRepository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,+BAA+B,EAAE,MAAM,gBAAgB,CAAA;AAEhE,OAAO,EAAQ,KAAK,UAAU,EAAE,MAAM,IAAI,CAAA;AAG1C;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,yEAAyE;IACzE,IAAI,CAAC,EAAE,UAAU,CAAA;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,8BAAsB,0BAA0B,CAAC,MAAM,GAAG,OAAO,CAC/D,SAAQ,+BAA+B,CAAC,MAAM,CAAC;gBAEnC,OAAO,EAAE,eAAe;IASpC;;;;;;;;OAQG;cACgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO;CAGzD"}

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

@@ -1,88 +0,0 @@
-import { TransactionalDatabaseRepository } from '@xfarch/xf-sql';
-import { PostgresDialect } from 'kysely';
-import { Pool } from 'pg';
-import { PostgresErrorUtils } from '../utils/PostgresErrorUtils.js';
-/**
- * Ready-to-use Generalization for the Access Layer when the backing
- * store is **PostgreSQL**.
- *
- * Wraps `kysely`'s `PostgresDialect` over the `pg` driver behind a
- * single XF-canonical class. The implementer's concrete Logical
- * extends this and exposes domain-meaningful methods that compose
- * queries against `this.db`. Transactions via `this.transaction(...)`,
- * one-shot error translation via `this.exec(...)`.
- *
- * The default `translateError` maps Postgres SQLSTATE codes to the
- * typed Exceptions exported from `@xfarch/xf-sql`
- * (`UniqueViolationException`, `ForeignKeyViolationException`,
- * `CheckViolationException`, `NotNullViolationException`,
- * `DeadlockException`) and transport-level errors (`ECONNREFUSED`,
- * `ETIMEDOUT`, …) to `ConnectionException`. The implementer's
- * Business Layer never sees `pg` types.
- *
- * @typeParam Schema  Implementer-defined TypeScript interface mapping
- *                    table names to their column shapes.
- *
- * @example
- * ```ts
- * import { PostgresDatabaseRepository } from '@xfarch/xf-sql-postgres'
- * import { UniqueViolationException } from '@xfarch/xf-sql'
- *
- * interface Schema {
- *   users: { id: number; name: string; email: string; created_at: Date }
- * }
- *
- * export class UsersDb extends PostgresDatabaseRepository<Schema> {
- *   constructor() {
- *     super({
- *       connectionString: process.env.DATABASE_URL!,
- *       pool: { max: 10, idleTimeoutMillis: 30_000 },
- *     })
- *   }
- *   async init()      { await super.init() }       // ← required
- *   async terminate() { await super.terminate() }  // ← required
- *
- *   getUser(id: number) {
- *     return this.exec(() =>
- *       this.db.selectFrom('users').where('id', '=', id).selectAll().executeTakeFirstOrThrow()
- *     )
- *   }
- *
- *   async createUser(input: { name: string; email: string }) {
- *     try {
- *       return await this.exec(() =>
- *         this.db.insertInto('users').values({ ...input, created_at: new Date() }).returningAll().executeTakeFirstOrThrow()
- *       )
- *     } catch (err) {
- *       if (err instanceof UniqueViolationException && err.column === 'email') {
- *         throw new DomainError('Email already registered')
- *       }
- *       throw err
- *     }
- *   }
- * }
- * ```
- */
-export class PostgresDatabaseRepository extends TransactionalDatabaseRepository {
-    constructor(options) {
-        const poolConfig = { ...options.pool };
-        if (options.connectionString !== undefined) {
-            poolConfig.connectionString = options.connectionString;
-        }
-        const pool = new Pool(poolConfig);
-        super({ dialect: new PostgresDialect({ pool }) });
-    }
-    /**
-     * Translate `pg` / Kysely driver errors into the typed Exceptions
-     * exported from `@xfarch/xf-sql`. Delegates to
-     * {@link PostgresErrorUtils.translate}.
-     *
-     * Subclasses may override to layer additional mappings on top, but
-     * should `return super.translateError(err)` for unrecognised
-     * errors so the base policy still applies.
-     */
-    translateError(err) {
-        return PostgresErrorUtils.translate(err);
-    }
-}
-//# sourceMappingURL=PostgresDatabaseRepository.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"PostgresDatabaseRepository.js","sourceRoot":"","sources":["../../../../src/repository/base/PostgresDatabaseRepository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,+BAA+B,EAAE,MAAM,gBAAgB,CAAA;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,EAAE,IAAI,EAAmB,MAAM,IAAI,CAAA;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAiBnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,OAAgB,0BACpB,SAAQ,+BAAuC;IAE/C,YAAY,OAAwB;QAClC,MAAM,UAAU,GAAe,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,CAAA;QAClD,IAAI,OAAO,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;YAC3C,UAAU,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAA;QACxD,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,CAAA;QACjC,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,eAAe,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAA;IACnD,CAAC;IAED;;;;;;;;OAQG;IACgB,cAAc,CAAC,GAAY;QAC5C,OAAO,kBAAkB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAA;IAC1C,CAAC;CACF"}