@relaybus/postgres 0.4.1 → 0.5.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { P as PostgresExecutor, a as PostgresParameter, b as PostgresQueryOptions, c as PostgresRow } from './executor-CfJgktC6.cjs';
-import { RelayBusLogger, EventStore, EventStoreTransactionOptions, AppendEntry, AppendResult, ClaimRequest, ClaimedDelivery, LeaseReference, ErrorInfo, DeliveryQuery, DeliveryRecord, PurgeRequest, PurgeResult, EventStoreStatistics, CloseOptions, RelayBusError } from '@relaybus/core';
+import { P as PostgresExecutor, a as PostgresIsolatedTransactionOptions, b as PostgresParameter, c as PostgresQueryOptions, d as PostgresRow } from './executor-Bt90w33Q.cjs';
+import { RelayBusLogger, EventStore, TransactionIsolationLevel, EventStoreTransactionOptions, AppendEntry, AppendResult, ClaimRequest, ClaimedDelivery, LeaseReference, ErrorInfo, DeliveryQuery, DeliveryRecord, PurgeRequest, PurgeResult, EventStoreStatistics, CloseOptions, RelayBusError } from '@relaybus/core';
 import { PoolClient, Pool, PoolConfig } from 'pg';
 
 interface PgExecutorOptions {
@@ -43,6 +43,11 @@ declare class PgExecutor implements PostgresExecutor<PoolClient> {
      * connection that already keeps this budget only gets `BEGIN`.
      */
     transactionWithBudget<T>(work: (transaction: PoolClient) => Promise<T>, timeoutMs: number): Promise<T>;
+    /**
+     * Like {@link PgExecutor.transactionWithBudget} with `BEGIN ISOLATION LEVEL ...`: the level is set
+     * with the `BEGIN` of the same simple query, before the budget's first statement.
+     */
+    transactionWithIsolation<T>(work: (transaction: PoolClient) => Promise<T>, { isolationLevel, timeoutMs }: PostgresIsolatedTransactionOptions): Promise<T>;
     query(sql: string, parameters: readonly PostgresParameter[], transaction?: PoolClient, options?: PostgresQueryOptions): Promise<readonly PostgresRow[]>;
 }
 
@@ -259,6 +264,14 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
      * `createPostgresSchemaSql()` instead.
      */
     setup(): Promise<void>;
+    /** Every level PostgreSQL has (it runs `read uncommitted` as `read committed`, which the bus does not offer). */
+    readonly isolationLevels: readonly TransactionIsolationLevel[];
+    /**
+     * True for a serialization failure (SQLSTATE `40001`) raised through any executor, including
+     * Prisma's `P2034` and the wrappers of TypeORM and Drizzle; a custom executor can add its own
+     * test with {@link PostgresExecutor.isSerializationFailure}.
+     */
+    isSerializationFailure(error: unknown): boolean;
     /**
      * Runs `work` in a transaction of the executor. With `options.timeoutMs` (from `bus.transaction`)
      * the server holds the transaction to the budget: `statement_timeout`, and for executors with
@@ -266,6 +279,9 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
      * `transaction_timeout`, all scoped to the transaction. An executor with `transactionWithBudget`
      * (`PgExecutor`) sets them with `BEGIN`, so the budget costs no round trip; on a pool the store
      * created they are kept per connection and sent only when the connection does not have them yet.
+     * With `options.isolationLevel` the transaction runs at that level: `PgExecutor` sends it with
+     * `BEGIN ISOLATION LEVEL ...` (no extra round trip), any other executor as `SET TRANSACTION
+     * ISOLATION LEVEL ...` before the budget statement.
      */
     transaction<T>(work: (transaction: TTransaction) => Promise<T>, options?: EventStoreTransactionOptions): Promise<T>;
     /**
@@ -343,5 +359,5 @@ declare class ReconcileFailedError extends RelayBusError {
     readonly code: string;
 }
 
-export { PgExecutor, PostgresEventStore, PostgresExecutor, PostgresParameter, PostgresQueryOptions, PostgresRow, ReconcileFailedError, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };
+export { PgExecutor, PostgresEventStore, PostgresExecutor, PostgresIsolatedTransactionOptions, PostgresParameter, PostgresQueryOptions, PostgresRow, ReconcileFailedError, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };
 export type { PgExecutorOptions, PostgresConnectionOptions, PostgresEventStoreOptions, PostgresEventStoreSettings, PostgresExecutorOptions, PostgresNames, PostgresPoolOptions, PostgresSchemaOptions, PostgresWakeUp };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { P as PostgresExecutor, a as PostgresParameter, b as PostgresQueryOptions, c as PostgresRow } from './executor-CfJgktC6.js';
-import { RelayBusLogger, EventStore, EventStoreTransactionOptions, AppendEntry, AppendResult, ClaimRequest, ClaimedDelivery, LeaseReference, ErrorInfo, DeliveryQuery, DeliveryRecord, PurgeRequest, PurgeResult, EventStoreStatistics, CloseOptions, RelayBusError } from '@relaybus/core';
+import { P as PostgresExecutor, a as PostgresIsolatedTransactionOptions, b as PostgresParameter, c as PostgresQueryOptions, d as PostgresRow } from './executor-Bt90w33Q.js';
+import { RelayBusLogger, EventStore, TransactionIsolationLevel, EventStoreTransactionOptions, AppendEntry, AppendResult, ClaimRequest, ClaimedDelivery, LeaseReference, ErrorInfo, DeliveryQuery, DeliveryRecord, PurgeRequest, PurgeResult, EventStoreStatistics, CloseOptions, RelayBusError } from '@relaybus/core';
 import { PoolClient, Pool, PoolConfig } from 'pg';
 
 interface PgExecutorOptions {
@@ -43,6 +43,11 @@ declare class PgExecutor implements PostgresExecutor<PoolClient> {
      * connection that already keeps this budget only gets `BEGIN`.
      */
     transactionWithBudget<T>(work: (transaction: PoolClient) => Promise<T>, timeoutMs: number): Promise<T>;
+    /**
+     * Like {@link PgExecutor.transactionWithBudget} with `BEGIN ISOLATION LEVEL ...`: the level is set
+     * with the `BEGIN` of the same simple query, before the budget's first statement.
+     */
+    transactionWithIsolation<T>(work: (transaction: PoolClient) => Promise<T>, { isolationLevel, timeoutMs }: PostgresIsolatedTransactionOptions): Promise<T>;
     query(sql: string, parameters: readonly PostgresParameter[], transaction?: PoolClient, options?: PostgresQueryOptions): Promise<readonly PostgresRow[]>;
 }
 
@@ -259,6 +264,14 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
      * `createPostgresSchemaSql()` instead.
      */
     setup(): Promise<void>;
+    /** Every level PostgreSQL has (it runs `read uncommitted` as `read committed`, which the bus does not offer). */
+    readonly isolationLevels: readonly TransactionIsolationLevel[];
+    /**
+     * True for a serialization failure (SQLSTATE `40001`) raised through any executor, including
+     * Prisma's `P2034` and the wrappers of TypeORM and Drizzle; a custom executor can add its own
+     * test with {@link PostgresExecutor.isSerializationFailure}.
+     */
+    isSerializationFailure(error: unknown): boolean;
     /**
      * Runs `work` in a transaction of the executor. With `options.timeoutMs` (from `bus.transaction`)
      * the server holds the transaction to the budget: `statement_timeout`, and for executors with
@@ -266,6 +279,9 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
      * `transaction_timeout`, all scoped to the transaction. An executor with `transactionWithBudget`
      * (`PgExecutor`) sets them with `BEGIN`, so the budget costs no round trip; on a pool the store
      * created they are kept per connection and sent only when the connection does not have them yet.
+     * With `options.isolationLevel` the transaction runs at that level: `PgExecutor` sends it with
+     * `BEGIN ISOLATION LEVEL ...` (no extra round trip), any other executor as `SET TRANSACTION
+     * ISOLATION LEVEL ...` before the budget statement.
      */
     transaction<T>(work: (transaction: TTransaction) => Promise<T>, options?: EventStoreTransactionOptions): Promise<T>;
     /**
@@ -343,5 +359,5 @@ declare class ReconcileFailedError extends RelayBusError {
     readonly code: string;
 }
 
-export { PgExecutor, PostgresEventStore, PostgresExecutor, PostgresParameter, PostgresQueryOptions, PostgresRow, ReconcileFailedError, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };
+export { PgExecutor, PostgresEventStore, PostgresExecutor, PostgresIsolatedTransactionOptions, PostgresParameter, PostgresQueryOptions, PostgresRow, ReconcileFailedError, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };
 export type { PgExecutorOptions, PostgresConnectionOptions, PostgresEventStoreOptions, PostgresEventStoreSettings, PostgresExecutorOptions, PostgresNames, PostgresPoolOptions, PostgresSchemaOptions, PostgresWakeUp };

package/dist/index.js

@@ -1,43 +1,10 @@
+import { isolationKeywords, inIsolatedTransaction } from './chunk-FY65AUUF.js';
+import { SESSION_DEFAULTS_SQL, budgetValue, inBudgetedTransaction, budgetSettingsSql } from './chunk-UDBN4RRV.js';
 import { createHash } from 'crypto';
-import { ConfigurationError, RelayBusError, systemClock } from '@relaybus/core';
+import { ConfigurationError, RelayBusError, TRANSACTION_ISOLATION_LEVELS, systemClock } from '@relaybus/core';
 import { LaneLeaseTokenFormat, HandedOutLedger, PositiveInteger, schedule, OwnerSerializedClaims, LeaseSettlement, CompositeKey, DeliveryLeaseIdentity } from '@relaybus/core/internal';
 import { Client, Pool } from 'pg';
 
-// src/pg-executor.ts
-
-// src/transaction-timeouts.ts
-function budgetSettingsSql({ value, sessionTimeouts, scope }) {
-  const local = scope === "transaction";
-  const statementTimeout = `SELECT set_config('statement_timeout', ${value}, ${local})`;
-  if (!sessionTimeouts) {
-    return statementTimeout;
-  }
-  return `${statementTimeout}, set_config('idle_in_transaction_session_timeout', ${value}, ${local}), CASE WHEN current_setting('server_version_num')::int >= 170000 THEN set_config('transaction_timeout', ${value}, ${local}) END`;
-}
-var SESSION_DEFAULTS_SQL = "SELECT set_config(name, reset_val, false) FROM pg_settings WHERE name IN ('statement_timeout', 'idle_in_transaction_session_timeout', 'transaction_timeout')";
-function budgetValue(timeoutMs) {
-  return `${Math.ceil(timeoutMs)}ms`;
-}
-function inBudgetedTransaction(state, {
-  work,
-  timeoutMs
-}) {
-  const { executor } = state;
-  if (executor.transactionWithBudget !== void 0) {
-    return executor.transactionWithBudget(work, timeoutMs);
-  }
-  const sql = budgetSettingsSql({
-    value: "$1",
-    sessionTimeouts: executor.sessionTimeouts === true,
-    scope: "transaction"
-  });
-  return executor.transaction(async (transaction) => {
-    await state.query({ sql, parameters: [budgetValue(timeoutMs)], transaction });
-    return work(transaction);
-  });
-}
-
-// src/pg-executor.ts
 var FOREIGN_SESSION_ERRORS = /* @__PURE__ */ new Set(["26000", "42P05"]);
 var STATEMENT_NAME_DIGITS = 24;
 var PgExecutor = class {
@@ -67,14 +34,28 @@ var PgExecutor = class {
    * connection that already keeps this budget only gets `BEGIN`.
    */
   transactionWithBudget(work, timeoutMs) {
+    return this.#transaction(work, this.#budgetStart(timeoutMs, "BEGIN"));
+  }
+  /**
+   * Like {@link PgExecutor.transactionWithBudget} with `BEGIN ISOLATION LEVEL ...`: the level is set
+   * with the `BEGIN` of the same simple query, before the budget's first statement.
+   */
+  transactionWithIsolation(work, { isolationLevel, timeoutMs }) {
+    return this.#transaction(
+      work,
+      this.#budgetStart(timeoutMs, `BEGIN ISOLATION LEVEL ${isolationKeywords(isolationLevel)}`)
+    );
+  }
+  /** How a transaction starts on a connection when it is held to `timeoutMs`; `begin` is the `BEGIN` statement. */
+  #budgetStart(timeoutMs, begin) {
     const value = budgetValue(timeoutMs);
     const settings = (scope) => budgetSettingsSql({ value: `'${value}'`, sessionTimeouts: true, scope });
-    return this.#transaction(work, (client) => {
+    return (client) => {
       if (!this.#keepsSessionBudget()) {
-        return { begin: `BEGIN; ${settings("transaction")}` };
+        return { begin: `${begin}; ${settings("transaction")}` };
       }
-      return this.#sessionValues.get(client) === value ? { begin: "BEGIN" } : { begin: `BEGIN; ${settings("session")}`, sessionValue: value };
-    });
+      return this.#sessionValues.get(client) === value ? { begin } : { begin: `${begin}; ${settings("session")}`, sessionValue: value };
+    };
   }
   #recordSession(client, sessionValue) {
     if (sessionValue === null) {
@@ -536,10 +517,38 @@ function withRootPool(executor, root) {
     ...executor.transactionWithBudget === void 0 ? {} : {
       transactionWithBudget: (work, timeoutMs) => executor.transactionWithBudget(work, timeoutMs)
     },
+    ...executor.transactionWithIsolation === void 0 ? {} : {
+      transactionWithIsolation: (work, options) => executor.transactionWithIsolation(work, options)
+    },
+    ...executor.isSerializationFailure === void 0 ? {} : { isSerializationFailure: (error) => executor.isSerializationFailure(error) },
     // eslint-disable-next-line relaybus/max-two-params -- PostgresExecutor port signature
     query: (sql, parameters, transaction, options) => transaction === void 0 ? root.query(sql, parameters, void 0, options) : executor.query(sql, parameters, transaction, options)
   };
 }
+
+// src/serialization-failure.ts
+var SERIALIZATION_FAILURE = "40001";
+var PRISMA_WRITE_CONFLICT = "P2034";
+var CONFLICT_CODES = /* @__PURE__ */ new Set([
+  SERIALIZATION_FAILURE,
+  PRISMA_WRITE_CONFLICT
+]);
+var MAXIMUM_DEPTH = 6;
+var WRAPPED_ERROR_KEYS = ["cause", "driverError", "originalError"];
+function isPostgresSerializationFailure(error, depth = 0) {
+  if (typeof error !== "object" || error === null || depth > MAXIMUM_DEPTH) {
+    return false;
+  }
+  const shape = error;
+  if (CONFLICT_CODES.has(shape.code) || shape.originalCode === SERIALIZATION_FAILURE) {
+    return true;
+  }
+  const meta = shape.meta;
+  if (isPostgresSerializationFailure(meta, depth + 1) || isPostgresSerializationFailure(meta?.driverAdapterError, depth + 1)) {
+    return true;
+  }
+  return WRAPPED_ERROR_KEYS.some((key) => isPostgresSerializationFailure(shape[key], depth + 1));
+}
 function text(row, column) {
   return row[column];
 }
@@ -3044,6 +3053,16 @@ var PostgresEventStore = class {
   async setup() {
     await this.#setup.run();
   }
+  /** Every level PostgreSQL has (it runs `read uncommitted` as `read committed`, which the bus does not offer). */
+  isolationLevels = TRANSACTION_ISOLATION_LEVELS;
+  /**
+   * True for a serialization failure (SQLSTATE `40001`) raised through any executor, including
+   * Prisma's `P2034` and the wrappers of TypeORM and Drizzle; a custom executor can add its own
+   * test with {@link PostgresExecutor.isSerializationFailure}.
+   */
+  isSerializationFailure(error) {
+    return isPostgresSerializationFailure(error) || this.#state.executor.isSerializationFailure?.(error) === true;
+  }
   /**
    * Runs `work` in a transaction of the executor. With `options.timeoutMs` (from `bus.transaction`)
    * the server holds the transaction to the budget: `statement_timeout`, and for executors with
@@ -3051,6 +3070,9 @@ var PostgresEventStore = class {
    * `transaction_timeout`, all scoped to the transaction. An executor with `transactionWithBudget`
    * (`PgExecutor`) sets them with `BEGIN`, so the budget costs no round trip; on a pool the store
    * created they are kept per connection and sent only when the connection does not have them yet.
+   * With `options.isolationLevel` the transaction runs at that level: `PgExecutor` sends it with
+   * `BEGIN ISOLATION LEVEL ...` (no extra round trip), any other executor as `SET TRANSACTION
+   * ISOLATION LEVEL ...` before the budget statement.
    */
   async transaction(work, options) {
     const own = { wake: false };
@@ -3062,12 +3084,20 @@ var PostgresEventStore = class {
         this.#state.ownTransactions.delete(transaction);
       }
     };
-    const result = await (options === void 0 ? this.#state.executor.transaction(tracked) : inBudgetedTransaction(this.#state, { work: tracked, timeoutMs: options.timeoutMs }));
+    const result = await this.#open(tracked, options);
     if (own.wake) {
       this.#appender.wakeAfterCommit();
     }
     return result;
   }
+  /** Opens the transaction `work` runs in: plain, held to the budget, or at an isolation level too. */
+  #open(work, options) {
+    if (options === void 0) {
+      return this.#state.executor.transaction(work);
+    }
+    const { timeoutMs, isolationLevel } = options;
+    return isolationLevel === void 0 ? inBudgetedTransaction(this.#state, { work, timeoutMs }) : inIsolatedTransaction(this.#state, { work, timeoutMs, isolationLevel });
+  }
   /**
    * Writes the entries in `transaction`, normally with one statement
    * (`AppendStatements.insertFreshEvents`): keyed events reserve their sequence numbers (locking