@relaybus/postgres 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -1,10 +1,20 @@
-import { P as PostgresExecutor, a as PostgresParameter, b as PostgresQueryOptions, c as PostgresRow } from './executor-VZGmsMX4.cjs';
-import { RelayBusLogger, EventStore, AppendEntry, AppendResult, ClaimRequest, ClaimedDelivery, LeaseReference, ErrorInfo, DeliveryQuery, DeliveryRecord, PurgeRequest, PurgeResult, EventStoreStatistics } from '@relaybus/core';
+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 { PoolClient, Pool, PoolConfig } from 'pg';
 
 interface PgExecutorOptions {
     /** Receives the warning sent when prepared statements are switched off. Default `console`. */
     readonly logger?: RelayBusLogger;
+    /**
+     * The pool is this executor's alone (the store sets it for the pool it creates from
+     * `connectionString`). A transaction budget then becomes a session setting of the connection, sent
+     * with `BEGIN` only when the connection does not have it yet, and a transaction without a budget on
+     * such a connection puts the session defaults back in its `BEGIN`. Statements outside a
+     * transaction run under the budget the connection last got. Never set it for a pool other code
+     * uses, or behind a pooler in transaction mode (session settings would reach other clients); the
+     * executor stops it by itself when it notices a pooler (see prepared statements). Default `false`.
+     */
+    readonly sessionBudget?: boolean;
 }
 /**
  * Executor for a `pg` {@link Pool}. A transaction is a dedicated pool client
@@ -24,7 +34,15 @@ interface PgExecutorOptions {
 declare class PgExecutor implements PostgresExecutor<PoolClient> {
     #private;
     constructor(pool: Pool, options?: PgExecutorOptions);
+    /** The connection listens for `error` during the transaction, so a server-ended session fails the transaction instead of the process. */
+    readonly sessionTimeouts = true;
     transaction<T>(work: (transaction: PoolClient) => Promise<T>): Promise<T>;
+    /**
+     * Sends `BEGIN` and the budget settings as one simple query (the value as a literal: the simple
+     * query protocol has no parameters), so the budget costs no round trip. With `sessionBudget` a
+     * connection that already keeps this budget only gets `BEGIN`.
+     */
+    transactionWithBudget<T>(work: (transaction: PoolClient) => Promise<T>, timeoutMs: number): Promise<T>;
     query(sql: string, parameters: readonly PostgresParameter[], transaction?: PoolClient, options?: PostgresQueryOptions): Promise<readonly PostgresRow[]>;
 }
 
@@ -227,10 +245,18 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
      * `createPostgresSchemaSql()` instead.
      */
     setup(): Promise<void>;
-    transaction<T>(work: (transaction: TTransaction) => Promise<T>): Promise<T>;
+    /**
+     * 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
+     * `sessionTimeouts` (`pg`) also `idle_in_transaction_session_timeout` and, on PostgreSQL 17+,
+     * `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.
+     */
+    transaction<T>(work: (transaction: TTransaction) => Promise<T>, options?: EventStoreTransactionOptions): Promise<T>;
     /**
      * Writes the entries in `transaction`, normally with one statement
-     * ({@link PostgresStatements.insertFreshEvents}): keyed events reserve their sequence numbers (locking
+     * (`AppendStatements.insertFreshEvents`): keyed events reserve their sequence numbers (locking
      * the key rows in sorted order, so publishers cannot deadlock inside one call), then the new events and
      * their deliveries are inserted, ordered by primary key, and one notification wakes the dispatchers
      * when a delivery is due now. Events that already existed get their missing handlers' deliveries in
@@ -242,14 +268,14 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
     append(transaction: TTransaction, entries: readonly AppendEntry[], now: Date): Promise<AppendResult>;
     /**
      * Claims up to `limit` due deliveries, normally with one statement
-     * ({@link PostgresStatements.claimLanes}): from the lanes this owner already holds, then from free lanes
+     * (`LaneStatements.claimLanes`): from the lanes this owner already holds, then from free lanes
      * it takes in the same statement, recording the batch in the lane rows. A claim that would have to take
      * over a lane whose previous holder still runs deliveries under an expired lease continues in a
      * transaction that charges their lost attempts first, taking free lanes a few at a time (4, 8, 16, ...);
      * so does a claim whose statement kept seeing a lane it holds change under it, and one that came up
      * short with more free lanes left than it looked at. The step that fails after
      * the first one has recorded deliveries returns those instead of failing: a recorded delivery nobody
-     * received would be held for a whole lease. See {@link PostgresStatements.claim} for the rules a delivery
+     * received would be held for a whole lease. See `ClaimStatements.claim` for the rules a delivery
      * must satisfy.
      */
     claim(request: ClaimRequest): Promise<ClaimedDelivery[]>;
@@ -285,8 +311,22 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
      */
     purge(request: PurgeRequest): Promise<PurgeResult>;
     statistics(now: Date): Promise<EventStoreStatistics>;
-    /** Ends the pool this store created from `connectionString`. Pools and executors you passed in stay open. */
-    close(): Promise<void>;
+    /**
+     * Ends the pool this store created from `connectionString`. Pools and executors you passed in stay
+     * open. Once `options.signal` aborts (the shutdown deadline passed), the connections the store opened
+     * itself are destroyed: queries still running on them fail at once instead of holding the shutdown.
+     */
+    close(options?: CloseOptions): Promise<void>;
+}
+
+/**
+ * A claim was refused because giving back the deliveries of an earlier, failed
+ * claim still fails. Claiming before that would take the owner's live lanes for
+ * foreign ones; the next claim tries the reconciliation again.
+ */
+declare class ReconcileFailedError extends RelayBusError {
+    name: string;
+    readonly code: string;
 }
 
-export { PgExecutor, type PgExecutorOptions, type PostgresConnectionOptions, PostgresEventStore, type PostgresEventStoreOptions, type PostgresEventStoreSettings, PostgresExecutor, type PostgresExecutorOptions, type PostgresNames, PostgresParameter, type PostgresPoolOptions, PostgresQueryOptions, PostgresRow, type PostgresSchemaOptions, type PostgresWakeUp, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };
+export { PgExecutor, type PgExecutorOptions, type PostgresConnectionOptions, PostgresEventStore, type PostgresEventStoreOptions, type PostgresEventStoreSettings, PostgresExecutor, type PostgresExecutorOptions, type PostgresNames, PostgresParameter, type PostgresPoolOptions, PostgresQueryOptions, PostgresRow, type PostgresSchemaOptions, type PostgresWakeUp, ReconcileFailedError, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };

package/dist/index.d.ts

@@ -1,10 +1,20 @@
-import { P as PostgresExecutor, a as PostgresParameter, b as PostgresQueryOptions, c as PostgresRow } from './executor-VZGmsMX4.js';
-import { RelayBusLogger, EventStore, AppendEntry, AppendResult, ClaimRequest, ClaimedDelivery, LeaseReference, ErrorInfo, DeliveryQuery, DeliveryRecord, PurgeRequest, PurgeResult, EventStoreStatistics } from '@relaybus/core';
+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 { PoolClient, Pool, PoolConfig } from 'pg';
 
 interface PgExecutorOptions {
     /** Receives the warning sent when prepared statements are switched off. Default `console`. */
     readonly logger?: RelayBusLogger;
+    /**
+     * The pool is this executor's alone (the store sets it for the pool it creates from
+     * `connectionString`). A transaction budget then becomes a session setting of the connection, sent
+     * with `BEGIN` only when the connection does not have it yet, and a transaction without a budget on
+     * such a connection puts the session defaults back in its `BEGIN`. Statements outside a
+     * transaction run under the budget the connection last got. Never set it for a pool other code
+     * uses, or behind a pooler in transaction mode (session settings would reach other clients); the
+     * executor stops it by itself when it notices a pooler (see prepared statements). Default `false`.
+     */
+    readonly sessionBudget?: boolean;
 }
 /**
  * Executor for a `pg` {@link Pool}. A transaction is a dedicated pool client
@@ -24,7 +34,15 @@ interface PgExecutorOptions {
 declare class PgExecutor implements PostgresExecutor<PoolClient> {
     #private;
     constructor(pool: Pool, options?: PgExecutorOptions);
+    /** The connection listens for `error` during the transaction, so a server-ended session fails the transaction instead of the process. */
+    readonly sessionTimeouts = true;
     transaction<T>(work: (transaction: PoolClient) => Promise<T>): Promise<T>;
+    /**
+     * Sends `BEGIN` and the budget settings as one simple query (the value as a literal: the simple
+     * query protocol has no parameters), so the budget costs no round trip. With `sessionBudget` a
+     * connection that already keeps this budget only gets `BEGIN`.
+     */
+    transactionWithBudget<T>(work: (transaction: PoolClient) => Promise<T>, timeoutMs: number): Promise<T>;
     query(sql: string, parameters: readonly PostgresParameter[], transaction?: PoolClient, options?: PostgresQueryOptions): Promise<readonly PostgresRow[]>;
 }
 
@@ -227,10 +245,18 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
      * `createPostgresSchemaSql()` instead.
      */
     setup(): Promise<void>;
-    transaction<T>(work: (transaction: TTransaction) => Promise<T>): Promise<T>;
+    /**
+     * 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
+     * `sessionTimeouts` (`pg`) also `idle_in_transaction_session_timeout` and, on PostgreSQL 17+,
+     * `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.
+     */
+    transaction<T>(work: (transaction: TTransaction) => Promise<T>, options?: EventStoreTransactionOptions): Promise<T>;
     /**
      * Writes the entries in `transaction`, normally with one statement
-     * ({@link PostgresStatements.insertFreshEvents}): keyed events reserve their sequence numbers (locking
+     * (`AppendStatements.insertFreshEvents`): keyed events reserve their sequence numbers (locking
      * the key rows in sorted order, so publishers cannot deadlock inside one call), then the new events and
      * their deliveries are inserted, ordered by primary key, and one notification wakes the dispatchers
      * when a delivery is due now. Events that already existed get their missing handlers' deliveries in
@@ -242,14 +268,14 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
     append(transaction: TTransaction, entries: readonly AppendEntry[], now: Date): Promise<AppendResult>;
     /**
      * Claims up to `limit` due deliveries, normally with one statement
-     * ({@link PostgresStatements.claimLanes}): from the lanes this owner already holds, then from free lanes
+     * (`LaneStatements.claimLanes`): from the lanes this owner already holds, then from free lanes
      * it takes in the same statement, recording the batch in the lane rows. A claim that would have to take
      * over a lane whose previous holder still runs deliveries under an expired lease continues in a
      * transaction that charges their lost attempts first, taking free lanes a few at a time (4, 8, 16, ...);
      * so does a claim whose statement kept seeing a lane it holds change under it, and one that came up
      * short with more free lanes left than it looked at. The step that fails after
      * the first one has recorded deliveries returns those instead of failing: a recorded delivery nobody
-     * received would be held for a whole lease. See {@link PostgresStatements.claim} for the rules a delivery
+     * received would be held for a whole lease. See `ClaimStatements.claim` for the rules a delivery
      * must satisfy.
      */
     claim(request: ClaimRequest): Promise<ClaimedDelivery[]>;
@@ -285,8 +311,22 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
      */
     purge(request: PurgeRequest): Promise<PurgeResult>;
     statistics(now: Date): Promise<EventStoreStatistics>;
-    /** Ends the pool this store created from `connectionString`. Pools and executors you passed in stay open. */
-    close(): Promise<void>;
+    /**
+     * Ends the pool this store created from `connectionString`. Pools and executors you passed in stay
+     * open. Once `options.signal` aborts (the shutdown deadline passed), the connections the store opened
+     * itself are destroyed: queries still running on them fail at once instead of holding the shutdown.
+     */
+    close(options?: CloseOptions): Promise<void>;
+}
+
+/**
+ * A claim was refused because giving back the deliveries of an earlier, failed
+ * claim still fails. Claiming before that would take the owner's live lanes for
+ * foreign ones; the next claim tries the reconciliation again.
+ */
+declare class ReconcileFailedError extends RelayBusError {
+    name: string;
+    readonly code: string;
 }
 
-export { PgExecutor, type PgExecutorOptions, type PostgresConnectionOptions, PostgresEventStore, type PostgresEventStoreOptions, type PostgresEventStoreSettings, PostgresExecutor, type PostgresExecutorOptions, type PostgresNames, PostgresParameter, type PostgresPoolOptions, PostgresQueryOptions, PostgresRow, type PostgresSchemaOptions, type PostgresWakeUp, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };
+export { PgExecutor, type PgExecutorOptions, type PostgresConnectionOptions, PostgresEventStore, type PostgresEventStoreOptions, type PostgresEventStoreSettings, PostgresExecutor, type PostgresExecutorOptions, type PostgresNames, PostgresParameter, type PostgresPoolOptions, PostgresQueryOptions, PostgresRow, type PostgresSchemaOptions, type PostgresWakeUp, ReconcileFailedError, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };