@duraflows/kysely 4.0.1 → 4.1.0

package/README.md

@@ -103,7 +103,7 @@ See the [`@duraflows/pg` README](https://github.com/camcima/duraflows/tree/main/
 
 ## API
 
-### `kyselyWorkflowProviders(db): WorkflowPersistenceProvider`
+### `kyselyWorkflowProviders(db, options?): WorkflowPersistenceProvider`
 
 Factory function that creates all required persistence providers from a `Kysely<WorkflowDatabase>` instance. Returns:
 
@@ -111,6 +111,19 @@ Factory function that creates all required persistence providers from a `Kysely<
 - `historyStore` -- `KyselyWorkflowHistoryStore`
 - `transactionRunner` -- `KyselyTransactionRunner`
 
+Options (all optional; omitting them keeps the previous behaviour):
+
+- `lockTimeoutMs` -- sets `lock_timeout` for the duration of each transaction. Bounds how long a statement **waits for a row lock**, so a stuck lock holder cannot hang `triggerEvent()` while it keeps a pooled connection checked out. **This is the recommended setting.**
+- `statementTimeoutMs` -- sets `statement_timeout` for the duration of each transaction. Bounds how long **any single statement** may run — including SQL your own commands issue inside the transaction, which is why it is left unset by default: a legitimately slow command statement would be aborted and take the whole transition with it.
+
+```ts
+const persistence = kyselyWorkflowProviders(db, { lockTimeoutMs: 3000 });
+```
+
+Both are applied transaction-locally via `set_config(name, value, true)` — the function form of `SET LOCAL` — so they are reverted on `COMMIT`/`ROLLBACK` and never leak to other users of the shared pool. Values must be non-negative integers in milliseconds (`0` means "no timeout"); anything else throws a `WorkflowError` at construction time.
+
+`kyselyWorkflowProvidersFromTransaction()` takes no timeout options: the transaction is owned by the caller, so its settings are the caller's to configure.
+
 ### `kyselyWorkflowProvidersFromTransaction(trx): WorkflowPersistenceProvider`
 
 Convenience factory for short-lived runtimes pre-bound to an existing transaction. The returned transaction runner seeds the context with the bound `trx` if no context already exists.

package/dist/cjs/index.d.ts

@@ -1,11 +1,18 @@
 import type { Kysely, Transaction } from "kysely";
 import type { WorkflowPersistenceProvider } from "@duraflows/core";
 import type { WorkflowDatabase } from "./kysely-database.js";
+import { type KyselyTransactionRunnerOptions } from "./kysely-transaction-runner.js";
 export { KyselyTransactionContext } from "./kysely-transaction-context.js";
 export { KyselyTransactionRunner } from "./kysely-transaction-runner.js";
+export type { KyselyTransactionRunnerOptions } from "./kysely-transaction-runner.js";
 export { KyselyWorkflowInstanceStore } from "./kysely-instance-store.js";
 export { KyselyWorkflowHistoryStore } from "./kysely-history-store.js";
 export type { WorkflowDatabase, WorkflowInstancesTable, WorkflowHistoryTable } from "./kysely-database.js";
+/**
+ * Options accepted by {@link kyselyWorkflowProviders}. Every field is optional
+ * and omitting the argument entirely reproduces the pre-existing behaviour.
+ */
+export type KyselyWorkflowProvidersOptions = KyselyTransactionRunnerOptions;
 /**
  * Creates long-lived persistence providers from a Kysely instance.
  *
@@ -14,7 +21,7 @@ export type { WorkflowDatabase, WorkflowInstancesTable, WorkflowHistoryTable } f
  * only access workflow tables; the `unknown` cast is needed because
  * Kysely is invariant in its DB type parameter).
  */
-export declare function kyselyWorkflowProviders<DB extends WorkflowDatabase>(db: Kysely<DB>): WorkflowPersistenceProvider;
+export declare function kyselyWorkflowProviders<DB extends WorkflowDatabase>(db: Kysely<DB>, options?: KyselyWorkflowProvidersOptions): WorkflowPersistenceProvider;
 /**
  * Creates providers pre-bound to an existing Kysely transaction.
  *

package/dist/cjs/index.js

@@ -23,9 +23,9 @@ Object.defineProperty(exports, "KyselyWorkflowHistoryStore", { enumerable: true,
  * only access workflow tables; the `unknown` cast is needed because
  * Kysely is invariant in its DB type parameter).
  */
-function kyselyWorkflowProviders(db) {
+function kyselyWorkflowProviders(db, options = {}) {
     const narrowed = db;
-    const transactionRunner = new kysely_transaction_runner_js_1.KyselyTransactionRunner(narrowed);
+    const transactionRunner = new kysely_transaction_runner_js_1.KyselyTransactionRunner(narrowed, options);
     const instanceStore = new kysely_instance_store_js_1.KyselyWorkflowInstanceStore(narrowed);
     const historyStore = new kysely_history_store_js_1.KyselyWorkflowHistoryStore(narrowed);
     return { instanceStore, historyStore, transactionRunner };

package/dist/cjs/kysely-history-store.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KyselyWorkflowHistoryStore = void 0;
+const core_1 = require("@duraflows/core");
 const kysely_transaction_context_js_1 = require("./kysely-transaction-context.js");
 class KyselyWorkflowHistoryStore {
     db;
@@ -26,7 +27,10 @@ class KyselyWorkflowHistoryStore {
             trigger_metadata_json: JSON.stringify(entry.triggerMetadata ?? {}),
         })
             .returning("uuid")
-            .executeTakeFirstOrThrow();
+            // `INSERT ... RETURNING` always yields a row, so an empty result means the
+            // statement did not do what the adapter assumes. Surface that as the
+            // library's own error type rather than kysely's `NoResultError`.
+            .executeTakeFirstOrThrow(() => new core_1.WorkflowError("Failed to append workflow history: INSERT ... RETURNING uuid returned no row"));
         return row.uuid;
     }
     async findByInstanceUuid(workflowInstanceUuid, options) {

package/dist/cjs/kysely-transaction-runner.d.ts

@@ -1,9 +1,47 @@
 import type { Kysely } from "kysely";
 import type { WorkflowTransactionRunner } from "@duraflows/core";
 import type { WorkflowDatabase } from "./kysely-database.js";
+/**
+ * Transaction-scoped PostgreSQL timeouts.
+ *
+ * Both settings are optional and both default to unset: when neither is
+ * supplied the runner issues no extra statement at all, leaving the session and
+ * server defaults exactly as they were before this option existed.
+ */
+export interface KyselyTransactionRunnerOptions {
+    /**
+     * `lock_timeout` in milliseconds -- how long a statement waits for a row lock
+     * before it aborts. This is the recommended setting: it bounds the blocking
+     * `SELECT ... FOR UPDATE` behind `lockByUuid()`, so a stuck lock holder cannot
+     * hang a `triggerEvent()` call indefinitely while it keeps a pooled connection
+     * checked out. `0` disables the timeout (PostgreSQL's own default).
+     */
+    lockTimeoutMs?: number;
+    /**
+     * `statement_timeout` in milliseconds -- how long any single statement may run
+     * before it aborts. Deliberately unset by default: commands run inside the
+     * same transaction and may legitimately issue slow statements on the shared
+     * connection, and aborting one of those rolls the whole transition back.
+     * `0` disables the timeout (PostgreSQL's own default).
+     */
+    statementTimeoutMs?: number;
+}
 export declare class KyselyTransactionRunner implements WorkflowTransactionRunner {
     private readonly db;
-    constructor(db: Kysely<WorkflowDatabase>);
+    private readonly timeoutSettings;
+    constructor(db: Kysely<WorkflowDatabase>, options?: KyselyTransactionRunnerOptions);
     runInTransaction<T>(callback: () => Promise<T>): Promise<T>;
+    /**
+     * Applies the configured timeouts to `trx` as transaction-local settings, so
+     * they are reverted on COMMIT/ROLLBACK and never leak to other users of the
+     * shared pool.
+     *
+     * `set_config(name, value, is_local = true)` is the function form of
+     * `SET LOCAL`, reached through the query builder rather than kysely's `sql`
+     * template on purpose: this package imports kysely for types only, which is
+     * what keeps its CommonJS build loadable (kysely itself is ESM-only). Both
+     * arguments are bound parameters, so no value is ever interpolated into SQL.
+     */
+    private applyTimeouts;
 }
 //# sourceMappingURL=kysely-transaction-runner.d.ts.map

package/dist/cjs/kysely-transaction-runner.js

@@ -1,11 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KyselyTransactionRunner = void 0;
+const core_1 = require("@duraflows/core");
 const kysely_transaction_context_js_1 = require("./kysely-transaction-context.js");
+/**
+ * Rejects anything that is not a finite, non-negative integer. Called at
+ * construction time so an invalid value can never reach the database.
+ */
+function assertTimeoutMs(value, name) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new core_1.WorkflowError(`${name} must be a non-negative integer number of milliseconds, got ${value}`);
+    }
+}
+/**
+ * Resolves the configured timeouts into `(setting, value)` pairs, or an empty
+ * list when neither is configured.
+ */
+function buildTimeoutSettings(options) {
+    const settings = [];
+    if (options.lockTimeoutMs !== undefined) {
+        assertTimeoutMs(options.lockTimeoutMs, "lockTimeoutMs");
+        settings.push(["lock_timeout", String(options.lockTimeoutMs)]);
+    }
+    if (options.statementTimeoutMs !== undefined) {
+        assertTimeoutMs(options.statementTimeoutMs, "statementTimeoutMs");
+        settings.push(["statement_timeout", String(options.statementTimeoutMs)]);
+    }
+    return settings;
+}
 class KyselyTransactionRunner {
     db;
-    constructor(db) {
+    timeoutSettings;
+    constructor(db, options = {}) {
         this.db = db;
+        this.timeoutSettings = buildTimeoutSettings(options);
     }
     async runInTransaction(callback) {
         const existing = kysely_transaction_context_js_1.KyselyTransactionContext.getTransaction(this.db);
@@ -13,9 +41,28 @@ class KyselyTransactionRunner {
             return callback();
         }
         return this.db.transaction().execute(async (trx) => {
+            await this.applyTimeouts(trx);
             return kysely_transaction_context_js_1.KyselyTransactionContext.run(this.db, trx, callback);
         });
     }
+    /**
+     * Applies the configured timeouts to `trx` as transaction-local settings, so
+     * they are reverted on COMMIT/ROLLBACK and never leak to other users of the
+     * shared pool.
+     *
+     * `set_config(name, value, is_local = true)` is the function form of
+     * `SET LOCAL`, reached through the query builder rather than kysely's `sql`
+     * template on purpose: this package imports kysely for types only, which is
+     * what keeps its CommonJS build loadable (kysely itself is ESM-only). Both
+     * arguments are bound parameters, so no value is ever interpolated into SQL.
+     */
+    async applyTimeouts(trx) {
+        for (const [setting, value] of this.timeoutSettings) {
+            await trx
+                .selectNoFrom((eb) => eb.fn("set_config", [eb.val(setting), eb.val(value), eb.val(true)]).as("set_config"))
+                .executeTakeFirst();
+        }
+    }
 }
 exports.KyselyTransactionRunner = KyselyTransactionRunner;
 //# sourceMappingURL=kysely-transaction-runner.js.map

package/dist/index.d.ts

@@ -1,11 +1,18 @@
 import type { Kysely, Transaction } from "kysely";
 import type { WorkflowPersistenceProvider } from "@duraflows/core";
 import type { WorkflowDatabase } from "./kysely-database.js";
+import { type KyselyTransactionRunnerOptions } from "./kysely-transaction-runner.js";
 export { KyselyTransactionContext } from "./kysely-transaction-context.js";
 export { KyselyTransactionRunner } from "./kysely-transaction-runner.js";
+export type { KyselyTransactionRunnerOptions } from "./kysely-transaction-runner.js";
 export { KyselyWorkflowInstanceStore } from "./kysely-instance-store.js";
 export { KyselyWorkflowHistoryStore } from "./kysely-history-store.js";
 export type { WorkflowDatabase, WorkflowInstancesTable, WorkflowHistoryTable } from "./kysely-database.js";
+/**
+ * Options accepted by {@link kyselyWorkflowProviders}. Every field is optional
+ * and omitting the argument entirely reproduces the pre-existing behaviour.
+ */
+export type KyselyWorkflowProvidersOptions = KyselyTransactionRunnerOptions;
 /**
  * Creates long-lived persistence providers from a Kysely instance.
  *
@@ -14,7 +21,7 @@ export type { WorkflowDatabase, WorkflowInstancesTable, WorkflowHistoryTable } f
  * only access workflow tables; the `unknown` cast is needed because
  * Kysely is invariant in its DB type parameter).
  */
-export declare function kyselyWorkflowProviders<DB extends WorkflowDatabase>(db: Kysely<DB>): WorkflowPersistenceProvider;
+export declare function kyselyWorkflowProviders<DB extends WorkflowDatabase>(db: Kysely<DB>, options?: KyselyWorkflowProvidersOptions): WorkflowPersistenceProvider;
 /**
  * Creates providers pre-bound to an existing Kysely transaction.
  *

package/dist/index.js

@@ -14,9 +14,9 @@ export { KyselyWorkflowHistoryStore } from "./kysely-history-store.js";
  * only access workflow tables; the `unknown` cast is needed because
  * Kysely is invariant in its DB type parameter).
  */
-export function kyselyWorkflowProviders(db) {
+export function kyselyWorkflowProviders(db, options = {}) {
     const narrowed = db;
-    const transactionRunner = new KyselyTransactionRunner(narrowed);
+    const transactionRunner = new KyselyTransactionRunner(narrowed, options);
     const instanceStore = new KyselyWorkflowInstanceStore(narrowed);
     const historyStore = new KyselyWorkflowHistoryStore(narrowed);
     return { instanceStore, historyStore, transactionRunner };

package/dist/kysely-history-store.js

@@ -1,3 +1,4 @@
+import { WorkflowError } from "@duraflows/core";
 import { KyselyTransactionContext } from "./kysely-transaction-context.js";
 export class KyselyWorkflowHistoryStore {
     db;
@@ -23,7 +24,10 @@ export class KyselyWorkflowHistoryStore {
             trigger_metadata_json: JSON.stringify(entry.triggerMetadata ?? {}),
         })
             .returning("uuid")
-            .executeTakeFirstOrThrow();
+            // `INSERT ... RETURNING` always yields a row, so an empty result means the
+            // statement did not do what the adapter assumes. Surface that as the
+            // library's own error type rather than kysely's `NoResultError`.
+            .executeTakeFirstOrThrow(() => new WorkflowError("Failed to append workflow history: INSERT ... RETURNING uuid returned no row"));
         return row.uuid;
     }
     async findByInstanceUuid(workflowInstanceUuid, options) {

package/dist/kysely-transaction-runner.d.ts

@@ -1,9 +1,47 @@
 import type { Kysely } from "kysely";
 import type { WorkflowTransactionRunner } from "@duraflows/core";
 import type { WorkflowDatabase } from "./kysely-database.js";
+/**
+ * Transaction-scoped PostgreSQL timeouts.
+ *
+ * Both settings are optional and both default to unset: when neither is
+ * supplied the runner issues no extra statement at all, leaving the session and
+ * server defaults exactly as they were before this option existed.
+ */
+export interface KyselyTransactionRunnerOptions {
+    /**
+     * `lock_timeout` in milliseconds -- how long a statement waits for a row lock
+     * before it aborts. This is the recommended setting: it bounds the blocking
+     * `SELECT ... FOR UPDATE` behind `lockByUuid()`, so a stuck lock holder cannot
+     * hang a `triggerEvent()` call indefinitely while it keeps a pooled connection
+     * checked out. `0` disables the timeout (PostgreSQL's own default).
+     */
+    lockTimeoutMs?: number;
+    /**
+     * `statement_timeout` in milliseconds -- how long any single statement may run
+     * before it aborts. Deliberately unset by default: commands run inside the
+     * same transaction and may legitimately issue slow statements on the shared
+     * connection, and aborting one of those rolls the whole transition back.
+     * `0` disables the timeout (PostgreSQL's own default).
+     */
+    statementTimeoutMs?: number;
+}
 export declare class KyselyTransactionRunner implements WorkflowTransactionRunner {
     private readonly db;
-    constructor(db: Kysely<WorkflowDatabase>);
+    private readonly timeoutSettings;
+    constructor(db: Kysely<WorkflowDatabase>, options?: KyselyTransactionRunnerOptions);
     runInTransaction<T>(callback: () => Promise<T>): Promise<T>;
+    /**
+     * Applies the configured timeouts to `trx` as transaction-local settings, so
+     * they are reverted on COMMIT/ROLLBACK and never leak to other users of the
+     * shared pool.
+     *
+     * `set_config(name, value, is_local = true)` is the function form of
+     * `SET LOCAL`, reached through the query builder rather than kysely's `sql`
+     * template on purpose: this package imports kysely for types only, which is
+     * what keeps its CommonJS build loadable (kysely itself is ESM-only). Both
+     * arguments are bound parameters, so no value is ever interpolated into SQL.
+     */
+    private applyTimeouts;
 }
 //# sourceMappingURL=kysely-transaction-runner.d.ts.map

package/dist/kysely-transaction-runner.js

@@ -1,8 +1,36 @@
+import { WorkflowError } from "@duraflows/core";
 import { KyselyTransactionContext } from "./kysely-transaction-context.js";
+/**
+ * Rejects anything that is not a finite, non-negative integer. Called at
+ * construction time so an invalid value can never reach the database.
+ */
+function assertTimeoutMs(value, name) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new WorkflowError(`${name} must be a non-negative integer number of milliseconds, got ${value}`);
+    }
+}
+/**
+ * Resolves the configured timeouts into `(setting, value)` pairs, or an empty
+ * list when neither is configured.
+ */
+function buildTimeoutSettings(options) {
+    const settings = [];
+    if (options.lockTimeoutMs !== undefined) {
+        assertTimeoutMs(options.lockTimeoutMs, "lockTimeoutMs");
+        settings.push(["lock_timeout", String(options.lockTimeoutMs)]);
+    }
+    if (options.statementTimeoutMs !== undefined) {
+        assertTimeoutMs(options.statementTimeoutMs, "statementTimeoutMs");
+        settings.push(["statement_timeout", String(options.statementTimeoutMs)]);
+    }
+    return settings;
+}
 export class KyselyTransactionRunner {
     db;
-    constructor(db) {
+    timeoutSettings;
+    constructor(db, options = {}) {
         this.db = db;
+        this.timeoutSettings = buildTimeoutSettings(options);
     }
     async runInTransaction(callback) {
         const existing = KyselyTransactionContext.getTransaction(this.db);
@@ -10,8 +38,27 @@ export class KyselyTransactionRunner {
             return callback();
         }
         return this.db.transaction().execute(async (trx) => {
+            await this.applyTimeouts(trx);
             return KyselyTransactionContext.run(this.db, trx, callback);
         });
     }
+    /**
+     * Applies the configured timeouts to `trx` as transaction-local settings, so
+     * they are reverted on COMMIT/ROLLBACK and never leak to other users of the
+     * shared pool.
+     *
+     * `set_config(name, value, is_local = true)` is the function form of
+     * `SET LOCAL`, reached through the query builder rather than kysely's `sql`
+     * template on purpose: this package imports kysely for types only, which is
+     * what keeps its CommonJS build loadable (kysely itself is ESM-only). Both
+     * arguments are bound parameters, so no value is ever interpolated into SQL.
+     */
+    async applyTimeouts(trx) {
+        for (const [setting, value] of this.timeoutSettings) {
+            await trx
+                .selectNoFrom((eb) => eb.fn("set_config", [eb.val(setting), eb.val(value), eb.val(true)]).as("set_config"))
+                .executeTakeFirst();
+        }
+    }
 }
 //# sourceMappingURL=kysely-transaction-runner.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duraflows/kysely",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "PostgreSQL persistence adapter for duraflows using `kysely`. Integrates with kysely's type-safe query builder and AsyncLocalStorage-based transaction context.",
   "keywords": [
     "duraflows",
@@ -51,15 +51,15 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@duraflows/core": "^4.0.1",
+    "@duraflows/core": "^4.1.0",
     "kysely": "^0.29.4"
   },
   "devDependencies": {
     "@types/pg": "^8.20.4",
     "kysely": "^0.29.4",
     "pg": "^8.22.0",
-    "@duraflows/core": "4.0.1",
-    "@duraflows/pg": "4.0.1"
+    "@duraflows/pg": "4.1.0",
+    "@duraflows/core": "4.1.0"
   },
   "scripts": {
     "build": "tsc --build"