@affordance/pg 0.2.0

package/dist/sql.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The one idiom behind every filtered read in the package: a `where` clause
+ * assembled from a list of AND-ed conditions and a positional values array.
+ * The journal, the dead-letter surface, and the migration candidate query
+ * each read a different table, but they all number their placeholders and
+ * join their conditions the same way — stated once here, so a new filter
+ * cannot number a placeholder wrong.
+ */
+/** A `where` clause under assembly. */
+export interface SqlWhere {
+    /** The AND-ed conditions; push to add one. */
+    readonly conditions: string[];
+    /** The bound values, positionally matching the `$n` placeholders. */
+    readonly values: unknown[];
+    /** Append a value and return its `$n` placeholder. */
+    readonly bind: (value: unknown) => string;
+    /** The conditions joined with ` and ` — the body of the `where` clause. */
+    readonly where: () => string;
+}
+/**
+ * Start a `where` clause. Fixed conditions and their values are the seed —
+ * a seeded condition may spell its own `$n` as long as it matches the
+ * value's position — and optional conditions are pushed with placeholders
+ * from `bind`.
+ */
+export declare const sqlWhere: (conditions?: string[], values?: unknown[]) => SqlWhere;

package/dist/sql.js

@@ -0,0 +1,21 @@
+/**
+ * The one idiom behind every filtered read in the package: a `where` clause
+ * assembled from a list of AND-ed conditions and a positional values array.
+ * The journal, the dead-letter surface, and the migration candidate query
+ * each read a different table, but they all number their placeholders and
+ * join their conditions the same way — stated once here, so a new filter
+ * cannot number a placeholder wrong.
+ */
+/**
+ * Start a `where` clause. Fixed conditions and their values are the seed —
+ * a seeded condition may spell its own `$n` as long as it matches the
+ * value's position — and optional conditions are pushed with placeholders
+ * from `bind`.
+ */
+export const sqlWhere = (conditions = [], values = []) => ({
+    conditions,
+    values,
+    bind: (value) => `$${values.push(value)}`,
+    where: () => conditions.join(' and '),
+});
+//# sourceMappingURL=sql.js.map

package/dist/sql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.js","sourceRoot":"","sources":["../src/sql.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAcH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,aAAuB,EAAE,EACzB,SAAoB,EAAE,EACZ,EAAE,CAAC,CAAC;IACd,UAAU;IACV,MAAM;IACN,IAAI,EAAE,CAAC,KAAc,EAAU,EAAE,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;IAC1D,KAAK,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;CACtC,CAAC,CAAA","sourcesContent":["/**\n * The one idiom behind every filtered read in the package: a `where` clause\n * assembled from a list of AND-ed conditions and a positional values array.\n * The journal, the dead-letter surface, and the migration candidate query\n * each read a different table, but they all number their placeholders and\n * join their conditions the same way — stated once here, so a new filter\n * cannot number a placeholder wrong.\n */\n\n/** A `where` clause under assembly. */\nexport interface SqlWhere {\n  /** The AND-ed conditions; push to add one. */\n  readonly conditions: string[]\n  /** The bound values, positionally matching the `$n` placeholders. */\n  readonly values: unknown[]\n  /** Append a value and return its `$n` placeholder. */\n  readonly bind: (value: unknown) => string\n  /** The conditions joined with ` and ` — the body of the `where` clause. */\n  readonly where: () => string\n}\n\n/**\n * Start a `where` clause. Fixed conditions and their values are the seed —\n * a seeded condition may spell its own `$n` as long as it matches the\n * value's position — and optional conditions are pushed with placeholders\n * from `bind`.\n */\nexport const sqlWhere = (\n  conditions: string[] = [],\n  values: unknown[] = [],\n): SqlWhere => ({\n  conditions,\n  values,\n  bind: (value: unknown): string => `$${values.push(value)}`,\n  where: () => conditions.join(' and '),\n})\n"]}

package/dist/storage.d.ts

@@ -0,0 +1,12 @@
+import type { EngineStorage } from '@affordance/core';
+import type { DatabaseAccess, Transaction } from './queryable.js';
+export interface PgStorageOptions<TCommit> {
+    readonly db: DatabaseAccess;
+    /** Bind application repositories to the framework's open commit transaction. */
+    readonly commitContext: (tx: Transaction) => TCommit;
+}
+export declare function createPgStorage<TCommit>(options: PgStorageOptions<TCommit>): EngineStorage<TCommit>;
+export declare function createPgStorage(options: {
+    readonly db: DatabaseAccess;
+    readonly commitContext?: undefined;
+}): EngineStorage<Transaction>;

package/dist/storage.js

@@ -0,0 +1,40 @@
+import { correlationsFor, lookupCorrelation, registerCorrelation, } from './correlation.js';
+import { claimDelivery, readDeadLetters, settle } from './delivery.js';
+import { pgLifecyclePort } from './execution.js';
+import { readJournal } from './journal.js';
+import { listCases } from './listing.js';
+import { findCandidates, hasCompleted } from './migration.js';
+import { queryableOf } from './queryable.js';
+import { insertStoredCase, selectCaseUntyped } from './store.js';
+export function createPgStorage(options) {
+    return options.commitContext === undefined
+        ? bindStorage(options.db, (tx) => tx)
+        : bindStorage(options.db, options.commitContext);
+}
+const bindStorage = (db, context) => {
+    const q = queryableOf(db);
+    return {
+        cases: {
+            create: (type, state) => insertStoredCase(q, type, state),
+            get: (id) => selectCaseUntyped(q, id),
+            list: (options) => listCases(q, options),
+        },
+        execution: pgLifecyclePort(db, context),
+        journal: { read: (id, filter) => readJournal(q, id, filter) },
+        correlations: {
+            register: (registration) => registerCorrelation(q, registration),
+            lookup: (system, externalId) => lookupCorrelation(q, system, externalId),
+            list: (id, scope) => correlationsFor(q, id, scope),
+        },
+        deliveries: {
+            acquire: (event, key, reopenable) => claimDelivery(q, event, key, reopenable),
+            settle: (id, outcome) => settle(q, id, outcome),
+            deadLetters: (filter) => readDeadLetters(q, filter),
+        },
+        migrations: {
+            candidates: (type, marker, options, cursor, limit) => findCandidates(q, type, marker, options, cursor, limit),
+            hasCompleted: (id, marker) => hasCompleted(q, id, marker),
+        },
+    };
+};
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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","sourcesContent":["import type { EngineStorage } from '@affordance/core'\nimport {\n  correlationsFor,\n  lookupCorrelation,\n  registerCorrelation,\n} from './correlation.js'\nimport { claimDelivery, readDeadLetters, settle } from './delivery.js'\nimport { pgLifecyclePort } from './execution.js'\nimport { readJournal } from './journal.js'\nimport { listCases } from './listing.js'\nimport { findCandidates, hasCompleted } from './migration.js'\nimport type { DatabaseAccess, Transaction } from './queryable.js'\nimport { queryableOf } from './queryable.js'\nimport { insertStoredCase, selectCaseUntyped } from './store.js'\n\nexport interface PgStorageOptions<TCommit> {\n  readonly db: DatabaseAccess\n  /** Bind application repositories to the framework's open commit transaction. */\n  readonly commitContext: (tx: Transaction) => TCommit\n}\n\nexport function createPgStorage<TCommit>(\n  options: PgStorageOptions<TCommit>,\n): EngineStorage<TCommit>\nexport function createPgStorage(options: {\n  readonly db: DatabaseAccess\n  readonly commitContext?: undefined\n}): EngineStorage<Transaction>\nexport function createPgStorage<TCommit>(options: {\n  readonly db: DatabaseAccess\n  readonly commitContext?: (tx: Transaction) => TCommit\n}) {\n  return options.commitContext === undefined\n    ? bindStorage(options.db, (tx: Transaction) => tx)\n    : bindStorage(options.db, options.commitContext)\n}\n\nconst bindStorage = <TCommit>(\n  db: DatabaseAccess,\n  context: (tx: Transaction) => TCommit,\n): EngineStorage<TCommit> => {\n  const q = queryableOf(db)\n  return {\n    cases: {\n      create: (type, state) => insertStoredCase(q, type, state),\n      get: (id) => selectCaseUntyped(q, id),\n      list: (options) => listCases(q, options),\n    },\n    execution: pgLifecyclePort(db, context),\n    journal: { read: (id, filter) => readJournal(q, id, filter) },\n    correlations: {\n      register: (registration) => registerCorrelation(q, registration),\n      lookup: (system, externalId) => lookupCorrelation(q, system, externalId),\n      list: (id, scope) => correlationsFor(q, id, scope),\n    },\n    deliveries: {\n      acquire: (event, key, reopenable) =>\n        claimDelivery(q, event, key, reopenable),\n      settle: (id, outcome) => settle(q, id, outcome),\n      deadLetters: (filter) => readDeadLetters(q, filter),\n    },\n    migrations: {\n      candidates: (type, marker, options, cursor, limit) =>\n        findCandidates(q, type, marker, options, cursor, limit),\n      hasCompleted: (id, marker) => hasCompleted(q, id, marker),\n    },\n  }\n}\n"]}

package/dist/store.d.ts

@@ -0,0 +1,53 @@
+import type { CaseHandle, Dormancy } from '@affordance/core';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Queryable, Transaction } from './queryable.js';
+/** Row shape of `affordance.cases` (int8 arrives as text from the pg driver). */
+export type CaseRow = {
+    id: string;
+    case_type: string;
+    state: unknown;
+    seq: string | number;
+    ended_at: Date | null;
+    created_at: Date;
+    updated_at: Date;
+};
+export declare const toHandle: <State>(row: CaseRow, state: State) => CaseHandle<State>;
+/**
+ * `createCase` against an explicit {@link Queryable} — the shared-transaction
+ * seam. State is stringified explicitly so array-rooted documents are stored
+ * as jsonb rather than misread as Postgres arrays.
+ */
+export declare const insertCase: <S extends StandardSchemaV1>(db: Queryable, caseTypeName: string, stateSchema: S, initialState: StandardSchemaV1.InferInput<S>) => Promise<CaseHandle<StandardSchemaV1.InferOutput<S>>>;
+export declare const insertStoredCase: <TState>(db: Queryable, caseTypeName: string, state: TState) => Promise<CaseHandle<TState>>;
+/** `loadCase` against an explicit {@link Queryable} — the shared-transaction seam. */
+export declare const selectCase: <S extends StandardSchemaV1>(db: Queryable, id: string, stateSchema: S) => Promise<CaseHandle<StandardSchemaV1.InferOutput<S>>>;
+/**
+ * Load a Case by id with the stored state **unvalidated** (`unknown`).
+ *
+ * Additive export for the engine: the engine learns which state
+ * schema applies only *from* the loaded row — `case_type` names the
+ * registered case type — so it must read the row before it can validate.
+ * Every other caller should prefer {@link selectCase} / `loadCase`, which
+ * validate; whoever consumes this handle owns validating `state` against the
+ * type's schema before trusting it.
+ */
+export declare const selectCaseUntyped: (db: Queryable, id: string) => Promise<CaseHandle<unknown>>;
+/**
+ * Load a Case by id **for update** — `select … for update`, so the row lock is
+ * held until the calling transaction ends.
+ *
+ * This is the execution lifecycle's serialization point: the claim and the
+ * commit both take the case row's lock first, which is what makes the
+ * one-in-flight-execution check (and an expired claim's takeover) a decision
+ * no two transactions can make concurrently.
+ */
+export declare const selectCaseForUpdate: (tx: Transaction, id: string) => Promise<CaseHandle<unknown>>;
+/** The dormancy transition a committing Execution applies to the case row (`end()` / `reopen()`). */
+/**
+ * Write the next Case State, bump `seq`, and apply the Execution's dormancy
+ * transition, if any: `'ended'` stamps `ended_at`, `'reopened'` clears it,
+ * `null` leaves it exactly as it was. The state document is **not** validated
+ * here — the execution lifecycle validates the handler's return against the
+ * case type's schema before calling this, and reports a failure there.
+ */
+export declare const updateCaseState: (tx: Transaction, id: string, state: unknown, dormancy?: Dormancy | null) => Promise<CaseHandle<unknown>>;

package/dist/store.js

@@ -0,0 +1,100 @@
+import { CaseNotFoundError } from '@affordance/core';
+import { mintId, validateAgainstSchema } from '@affordance/core/storage';
+import { FRAMEWORK_SCHEMA } from './bootstrap.js';
+const CASES = `${FRAMEWORK_SCHEMA}.cases`;
+const CASE_COLUMNS = 'id, case_type, state, seq, ended_at, created_at, updated_at';
+export const toHandle = (row, state) => ({
+    id: row.id,
+    caseTypeName: row.case_type,
+    state,
+    // Number() is safe: seq counts executions of one human-paced case and will
+    // never approach 2^53.
+    seq: Number(row.seq),
+    endedAt: row.ended_at,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+});
+/**
+ * `createCase` against an explicit {@link Queryable} — the shared-transaction
+ * seam. State is stringified explicitly so array-rooted documents are stored
+ * as jsonb rather than misread as Postgres arrays.
+ */
+export const insertCase = async (db, caseTypeName, stateSchema, initialState) => {
+    const state = await validateAgainstSchema(stateSchema, initialState, 'initial state');
+    return insertStoredCase(db, caseTypeName, state);
+};
+export const insertStoredCase = async (db, caseTypeName, state) => {
+    const id = mintId('case');
+    const { rows } = await db.query(`insert into ${CASES} (id, case_type, state)
+     values ($1, $2, $3::jsonb)
+     returning ${CASE_COLUMNS}`, [id, caseTypeName, JSON.stringify(state)]);
+    const row = rows[0];
+    if (!row)
+        throw new Error(`insert into ${CASES} returned no row`);
+    return toHandle(row, state);
+};
+/** `loadCase` against an explicit {@link Queryable} — the shared-transaction seam. */
+export const selectCase = async (db, id, stateSchema) => {
+    const handle = await selectCaseUntyped(db, id);
+    const state = await validateAgainstSchema(stateSchema, handle.state, 'stored state');
+    return { ...handle, state };
+};
+/**
+ * Load a Case by id with the stored state **unvalidated** (`unknown`).
+ *
+ * Additive export for the engine: the engine learns which state
+ * schema applies only *from* the loaded row — `case_type` names the
+ * registered case type — so it must read the row before it can validate.
+ * Every other caller should prefer {@link selectCase} / `loadCase`, which
+ * validate; whoever consumes this handle owns validating `state` against the
+ * type's schema before trusting it.
+ */
+export const selectCaseUntyped = async (db, id) => {
+    const { rows } = await db.query(`select ${CASE_COLUMNS} from ${CASES} where id = $1`, [id]);
+    const row = rows[0];
+    if (!row)
+        throw new CaseNotFoundError(id);
+    return toHandle(row, row.state);
+};
+/**
+ * Load a Case by id **for update** — `select … for update`, so the row lock is
+ * held until the calling transaction ends.
+ *
+ * This is the execution lifecycle's serialization point: the claim and the
+ * commit both take the case row's lock first, which is what makes the
+ * one-in-flight-execution check (and an expired claim's takeover) a decision
+ * no two transactions can make concurrently.
+ */
+export const selectCaseForUpdate = async (tx, id) => {
+    const { rows } = await tx.query(`select ${CASE_COLUMNS} from ${CASES} where id = $1 for update`, [id]);
+    const row = rows[0];
+    if (!row)
+        throw new CaseNotFoundError(id);
+    return toHandle(row, row.state);
+};
+/** The dormancy transition a committing Execution applies to the case row (`end()` / `reopen()`). */
+/**
+ * Write the next Case State, bump `seq`, and apply the Execution's dormancy
+ * transition, if any: `'ended'` stamps `ended_at`, `'reopened'` clears it,
+ * `null` leaves it exactly as it was. The state document is **not** validated
+ * here — the execution lifecycle validates the handler's return against the
+ * case type's schema before calling this, and reports a failure there.
+ */
+export const updateCaseState = async (tx, id, state, dormancy = null) => {
+    const { rows } = await tx.query(`update ${CASES}
+     set state = $2::jsonb,
+         seq = seq + 1,
+         ended_at = case
+           when $3::text = 'ended' then now()
+           when $3::text = 'reopened' then null
+           else ended_at
+         end,
+         updated_at = now()
+     where id = $1
+     returning ${CASE_COLUMNS}`, [id, JSON.stringify(state), dormancy]);
+    const row = rows[0];
+    if (!row)
+        throw new CaseNotFoundError(id);
+    return toHandle(row, row.state);
+};
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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","sourcesContent":["import type { CaseHandle, Dormancy } from '@affordance/core'\nimport { CaseNotFoundError } from '@affordance/core'\nimport { mintId, validateAgainstSchema } from '@affordance/core/storage'\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\nimport { FRAMEWORK_SCHEMA } from './bootstrap.js'\nimport type { Queryable, Transaction } from './queryable.js'\n\nconst CASES = `${FRAMEWORK_SCHEMA}.cases`\nconst CASE_COLUMNS =\n  'id, case_type, state, seq, ended_at, created_at, updated_at'\n\n/** Row shape of `affordance.cases` (int8 arrives as text from the pg driver). */\nexport type CaseRow = {\n  id: string\n  case_type: string\n  state: unknown\n  seq: string | number\n  ended_at: Date | null\n  created_at: Date\n  updated_at: Date\n}\n\nexport const toHandle = <State>(\n  row: CaseRow,\n  state: State,\n): CaseHandle<State> => ({\n  id: row.id,\n  caseTypeName: row.case_type,\n  state,\n  // Number() is safe: seq counts executions of one human-paced case and will\n  // never approach 2^53.\n  seq: Number(row.seq),\n  endedAt: row.ended_at,\n  createdAt: row.created_at,\n  updatedAt: row.updated_at,\n})\n\n/**\n * `createCase` against an explicit {@link Queryable} — the shared-transaction\n * seam. State is stringified explicitly so array-rooted documents are stored\n * as jsonb rather than misread as Postgres arrays.\n */\nexport const insertCase = async <S extends StandardSchemaV1>(\n  db: Queryable,\n  caseTypeName: string,\n  stateSchema: S,\n  initialState: StandardSchemaV1.InferInput<S>,\n): Promise<CaseHandle<StandardSchemaV1.InferOutput<S>>> => {\n  const state = await validateAgainstSchema(\n    stateSchema,\n    initialState,\n    'initial state',\n  )\n  return insertStoredCase(db, caseTypeName, state)\n}\n\nexport const insertStoredCase = async <TState>(\n  db: Queryable,\n  caseTypeName: string,\n  state: TState,\n): Promise<CaseHandle<TState>> => {\n  const id = mintId('case')\n  const { rows } = await db.query<CaseRow>(\n    `insert into ${CASES} (id, case_type, state)\n     values ($1, $2, $3::jsonb)\n     returning ${CASE_COLUMNS}`,\n    [id, caseTypeName, JSON.stringify(state)],\n  )\n  const row = rows[0]\n  if (!row) throw new Error(`insert into ${CASES} returned no row`)\n  return toHandle(row, state)\n}\n\n/** `loadCase` against an explicit {@link Queryable} — the shared-transaction seam. */\nexport const selectCase = async <S extends StandardSchemaV1>(\n  db: Queryable,\n  id: string,\n  stateSchema: S,\n): Promise<CaseHandle<StandardSchemaV1.InferOutput<S>>> => {\n  const handle = await selectCaseUntyped(db, id)\n  const state = await validateAgainstSchema(\n    stateSchema,\n    handle.state,\n    'stored state',\n  )\n  return { ...handle, state }\n}\n\n/**\n * Load a Case by id with the stored state **unvalidated** (`unknown`).\n *\n * Additive export for the engine: the engine learns which state\n * schema applies only *from* the loaded row — `case_type` names the\n * registered case type — so it must read the row before it can validate.\n * Every other caller should prefer {@link selectCase} / `loadCase`, which\n * validate; whoever consumes this handle owns validating `state` against the\n * type's schema before trusting it.\n */\nexport const selectCaseUntyped = async (\n  db: Queryable,\n  id: string,\n): Promise<CaseHandle<unknown>> => {\n  const { rows } = await db.query<CaseRow>(\n    `select ${CASE_COLUMNS} from ${CASES} where id = $1`,\n    [id],\n  )\n  const row = rows[0]\n  if (!row) throw new CaseNotFoundError(id)\n  return toHandle(row, row.state)\n}\n\n/**\n * Load a Case by id **for update** — `select … for update`, so the row lock is\n * held until the calling transaction ends.\n *\n * This is the execution lifecycle's serialization point: the claim and the\n * commit both take the case row's lock first, which is what makes the\n * one-in-flight-execution check (and an expired claim's takeover) a decision\n * no two transactions can make concurrently.\n */\nexport const selectCaseForUpdate = async (\n  tx: Transaction,\n  id: string,\n): Promise<CaseHandle<unknown>> => {\n  const { rows } = await tx.query<CaseRow>(\n    `select ${CASE_COLUMNS} from ${CASES} where id = $1 for update`,\n    [id],\n  )\n  const row = rows[0]\n  if (!row) throw new CaseNotFoundError(id)\n  return toHandle(row, row.state)\n}\n\n/** The dormancy transition a committing Execution applies to the case row (`end()` / `reopen()`). */\n\n/**\n * Write the next Case State, bump `seq`, and apply the Execution's dormancy\n * transition, if any: `'ended'` stamps `ended_at`, `'reopened'` clears it,\n * `null` leaves it exactly as it was. The state document is **not** validated\n * here — the execution lifecycle validates the handler's return against the\n * case type's schema before calling this, and reports a failure there.\n */\nexport const updateCaseState = async (\n  tx: Transaction,\n  id: string,\n  state: unknown,\n  dormancy: Dormancy | null = null,\n): Promise<CaseHandle<unknown>> => {\n  const { rows } = await tx.query<CaseRow>(\n    `update ${CASES}\n     set state = $2::jsonb,\n         seq = seq + 1,\n         ended_at = case\n           when $3::text = 'ended' then now()\n           when $3::text = 'reopened' then null\n           else ended_at\n         end,\n         updated_at = now()\n     where id = $1\n     returning ${CASE_COLUMNS}`,\n    [id, JSON.stringify(state), dormancy],\n  )\n  const row = rows[0]\n  if (!row) throw new CaseNotFoundError(id)\n  return toHandle(row, row.state)\n}\n"]}

package/dist/transaction.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The transaction seam.
+ *
+ * The claim and the commit are each one short transaction; the handler runs
+ * between them, outside both — so no transaction is ever held open
+ * across a handler's external calls. `withTransaction` is how the execution
+ * lifecycle gets one, and it is also what a handler's `ctx.onCommit` writes
+ * ride along inside.
+ */
+import type { DatabaseAccess, Transaction } from './queryable.js';
+/**
+ * Run `fn` inside a transaction and hand it the handle to use — a checked-out
+ * client when the caller brought a pool, the client itself when they brought
+ * one (issuing `begin` on a *pool* would put each statement on a different
+ * connection, so the distinction is not cosmetic). Which case applies is the
+ * caller's declaration — {@link DatabaseAccess} — never sniffed from the
+ * object.
+ *
+ * Commits on return, rolls back on throw, and always releases what it
+ * checked out. A rollback that itself fails is swallowed: the original error
+ * is what the caller needs, and a connection too broken to roll back is
+ * discarded by the pool anyway.
+ */
+export declare const withTransaction: <T>(db: DatabaseAccess, fn: (tx: Transaction) => Promise<T>) => Promise<T>;

package/dist/transaction.js

@@ -0,0 +1,50 @@
+/**
+ * The transaction seam.
+ *
+ * The claim and the commit are each one short transaction; the handler runs
+ * between them, outside both — so no transaction is ever held open
+ * across a handler's external calls. `withTransaction` is how the execution
+ * lifecycle gets one, and it is also what a handler's `ctx.onCommit` writes
+ * ride along inside.
+ */
+import { withClient } from './queryable.js';
+/**
+ * Run `fn` inside a transaction and hand it the handle to use — a checked-out
+ * client when the caller brought a pool, the client itself when they brought
+ * one (issuing `begin` on a *pool* would put each statement on a different
+ * connection, so the distinction is not cosmetic). Which case applies is the
+ * caller's declaration — {@link DatabaseAccess} — never sniffed from the
+ * object.
+ *
+ * Commits on return, rolls back on throw, and always releases what it
+ * checked out. A rollback that itself fails is swallowed: the original error
+ * is what the caller needs, and a connection too broken to roll back is
+ * discarded by the pool anyway.
+ */
+export const withTransaction = async (db, fn) => {
+    if (!('pool' in db))
+        return withClient(db.client, () => runTransaction(db.client, fn));
+    const client = await db.pool.connect();
+    try {
+        return await runTransaction(client, fn);
+    }
+    finally {
+        client.release();
+    }
+};
+const runTransaction = async (handle, fn) => {
+    // The one place the brand is applied: past the `begin` below, this handle
+    // really is inside a transaction.
+    const tx = handle;
+    await tx.query('begin');
+    try {
+        const result = await fn(tx);
+        await tx.query('commit');
+        return result;
+    }
+    catch (error) {
+        await tx.query('rollback').catch(() => undefined);
+        throw error;
+    }
+};
+//# sourceMappingURL=transaction.js.map

package/dist/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAClC,EAAkB,EAClB,EAAmC,EACvB,EAAE;IACd,IAAI,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC;QACjB,OAAO,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAA;IACnE,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAA;IACtC,IAAI,CAAC;QACH,OAAO,MAAM,cAAc,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IACzC,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,OAAO,EAAE,CAAA;IAClB,CAAC;AACH,CAAC,CAAA;AAED,MAAM,cAAc,GAAG,KAAK,EAC1B,MAAiB,EACjB,EAAmC,EACvB,EAAE;IACd,0EAA0E;IAC1E,kCAAkC;IAClC,MAAM,EAAE,GAAG,MAAqB,CAAA;IAChC,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IACvB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,CAAC,CAAA;QAC3B,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;QACxB,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QACjD,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC,CAAA","sourcesContent":["/**\n * The transaction seam.\n *\n * The claim and the commit are each one short transaction; the handler runs\n * between them, outside both — so no transaction is ever held open\n * across a handler's external calls. `withTransaction` is how the execution\n * lifecycle gets one, and it is also what a handler's `ctx.onCommit` writes\n * ride along inside.\n */\n\nimport type { DatabaseAccess, Queryable, Transaction } from './queryable.js'\nimport { withClient } from './queryable.js'\n\n/**\n * Run `fn` inside a transaction and hand it the handle to use — a checked-out\n * client when the caller brought a pool, the client itself when they brought\n * one (issuing `begin` on a *pool* would put each statement on a different\n * connection, so the distinction is not cosmetic). Which case applies is the\n * caller's declaration — {@link DatabaseAccess} — never sniffed from the\n * object.\n *\n * Commits on return, rolls back on throw, and always releases what it\n * checked out. A rollback that itself fails is swallowed: the original error\n * is what the caller needs, and a connection too broken to roll back is\n * discarded by the pool anyway.\n */\nexport const withTransaction = async <T>(\n  db: DatabaseAccess,\n  fn: (tx: Transaction) => Promise<T>,\n): Promise<T> => {\n  if (!('pool' in db))\n    return withClient(db.client, () => runTransaction(db.client, fn))\n  const client = await db.pool.connect()\n  try {\n    return await runTransaction(client, fn)\n  } finally {\n    client.release()\n  }\n}\n\nconst runTransaction = async <T>(\n  handle: Queryable,\n  fn: (tx: Transaction) => Promise<T>,\n): Promise<T> => {\n  // The one place the brand is applied: past the `begin` below, this handle\n  // really is inside a transaction.\n  const tx = handle as Transaction\n  await tx.query('begin')\n  try {\n    const result = await fn(tx)\n    await tx.query('commit')\n    return result\n  } catch (error) {\n    await tx.query('rollback').catch(() => undefined)\n    throw error\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@affordance/pg",
+  "version": "0.2.0",
+  "author": "Mochicode LLC (https://mochicode.com)",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0",
+    "@types/pg": "^8.11.10",
+    "@affordance/core": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.7.2",
+    "vitest": "^3.2.0",
+    "pg": "^8.13.1",
+    "zod": "^4.4.3",
+    "@affordance/testkit": "0.0.0"
+  },
+  "description": "Postgres storage and transactional execution for Affordance.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mochicodecom/affordance.git",
+    "directory": "packages/pg"
+  },
+  "homepage": "https://github.com/mochicodecom/affordance#readme",
+  "bugs": {
+    "url": "https://github.com/mochicodecom/affordance/issues"
+  },
+  "keywords": [
+    "affordance",
+    "case-management",
+    "typescript",
+    "postgres"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "node ../../scripts/build-package.mjs"
+  }
+}