@kronos-ts/postgres 0.1.0

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@kronos-ts/postgres",
+  "version": "0.1.0",
+  "description": "PostgreSQL extension for Kronos — event store and snapshot store adapters.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "author": "Theo Emanuelsson",
+  "homepage": "https://github.com/KronosDB/kronos-ts/tree/main/packages/extensions/postgres#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KronosDB/kronos-ts.git",
+    "directory": "packages/extensions/postgres"
+  },
+  "bugs": {
+    "url": "https://github.com/KronosDB/kronos-ts/issues"
+  },
+  "keywords": [
+    "kronos",
+    "event-sourcing",
+    "cqrs",
+    "dcb",
+    "typescript",
+    "postgres",
+    "postgresql"
+  ],
+  "sideEffects": false,
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./adapters/pg": "./src/adapters/pg.ts",
+    "./adapters/postgres": "./src/adapters/postgres.ts",
+    "./adapters/bun-sql": "./src/adapters/bun-sql.ts"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/__tests__",
+    "!src/**/*.test.ts",
+    "!src/**/*.bench.ts"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "publishConfig": {
+    "access": "public",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "./adapters/pg": {
+        "types": "./dist/adapters/pg.d.ts",
+        "default": "./dist/adapters/pg.js"
+      },
+      "./adapters/postgres": {
+        "types": "./dist/adapters/postgres.d.ts",
+        "default": "./dist/adapters/postgres.js"
+      },
+      "./adapters/bun-sql": {
+        "types": "./dist/adapters/bun-sql.d.ts",
+        "default": "./dist/adapters/bun-sql.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@kronos-ts/common": "workspace:*",
+    "@kronos-ts/app": "workspace:*",
+    "@kronos-ts/eventsourcing": "workspace:*",
+    "@kronos-ts/messaging": "workspace:*"
+  },
+  "peerDependencies": {
+    "pg": ">=8.0.0",
+    "postgres": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    },
+    "postgres": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "pg": "^8.20.0",
+    "@types/pg": "^8.11.0",
+    "postgres": "^3.4.9",
+    "testcontainers": "^11.14.0"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,104 @@
+/**
+ * Driver-agnostic adapter contract for @kronos-ts/postgres.
+ *
+ * Per D-12.05 the package itself has zero direct dependency on any specific
+ * Postgres client library. Engine code (Plan 04) talks to this interface;
+ * adapter implementations (pg, postgres.js, Bun.sql) live under
+ * `./adapters/*` and are imported via package sub-path exports (D-12.08).
+ *
+ * Capability coverage per D-12.07:
+ *   - query execution (parameterised)         -> query / queryOne
+ *   - transactions with isolation level       -> transaction(isolationLevel, fn)
+ *   - LISTEN-style subscription               -> listen(channel, onNotification)
+ *   - lifecycle                               -> connect / disconnect
+ *
+ * Error contract per D-12.12: SQLSTATE on thrown errors as `.code` (string).
+ * Adapter implementations MUST NOT swallow / rewrap SQLSTATE-bearing errors
+ * — the engine relies on `isDcbViolation(err)` reading `err.code === "KR001"`.
+ */
+
+/**
+ * Postgres isolation levels the engine actually emits. SQL string values are
+ * the verbatim Postgres syntax used after `SET TRANSACTION ISOLATION LEVEL`,
+ * so adapters can interpolate directly without a lookup table.
+ */
+export const IsolationLevel = {
+  READ_COMMITTED: "READ COMMITTED",
+  REPEATABLE_READ: "REPEATABLE READ",
+  SERIALIZABLE: "SERIALIZABLE",
+} as const
+export type IsolationLevel = (typeof IsolationLevel)[keyof typeof IsolationLevel]
+
+/** Plain row shape returned by query/queryOne. Adapter implementations cast
+ *  driver-specific row objects to this. */
+export type QueryRow = Record<string, unknown>
+
+/**
+ * Active in-transaction handle. Pinned to a single underlying connection so
+ * statements never interleave with sibling pool traffic. Intentionally NO
+ * nested-transaction method — Plan 04's engine does not need it and savepoints
+ * would invite confusion about which level a SQLSTATE error propagates from.
+ */
+export interface PostgresAdapterTransaction {
+  query<R extends QueryRow = QueryRow>(sql: string, params?: unknown[]): Promise<R[]>
+}
+
+/** Handle to a live LISTEN subscription. unlisten() unregisters + releases
+ *  the dedicated connection (if any). */
+export interface ListenSubscription {
+  unlisten(): Promise<void>
+}
+
+/**
+ * The single interface the engine layer (Plan 04+) consumes. All concurrency
+ * (pool sizing, idle eviction, reconnect) lives below this seam — the engine
+ * code MUST NOT know about pools.
+ */
+export interface PostgresAdapter {
+  /**
+   * Run a parameterised SQL statement on a pool-borrowed connection.
+   * Returns rows; empty array if none. Thrown errors carry SQLSTATE on
+   * `.code` unchanged so `isDcbViolation(err)` works at any call site.
+   */
+  query<R extends QueryRow = QueryRow>(sql: string, params?: unknown[]): Promise<R[]>
+
+  /**
+   * Convenience for single-row queries. Returns `null` if zero rows.
+   * Throws if more than one row is returned (caller bug — use query()).
+   */
+  queryOne<R extends QueryRow = QueryRow>(sql: string, params?: unknown[]): Promise<R | null>
+
+  /**
+   * Open a transaction at the given isolation level, run `fn` against a
+   * pinned-connection handle, and COMMIT on resolution or ROLLBACK on
+   * rejection. If `fn` throws, the original error is re-thrown after
+   * ROLLBACK; rollback failures do NOT mask the original.
+   *
+   * The framework's AppendTransaction has a synchronous `rollback(): void`
+   * (see packages/eventsourcing/src/event-storage-engine.ts) — the
+   * implementation translates that into a fire-and-forget reject inside
+   * this method's promise, NOT an awaited rollback round-trip.
+   */
+  transaction<T>(
+    isolationLevel: IsolationLevel,
+    fn: (tx: PostgresAdapterTransaction) => Promise<T>,
+  ): Promise<T>
+
+  /**
+   * Subscribe to `LISTEN <channel>` on a dedicated long-lived connection.
+   * Adapter implementations that lack a real LISTEN channel (e.g. Bun.sql
+   * pre-1.x) MAY implement a polling shim — the subscription handle is the
+   * same regardless. Plan 05's streaming open() uses this to wake up
+   * tailers immediately instead of waiting for a poll tick.
+   */
+  listen(
+    channel: string,
+    onNotification: (payload: string | undefined) => void,
+  ): Promise<ListenSubscription>
+
+  /** Initialise pool / verify reachability. Idempotent. */
+  connect(): Promise<void>
+
+  /** Drain pool, close LISTEN connections, release sockets. Idempotent. */
+  disconnect(): Promise<void>
+}

package/src/adapters/bun-sql.ts

@@ -0,0 +1,228 @@
+/**
+ * Bun.sql adapter for @kronos-ts/postgres.
+ *
+ * Import via the sub-path (Bun runtime only):
+ *   import { bunSqlAdapter } from "@kronos-ts/postgres/adapters/bun-sql"
+ *
+ * Requires Bun >= 1.2 for Bun.SQL (sql.transaction()). LISTEN support is
+ * feature-detected; if Bun.SQL lacks native LISTEN on the running version,
+ * the adapter falls back to a 250ms polling shim — slower wake-up but
+ * correct semantics.
+ *
+ * This file uses `globalThis as { Bun?: ... }` access to avoid a hard
+ * compile-time reference to Bun's global, so the package can ship under
+ * Node (where this file would never be imported) without TypeScript
+ * compilation errors. Users importing the sub-path under Node will get
+ * a clear runtime error from the connect() call.
+ */
+
+import type {
+  PostgresAdapter,
+  PostgresAdapterTransaction,
+  ListenSubscription,
+  QueryRow,
+} from "../adapter.js"
+import { IsolationLevel } from "../adapter.js"
+
+export interface BunSqlAdapterConfig {
+  readonly connectionString: string
+}
+
+// Minimal structural type for Bun.SQL we depend on (kept local to avoid
+// a hard dependency on @types/bun).
+interface BunSqlInstance {
+  (template: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>
+  unsafe(text: string, params?: unknown[]): Promise<unknown[]>
+  begin<T>(
+    isolation: string,
+    fn: (sql: BunSqlInstance) => Promise<T>,
+  ): Promise<T>
+  listen?(channel: string, cb: (payload: string) => void): Promise<{ unlisten: () => Promise<void> }>
+  close(): Promise<void>
+  end(): Promise<void>
+}
+
+/**
+ * Bun.SQL surfaces SQLSTATE in `err.errno` (not `err.code`). The adapter
+ * contract (D-12.12) requires SQLSTATE on `.code` so that `isDcbViolation(err)`
+ * works uniformly across all adapters.
+ *
+ * This helper normalises Bun.SQL errors: if `err.code === "ERR_POSTGRES_SERVER_ERROR"`
+ * and `err.errno` is a non-empty string, we copy `errno` to `code` before
+ * re-throwing, giving callers the SQLSTATE they expect on `.code`.
+ */
+/**
+ * Bun.SQL's `.unsafe(text, params)` does not auto-encode JS arrays as Postgres
+ * array literals — single-element arrays get unwrapped to their scalar value
+ * and bound as TEXT, which fails when the column is TEXT[]. We pre-encode any
+ * plain Array param to the canonical `{"v1","v2"}` literal so it round-trips
+ * to TEXT[] / array operators (`@>`, `ANY`) correctly.
+ *
+ * Uint8Array / Buffer are not plain arrays (Array.isArray returns false), so
+ * BYTEA params remain untouched.
+ */
+function encodeArrayParam(arr: unknown[]): string {
+  const escaped = arr.map((v) => {
+    if (v === null || v === undefined) return "NULL"
+    const s = String(v)
+    return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
+  })
+  return `{${escaped.join(",")}}`
+}
+
+function normalizeParams(params: unknown[] | undefined): unknown[] {
+  if (!params) return []
+  return params.map((p) => (Array.isArray(p) ? encodeArrayParam(p) : p))
+}
+
+function normalizeBunSqlError(err: unknown): never {
+  if (
+    typeof err === "object" &&
+    err !== null &&
+    (err as { code?: string }).code === "ERR_POSTGRES_SERVER_ERROR" &&
+    typeof (err as { errno?: unknown }).errno === "string" &&
+    (err as { errno: string }).errno.length > 0
+  ) {
+    ;(err as { code: string }).code = (err as { errno: string }).errno
+  }
+  throw err
+}
+
+interface BunSqlConstructor {
+  new (config: { url: string }): BunSqlInstance
+}
+
+function getBunSql(): BunSqlConstructor {
+  const g = globalThis as { Bun?: { SQL?: BunSqlConstructor } }
+  if (!g.Bun?.SQL) {
+    throw new Error(
+      "bunSqlAdapter requires the Bun runtime with built-in Bun.SQL (>= 1.2). " +
+        "Detected non-Bun runtime — use pgAdapter or postgresAdapter instead.",
+    )
+  }
+  return g.Bun.SQL
+}
+
+export function bunSqlAdapter(config: BunSqlAdapterConfig): PostgresAdapter {
+  let sql: BunSqlInstance | undefined
+  let disconnected = false
+
+  function getInstance(): BunSqlInstance {
+    if (!sql) {
+      const SQL = getBunSql()
+      sql = new SQL({ url: config.connectionString })
+    }
+    return sql
+  }
+
+  return {
+    async connect(): Promise<void> {
+      const inst = getInstance()
+      const rows = await inst.unsafe("SELECT 1 AS ok").catch(normalizeBunSqlError) as Array<{ ok: number }>
+      if (rows[0]?.ok !== 1) {
+        throw new Error("bunSqlAdapter.connect: unexpected health-check response")
+      }
+    },
+
+    async disconnect(): Promise<void> {
+      if (disconnected) return
+      disconnected = true
+      if (sql) {
+        // Bun.SQL exposes both close() and end() — try end() first (graceful
+        // drain), fall back to close() if end is unavailable.
+        try {
+          if (typeof (sql as unknown as { end?: () => Promise<void> }).end === "function") {
+            await (sql as unknown as { end: () => Promise<void> }).end()
+          } else {
+            await sql.close()
+          }
+        } catch {
+          /* ignore disconnect errors */
+        }
+        sql = undefined
+      }
+    },
+
+    async query<R extends QueryRow = QueryRow>(text: string, params?: unknown[]): Promise<R[]> {
+      const inst = getInstance()
+      return inst.unsafe(text, normalizeParams(params)).catch(normalizeBunSqlError) as Promise<R[]>
+    },
+
+    async queryOne<R extends QueryRow = QueryRow>(
+      text: string,
+      params?: unknown[],
+    ): Promise<R | null> {
+      const rows = await this.query<R>(text, params)
+      if (rows.length === 0) return null
+      if (rows.length > 1) {
+        throw new Error(
+          `bunSqlAdapter.queryOne: more than one row returned (got ${rows.length}). Use query() for multi-row results.`,
+        )
+      }
+      return rows[0] ?? null
+    },
+
+    async transaction<T>(
+      isolationLevel: IsolationLevel,
+      fn: (tx: PostgresAdapterTransaction) => Promise<T>,
+    ): Promise<T> {
+      const inst = getInstance()
+      // Bun.SQL.begin(isolation, fn) starts a transaction at the given isolation
+      // level. The callback receives a scoped sql instance pinned to the
+      // underlying connection. SQLSTATE errors from within the transaction are
+      // normalized (errno -> code) via normalizeBunSqlError before propagating.
+      return inst.begin(`ISOLATION LEVEL ${isolationLevel}`, async (txSql) => {
+        const tx: PostgresAdapterTransaction = {
+          async query<R extends QueryRow = QueryRow>(
+            text: string,
+            params?: unknown[],
+          ): Promise<R[]> {
+            return txSql.unsafe(text, normalizeParams(params)).catch(normalizeBunSqlError) as Promise<R[]>
+          },
+        }
+        return fn(tx)
+      }).catch(normalizeBunSqlError)
+    },
+
+    async listen(
+      channel: string,
+      onNotification: (payload: string | undefined) => void,
+    ): Promise<ListenSubscription> {
+      if (!/^[A-Za-z0-9_]+$/.test(channel)) {
+        throw new Error(
+          `bunSqlAdapter.listen: channel name must match /^[A-Za-z0-9_]+$/, got: ${channel}`,
+        )
+      }
+      const inst = getInstance()
+      // Feature-detect native LISTEN
+      if (typeof inst.listen === "function") {
+        const sub = await inst.listen(channel, (p) => onNotification(p || undefined))
+        return {
+          async unlisten() {
+            await sub.unlisten()
+          },
+        }
+      }
+      // Polling fallback for Bun versions without native LISTEN.
+      // The fallback fires the callback on every tick with undefined payload,
+      // which causes the streaming engine to re-poll. This is coarse but
+      // semantically correct — the caller (open() in postgres-event-store.ts)
+      // already falls back to 250ms polling as a safety net, so this shim
+      // merely triggers additional pump cycles.
+      let stopped = false
+      const tick = setInterval(() => {
+        if (stopped) {
+          clearInterval(tick)
+          return
+        }
+        onNotification(undefined)
+      }, 250)
+      return {
+        async unlisten() {
+          stopped = true
+          clearInterval(tick)
+        },
+      }
+    },
+  }
+}

package/src/adapters/pg.ts

@@ -0,0 +1,189 @@
+/**
+ * pg (node-postgres 8.20+) reference adapter for @kronos-ts/postgres.
+ *
+ * Import via the sub-path:
+ *   import { pgAdapter } from "@kronos-ts/postgres/adapters/pg"
+ *
+ * Implements every PostgresAdapter method per the contract in
+ * ../adapter.ts. Pool sizing follows pg defaults; override via the
+ * `poolConfig` field if needed.
+ *
+ * LISTEN uses a dedicated long-lived PoolClient pinned outside the pool
+ * (never released) so notification delivery is not racing pool eviction.
+ * That client is closed by `disconnect()`.
+ */
+
+import { Pool, type PoolClient, type PoolConfig } from "pg"
+import type {
+  PostgresAdapter,
+  PostgresAdapterTransaction,
+  ListenSubscription,
+  QueryRow,
+} from "../adapter.js"
+import { IsolationLevel } from "../adapter.js"
+
+export interface PgAdapterConfig {
+  /** Standard libpq URI: postgresql://user:pass@host:port/db */
+  readonly connectionString: string
+  /** Optional pg.Pool config overrides (max connections, idleTimeoutMillis, etc.). */
+  readonly poolConfig?: Omit<PoolConfig, "connectionString">
+}
+
+interface ListenerSlot {
+  channel: string
+  callback: (payload: string | undefined) => void
+}
+
+export function pgAdapter(config: PgAdapterConfig): PostgresAdapter {
+  let pool: Pool | undefined
+  let listenClient: PoolClient | undefined
+  const listenSlots = new Map<string, Set<ListenerSlot>>()
+  let disconnected = false
+
+  function getPool(): Pool {
+    if (!pool) {
+      pool = new Pool({ connectionString: config.connectionString, ...config.poolConfig })
+      pool.on("error", () => {
+        // Connection-level errors on idle clients are non-fatal for the
+        // adapter; pg removes the bad client from the pool automatically.
+        // Surfacing them would force every consumer to attach a handler.
+      })
+    }
+    return pool
+  }
+
+  async function ensureListenClient(): Promise<PoolClient> {
+    if (listenClient) return listenClient
+    listenClient = await getPool().connect()
+    listenClient.on("notification", (msg) => {
+      const slots = listenSlots.get(msg.channel)
+      if (!slots) return
+      for (const slot of slots) slot.callback(msg.payload)
+    })
+    return listenClient
+  }
+
+  const adapter: PostgresAdapter = {
+    async connect(): Promise<void> {
+      // Force pool creation + a no-op query so connect() actually verifies
+      // reachability. Without this, a bad connection string would only
+      // surface on the first real query.
+      const result = await getPool().query<{ ok: number }>("SELECT 1 AS ok")
+      if (result.rows[0]?.ok !== 1) {
+        throw new Error("pgAdapter.connect(): unexpected health-check response")
+      }
+    },
+
+    async disconnect(): Promise<void> {
+      if (disconnected) return
+      disconnected = true
+      if (listenClient) {
+        try {
+          listenClient.release()
+        } catch {
+          /* ignore — client may already be gone */
+        }
+        listenClient = undefined
+      }
+      if (pool) {
+        await pool.end()
+        pool = undefined
+      }
+    },
+
+    async query<R extends QueryRow = QueryRow>(sql: string, params?: unknown[]): Promise<R[]> {
+      const result = await getPool().query<R>(sql, params as unknown[])
+      return result.rows
+    },
+
+    async queryOne<R extends QueryRow = QueryRow>(
+      sql: string,
+      params?: unknown[],
+    ): Promise<R | null> {
+      const result = await getPool().query<R>(sql, params as unknown[])
+      if (result.rows.length === 0) return null
+      if (result.rows.length > 1) {
+        throw new Error(
+          `pgAdapter.queryOne: more than one row returned (got ${result.rows.length}). ` +
+            `Use query() for multi-row results.`,
+        )
+      }
+      return result.rows[0] ?? null
+    },
+
+    async transaction<T>(
+      isolationLevel: IsolationLevel,
+      fn: (tx: PostgresAdapterTransaction) => Promise<T>,
+    ): Promise<T> {
+      const client = await getPool().connect()
+      try {
+        await client.query(`BEGIN ISOLATION LEVEL ${isolationLevel}`)
+        const tx: PostgresAdapterTransaction = {
+          async query<R extends QueryRow = QueryRow>(
+            sql: string,
+            params?: unknown[],
+          ): Promise<R[]> {
+            const result = await client.query<R>(sql, params as unknown[])
+            return result.rows
+          },
+        }
+        let result: T
+        try {
+          result = await fn(tx)
+        } catch (err) {
+          // ROLLBACK best-effort; preserve the ORIGINAL error.
+          try {
+            await client.query("ROLLBACK")
+          } catch {
+            /* ignore rollback failure — original error matters more */
+          }
+          throw err
+        }
+        await client.query("COMMIT")
+        return result
+      } finally {
+        client.release()
+      }
+    },
+
+    async listen(
+      channel: string,
+      onNotification: (payload: string | undefined) => void,
+    ): Promise<ListenSubscription> {
+      const client = await ensureListenClient()
+      const slot: ListenerSlot = { channel, callback: onNotification }
+      let slots = listenSlots.get(channel)
+      if (!slots) {
+        slots = new Set()
+        listenSlots.set(channel, slots)
+        // Channel identifiers cannot be parameterised in pg's LISTEN — use
+        // a safelist: alphanumerics + underscore only. Anything else is a
+        // SQL-injection risk by definition.
+        if (!/^[A-Za-z0-9_]+$/.test(channel)) {
+          throw new Error(
+            `pgAdapter.listen: channel name must match /^[A-Za-z0-9_]+$/, got: ${channel}`,
+          )
+        }
+        await client.query(`LISTEN ${channel}`)
+      }
+      slots.add(slot)
+      return {
+        async unlisten() {
+          const cur = listenSlots.get(channel)
+          if (!cur) return
+          cur.delete(slot)
+          if (cur.size === 0) {
+            listenSlots.delete(channel)
+            try {
+              await client.query(`UNLISTEN ${channel}`)
+            } catch {
+              /* connection may already be gone */
+            }
+          }
+        },
+      }
+    },
+  }
+
+  return adapter
+}