@nestjs/workflows 0.0.3 → 0.0.5

package/dist/core/interfaces/leased-worker-options.interface.d.ts

@@ -40,7 +40,11 @@ export interface LeasedRun {
     readonly detached: boolean;
     /**
      * Renews the lease now, as the heartbeat does (a long step that proves it's alive): `false` once it's lost. A renewal
-     * that fails (the store is unreachable) keeps the lease, which the next heartbeat renews before it runs out.
+     * that fails (the store is unreachable) keeps the lease, which the next heartbeat renews before it runs out. One
+     * renewal is in flight at a time: called while one is (a heartbeat's held up by the store), it waits for that one, then
+     * for one more that goes out as soon as it answered, or beside it once it went a heartbeat interval unanswered, and
+     * resolves with that one's answer. None goes once the lease was lost, the run ended or was detached, before the call
+     * or meanwhile: it then resolves `false` if the lease was lost, else `true`.
      */
     renew(): Promise<boolean>;
     /** Marks the lease lost, when a fenced write found it gone: aborts `signal` and stops renewing. */

package/dist/core/interfaces/result-waiter-options.interface.d.ts

@@ -29,7 +29,8 @@ export type ResultOutcome<T> = {
 export interface ResultWaiterOptions<T> {
     /**
      * Reads the outcome from the store: `null` while it hasn't ended. Called when a wait starts, then after a backoff
-     * (25 ms at first, doubling up to a second), until the wait ends; a rejection rejects the wait.
+     * (25 ms at first, doubling up to a second), until the wait ends; a rejection rejects the wait. A wait that times
+     * out, is aborted or closes doesn't wait for a read in flight: its answer or rejection is then ignored.
      */
     read(id: string): Promise<ResultOutcome<T> | null>;
     /** The error a wait rejects with past its `timeout`. Default: an `Error` that names `id`. */
@@ -45,7 +46,10 @@ export interface ResultWaiterOptions<T> {
  * ```
  */
 export interface ResultWaitOptions {
-    /** Stop waiting after this long, in wall-clock time (not a `Clock`'s). Default: no limit. */
+    /**
+     * Stop waiting after this long, in wall-clock time (not a `Clock`'s). Default: no limit. A hard deadline: a read
+     * still in flight when it passes isn't awaited, so a timeout shorter than one read (0 included) rejects.
+     */
     timeout?: Duration;
     /** Stop waiting when it aborts: the wait rejects with its reason. */
     signal?: AbortSignal;

package/dist/core/results/result-waiter.d.ts

@@ -3,7 +3,8 @@ import type { ResultOutcome, ResultWaiterOptions, ResultWaitOptions } from '../i
  * Waits for the outcome of something another part of the application runs (a workflow instance, a job): at once
  * when this process ends it and says so (`settle()`), else by reading the store with a backoff (every 25 ms at
  * first, doubling up to every second), which sees what other processes ended. A wait rejects past its `timeout`
- * (the work goes on), when its `signal` aborts, and as soon as the waiter closes, without reading the store again:
+ * (the work goes on), when its `signal` aborts, and as soon as the waiter closes, without reading the store again
+ * nor waiting for a read in flight (it ends in the background, and its answer or failure is ignored):
  * close it in `beforeApplicationShutdown`, which Nest runs after `onModuleDestroy` (where workers drain, so work that
  * ends during the drain still answers) and before the HTTP server closes.
  *
@@ -50,8 +51,9 @@ export declare class ResultWaiter<T = unknown> {
      */
     close(): Promise<void>;
     /**
-     * Reads `id`, unless the wait settles first. It races a promise of its own, not one the whole wait shares: each
-     * race leaves a reaction on its inputs until they settle, so a shared one would keep one per poll.
+     * Reads `id`, unless the wait settles, times out or is aborted first: the read is then given up, and left to end in
+     * the background (`Promise.race` handles its failure). It races a promise of its own, not one the whole wait
+     * shares: each race leaves a reaction on its inputs until they settle, so a shared one would keep one per poll.
      */
     private read;
     private add;

package/dist/core/results/result-waiter.js

@@ -1,12 +1,16 @@
 import { setImmediate as nextMacrotask } from 'node:timers/promises';
 import { parseDuration } from '../time/duration.js';
+import { MAX_TIMER_DELAY, setTimer } from '../utils/timer.util.js';
 /** What a read in flight gives way to: an outcome settled locally, or the waiter closing. */
 const SETTLED = Symbol('settled');
+/** What a read in flight gives way to when the wait's timeout passes. */
+const EXPIRED = Symbol('expired');
 /**
  * Waits for the outcome of something another part of the application runs (a workflow instance, a job): at once
  * when this process ends it and says so (`settle()`), else by reading the store with a backoff (every 25 ms at
  * first, doubling up to every second), which sees what other processes ended. A wait rejects past its `timeout`
- * (the work goes on), when its `signal` aborts, and as soon as the waiter closes, without reading the store again:
+ * (the work goes on), when its `signal` aborts, and as soon as the waiter closes, without reading the store again
+ * nor waiting for a read in flight (it ends in the background, and its answer or failure is ignored):
  * close it in `beforeApplicationShutdown`, which Nest runs after `onModuleDestroy` (where workers drain, so work that
  * ends during the drain still answers) and before the HTTP server closes.
  *
@@ -48,7 +52,10 @@ export class ResultWaiter {
         const deadline = performance.now() + timeoutMs;
         options.signal?.throwIfAborted();
         const wait = { closed: this.closed };
-        const nudge = () => wait.wake?.();
+        const nudge = () => {
+            wait.giveUp?.();
+            wait.wake?.();
+        };
         const close = () => {
             wait.closed = true;
             wait.settle?.();
@@ -59,19 +66,19 @@ export class ResultWaiter {
         options.signal?.addEventListener('abort', nudge);
         try {
             for (let delay = 25;; delay = Math.min(delay * 2, 1_000)) {
-                const read = wait.outcome || wait.closed ? SETTLED : await this.read(id, wait);
+                const read = wait.outcome || wait.closed ? SETTLED : await this.read(id, wait, deadline, options.signal);
                 if (wait.outcome) {
                     return unwrap(wait.outcome);
                 }
                 if (read === SETTLED) {
                     throw this.options.closedError?.(id) ?? new Error(`The waiter closed while waiting for the result of "${id}".`);
                 }
-                if (read) {
+                if (read && read !== EXPIRED) {
                     return unwrap(read);
                 }
                 options.signal?.throwIfAborted();
                 const remaining = deadline - performance.now();
-                if (remaining <= 0) {
+                if (read === EXPIRED || remaining <= 0) {
                     throw this.options.timeoutError?.(id, timeoutMs) ?? new Error(`"${id}" didn't end within ${timeoutMs}ms.`);
                 }
                 await new Promise((resolve) => {
@@ -116,16 +123,33 @@ export class ResultWaiter {
         await nextMacrotask();
     }
     /**
-     * Reads `id`, unless the wait settles first. It races a promise of its own, not one the whole wait shares: each
-     * race leaves a reaction on its inputs until they settle, so a shared one would keep one per poll.
+     * Reads `id`, unless the wait settles, times out or is aborted first: the read is then given up, and left to end in
+     * the background (`Promise.race` handles its failure). It races a promise of its own, not one the whole wait
+     * shares: each race leaves a reaction on its inputs until they settle, so a shared one would keep one per poll.
      */
-    async read(id, wait) {
-        const settled = new Promise((resolve) => (wait.settle = () => resolve(SETTLED)));
+    async read(id, wait, deadline, signal) {
+        // Aborted during the backoff's sleep: no read for a caller that went away.
+        if (signal?.aborted) {
+            return null;
+        }
+        let timer;
+        const givenWay = new Promise((resolve) => {
+            wait.settle = () => resolve(SETTLED);
+            wait.giveUp = () => resolve(null);
+            const remaining = deadline - performance.now();
+            if (remaining !== Infinity) {
+                // A deadline beyond what a timer supports: the read is given up at the longest delay, and the next one waits on.
+                const expired = remaining <= MAX_TIMER_DELAY ? EXPIRED : null;
+                timer = setTimer(() => resolve(expired), Math.max(remaining, 0));
+            }
+        });
         try {
-            return await Promise.race([this.options.read(id), settled]);
+            return await Promise.race([this.options.read(id), givenWay]);
         }
         finally {
             wait.settle = undefined;
+            wait.giveUp = undefined;
+            clearTimeout(timer);
         }
     }
     add(id, wait) {

package/dist/core/utils/timer.util.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The longest delay `setTimeout` and `setInterval` support: 2^31 - 1 ms, about 24.8 days. Node runs a longer one
+ * after 1 ms instead (with a `TimeoutOverflowWarning`), so a step `timeout: '30d'` would time out every attempt at
+ * once, and a `heartbeatInterval` of '30d' would renew the lease every millisecond.
+ *
+ * @internal
+ */
+export declare const MAX_TIMER_DELAY: number;
+/** @internal `setTimeout`, with delays beyond what timers support treated as the longest one. */
+export declare function setTimer(callback: () => void, ms: number): NodeJS.Timeout;
+/** @internal `setInterval`, capped like `setTimer()`. */
+export declare function setRepeatingTimer(callback: () => void, ms: number): NodeJS.Timeout;

package/dist/core/utils/timer.util.js

@@ -0,0 +1,16 @@
+/**
+ * The longest delay `setTimeout` and `setInterval` support: 2^31 - 1 ms, about 24.8 days. Node runs a longer one
+ * after 1 ms instead (with a `TimeoutOverflowWarning`), so a step `timeout: '30d'` would time out every attempt at
+ * once, and a `heartbeatInterval` of '30d' would renew the lease every millisecond.
+ *
+ * @internal
+ */
+export const MAX_TIMER_DELAY = 2 ** 31 - 1;
+/** @internal `setTimeout`, with delays beyond what timers support treated as the longest one. */
+export function setTimer(callback, ms) {
+    return setTimeout(callback, Math.min(ms, MAX_TIMER_DELAY));
+}
+/** @internal `setInterval`, capped like `setTimer()`. */
+export function setRepeatingTimer(callback, ms) {
+    return setInterval(callback, Math.min(ms, MAX_TIMER_DELAY));
+}

package/dist/core/workers/leased-worker.d.ts

@@ -2,8 +2,11 @@ import type { LeasedWorkerOptions } from '../interfaces/leased-worker-options.in
 /**
  * A claim-execute loop under leases, any number of processes sharing a store: it claims due items (as many as it has
  * free slots), executes them, renews each one's lease every `heartbeatInterval` (a third of the lease by default), and
- * aborts an item's `signal` when a renewal finds its lease gone. It looks for work every `pollInterval`, and at once
- * after `kick()` (a local write made something due) or when an item ends. `drain()` runs due items on demand, for
+ * aborts an item's `signal` when a renewal finds its lease gone. An item has one renewal in flight at a time, so a store
+ * that holds a renewal up (a lock its row waits on) gets no more of them meanwhile: one asked for in the meantime goes
+ * out once that one answered, or beside it once it went a heartbeat interval unanswered (a connection that died without
+ * an error never answers), and none more while those two are in flight. It looks for work every `pollInterval`, and at
+ * once after `kick()` (a local write made something due) or when an item ends. `drain()` runs due items on demand, for
  * tests and scripts.
  *
  * Shutdown is graceful: call `shutdown()` from `onModuleDestroy`. It stops claiming, waits for the claims in flight

package/dist/core/workers/leased-worker.js

@@ -3,11 +3,15 @@ import { hostname } from 'node:os';
 import { Logger } from '@nestjs/common';
 import { systemClock } from '../time/clock.js';
 import { parseDuration } from '../time/duration.js';
+import { setRepeatingTimer, setTimer } from '../utils/timer.util.js';
 /**
  * A claim-execute loop under leases, any number of processes sharing a store: it claims due items (as many as it has
  * free slots), executes them, renews each one's lease every `heartbeatInterval` (a third of the lease by default), and
- * aborts an item's `signal` when a renewal finds its lease gone. It looks for work every `pollInterval`, and at once
- * after `kick()` (a local write made something due) or when an item ends. `drain()` runs due items on demand, for
+ * aborts an item's `signal` when a renewal finds its lease gone. An item has one renewal in flight at a time, so a store
+ * that holds a renewal up (a lock its row waits on) gets no more of them meanwhile: one asked for in the meantime goes
+ * out once that one answered, or beside it once it went a heartbeat interval unanswered (a connection that died without
+ * an error never answers), and none more while those two are in flight. It looks for work every `pollInterval`, and at
+ * once after `kick()` (a local write made something due) or when an item ends. `drain()` runs due items on demand, for
  * tests and scripts.
  *
  * Shutdown is graceful: call `shutdown()` from `onModuleDestroy`. It stops claiming, waits for the claims in flight
@@ -122,7 +126,7 @@ export class LeasedWorker {
         let timer;
         await Promise.race([
             Promise.allSettled([...this.runs].map((run) => run.done)),
-            new Promise((resolve) => (timer = setTimeout(resolve, this.shutdownMs))),
+            new Promise((resolve) => (timer = setTimer(resolve, this.shutdownMs))),
         ]);
         clearTimeout(timer);
         for (const run of this.runs) {
@@ -185,7 +189,7 @@ export class LeasedWorker {
                 this.wake = undefined;
                 resolve();
             };
-            const timer = setTimeout(done, this.pollMs);
+            const timer = setTimer(done, this.pollMs);
             this.wake = () => {
                 this.kicked = false;
                 done();
@@ -210,12 +214,12 @@ export class LeasedWorker {
         }
     }
     launch(item) {
-        const run = new Run(item, () => this.renew(run));
+        const run = new Run(item, this.heartbeatMs, () => this.renew(run));
         this.runs.add(run);
         if (this.stopped) {
             run.halt();
         }
-        run.heartbeat = setInterval(() => void run.renew(), this.heartbeatMs);
+        run.heartbeat = setRepeatingTimer(() => void run.renew(), this.heartbeatMs);
         run.heartbeat.unref();
         let executing;
         try {
@@ -227,7 +231,7 @@ export class LeasedWorker {
         run.done = executing
             .catch((error) => this.report(error, 'execute'))
             .finally(() => {
-            clearInterval(run.heartbeat);
+            run.end();
             this.runs.delete(run);
         });
         return run.done;
@@ -246,12 +250,21 @@ export class LeasedWorker {
 }
 /** A claimed item's run: its signal, its heartbeat, and what became of its lease. */
 class Run {
-    constructor(item, renewer) {
+    constructor(item, heartbeatMs, renewer) {
         this.item = item;
+        this.heartbeatMs = heartbeatMs;
         this.renewer = renewer;
         this.controller = new AbortController();
         this.lost = false;
         this.isDetached = false;
+        /** Its `execute` settled: no more renewals. */
+        this.ended = false;
+        /** The renewals in flight: one, or two once the older went a heartbeat interval unanswered. */
+        this.inFlight = new Set();
+        /** How many renewals went out: the next one's `seq` follows. */
+        this.sent = 0;
+        /** The `seq` of the latest renewal that landed (the store wrote its `until`). */
+        this.landed = 0;
     }
     get signal() {
         return this.controller.signal;
@@ -262,10 +275,78 @@ class Run {
     get detached() {
         return this.isDetached;
     }
-    async renew() {
-        if (this.lost || this.isDetached) {
-            return !this.lost;
+    /**
+     * Renews the lease (a heartbeat's tick, or the item's own call), one renewal at a time: a store that holds one up
+     * would otherwise get another at each tick, each holding a connection, and an older one could land after a newer
+     * one, shortening the lease. One asked for while another is in flight sends nothing then: it goes out once that one
+     * answered, its `until` read then (so after a renewal that was held up, the lease's deadline counts from when it
+     * answered), those asked for meanwhile sharing it, and resolves with its answer. A renewal a heartbeat interval
+     * unanswered no longer holds the next one back, as it may never answer (a connection that died without an error):
+     * the next goes out beside it, and no third while both are in flight. One that lands after a later one did leaves
+     * its older `until`, so one more follows it. None goes once the lease is lost (an answer, or `loseLease()`), the run
+     * ended, or it was detached: those asked for meanwhile resolve as `renew()` would then.
+     */
+    renew() {
+        if (this.lost || this.isDetached || this.ended) {
+            return Promise.resolve(!this.lost);
+        }
+        return this.canSend() ? this.send() : this.ask();
+    }
+    /** Whether a renewal can go out now: none is in flight, or one went a heartbeat interval unanswered; never a third. */
+    canSend() {
+        const [oldest, next] = this.inFlight;
+        return !oldest || (!next && oldest.late);
+    }
+    /** Asks for the renewal that goes out as soon as one can (`flush()`): its callers' answer. */
+    ask() {
+        if (!this.again) {
+            let resolve;
+            const promise = new Promise((resolved) => (resolve = resolved));
+            this.again = { promise, resolve };
+        }
+        return this.again.promise;
+    }
+    /**
+     * Sends the renewal asked for meanwhile if one can go out now (a renewal answered, or went a heartbeat interval
+     * unanswered). None goes once the lease is lost, the run ended or was detached: its callers hear what `renew()` would
+     * say then.
+     */
+    flush() {
+        const again = this.again;
+        if (!again) {
+            return;
+        }
+        if (this.lost || this.isDetached || this.ended) {
+            this.again = undefined;
+            again.resolve(!this.lost);
+        }
+        else if (this.canSend()) {
+            this.again = undefined;
+            void this.send().then(again.resolve);
         }
+    }
+    /** Sends a renewal, and once it answered, before its callers hear it, the one asked for meanwhile if it can go. */
+    send() {
+        const renewal = {
+            seq: ++this.sent,
+            late: false,
+            // Unanswered for a heartbeat interval, it no longer holds the next one back.
+            timer: setTimer(() => {
+                renewal.late = true;
+                this.flush();
+            }, this.heartbeatMs).unref(),
+        };
+        this.inFlight.add(renewal);
+        const answer = this.renewOnce(renewal.seq);
+        void answer.then(() => {
+            clearTimeout(renewal.timer);
+            this.inFlight.delete(renewal);
+            this.flush();
+        });
+        return answer;
+    }
+    /** One renewal: `false` once it found the lease gone; one that fails keeps the lease. */
+    async renewOnce(seq) {
         let held;
         try {
             held = await this.renewer();
@@ -276,8 +357,14 @@ class Run {
         }
         if (!held) {
             this.loseLease();
+            return false;
+        }
+        // It landed after a later renewal did (on a slower connection): the store keeps its older `until` now.
+        if (seq < this.landed) {
+            void this.ask();
         }
-        return held;
+        this.landed = Math.max(this.landed, seq);
+        return true;
     }
     loseLease() {
         if (this.lost) {
@@ -298,4 +385,9 @@ class Run {
         this.isDetached = true;
         clearInterval(this.heartbeat);
     }
+    /** Its `execute` settled: no more heartbeats, and no more renewals. */
+    end() {
+        this.ended = true;
+        clearInterval(this.heartbeat);
+    }
 }

package/dist/cqrs/workflow-event.publisher.js

@@ -111,9 +111,9 @@ let WorkflowEventPublisher = class WorkflowEventPublisher {
             failure.event = undefined;
             return;
         }
-        // Issued back to back, not awaited in between: a driver whose transactions are synchronous
-        // must see every statement before the application's callback returns, and on the
-        // transaction's one connection they still run in this order.
+        // Issued back to back, not awaited in between: on the transaction's one connection they still
+        // run in this order. The application awaits publish() in its transaction callback, so its
+        // driver must accept an async one (not better-sqlite3's), as start() and signal() require.
         const settled = await Promise.allSettled(writes.map((write) => write.run(transaction)));
         const index = settled.findIndex((result) => result.status === 'rejected');
         if (index !== -1) {

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export { ChildWorkflowFailedError, isWorkflowInterrupt, NonRetryableStepError, S
 export type { SerializedWorkflowError } from './interfaces/index.js';
 export { WorkflowEvents, type WorkflowCancelledEvent, type WorkflowChildStartedEvent, type WorkflowCompensatingEvent, type WorkflowCompensationFailedEvent, type WorkflowCompletedEvent, type WorkflowCustomStatusEvent, type WorkflowDeletedEvent, type WorkflowEvent, type WorkflowFailedEvent, type WorkflowJournalLargeEvent, type WorkflowResumedEvent, type WorkflowRetriedEvent, type WorkflowScheduleSkippedEvent, type WorkflowSignalReceivedEvent, type WorkflowSignalTimedOutEvent, type WorkflowStartedEvent, type WorkflowStepCompensatedEvent, type WorkflowStepCompletedEvent, type WorkflowStepFailedEvent, type WorkflowSuspendedEvent, } from './events/index.js';
 export { WorkflowStorage } from './storage/index.js';
-export type { NewWorkflowInstance, NewWorkflowSignal, WorkflowCancelRequest, WorkflowClaim, WorkflowClaimRequest, WorkflowConcurrencyLimit, WorkflowInstanceDetails, WorkflowKeyKind, WorkflowListQuery, WorkflowPurgeQuery, WorkflowPurgeResult, WorkflowRateLimitRule, WorkflowRateWindow, WorkflowRelease, WorkflowReopen, WorkflowScheduleClaimRequest, WorkflowScheduleQuery, WorkflowScheduleRecord, WorkflowScheduleSave, WorkflowScheduleWrite, WorkflowSignalQuery, WorkflowSignalRecord, WorkflowSignalResult, WorkflowStorageRegisterOptions, WorkflowStore, WorkflowWrite, } from './interfaces/index.js';
+export type { NewWorkflowInstance, NewWorkflowSignal, WorkflowCancelRequest, WorkflowClaim, WorkflowClaimRequest, WorkflowConcurrencyLimit, WorkflowInstanceDetails, WorkflowKeyKind, WorkflowListQuery, WorkflowPurgeQuery, WorkflowPurgeResult, WorkflowRateLimitRule, WorkflowRateWindow, WorkflowRelease, WorkflowReopen, WorkflowScheduleClaimRequest, WorkflowScheduleQuery, WorkflowScheduleRecord, WorkflowScheduleSave, WorkflowScheduleWrite, WorkflowSignalQuery, WorkflowSignalRecord, WorkflowSignalResult, WorkflowStorageRegisterOptions, WorkflowStore, WorkflowTextColumn, WorkflowWrite, } from './interfaces/index.js';
 export * from './stores/index.js';
 export { AesGcmPayloadCodec, type AesGcmPayloadCodecOptions } from './core/codecs/index.js';
 export type { WorkflowPayloadCodec, WorkflowPayloadContext } from './interfaces/index.js';

package/dist/interfaces/workflow-client.interface.d.ts

@@ -72,7 +72,10 @@ export interface SignalWorkflowOptions {
 export interface WorkflowResultOptions {
     /**
      * How long to wait. Past it, the call rejects with `WorkflowResultTimeoutError`, and the
-     * instance keeps running. Wall-clock time, not the module's clock. Default: no limit.
+     * instance keeps running. Wall-clock time, not the module's clock. Default: no limit. A hard
+     * deadline: a store read still in flight when it passes isn't awaited, so a timeout shorter than
+     * one round trip to the store (0 included) rejects, also for an instance that has ended. To
+     * check an instance without waiting, use `getStatus()`.
      */
     timeout?: Duration;
     /** Stops waiting once aborted (a client that went away), rejecting with the signal's reason. */

package/dist/interfaces/workflow-context.interface.d.ts

@@ -53,9 +53,9 @@ export interface WorkflowCompensationContext extends WorkflowStepContext {
 export interface WorkflowStepOptions<T> {
     /** Default: the module's `retry` (3 attempts, 1s doubling up to 5m). */
     retry?: number | false | WorkflowRetryOptions;
-    /** Fail the attempt (retryably) after this long. */
+    /** Fail the attempt (retryably) after this long. Capped at about 24.8 days, the longest timer Node supports. */
     timeout?: Duration;
-    /** Fail the attempt (retryably) if `heartbeat()` is not called this often. */
+    /** Fail the attempt (retryably) if `heartbeat()` is not called this often. Capped like `timeout`. */
     heartbeatTimeout?: Duration;
     /**
      * Undo this step, once it completed, if the workflow later fails or is

package/dist/interfaces/workflow-store.interface.d.ts

@@ -35,7 +35,10 @@ export interface WorkflowStore {
      * hands its transaction callback (a Drizzle `tx`, a TypeORM `EntityManager`...). Write only
      * through it, so the instance commits or rolls back with the application's rows, and never
      * catch a database error inside it (on PostgreSQL that aborts the transaction: use
-     * insert-or-ignore). Without this method, `start()` with a transaction throws.
+     * insert-or-ignore). Without this method, `start()` with a transaction throws. The
+     * application awaits `start()` in its transaction callback, so its driver must accept an
+     * async one: one whose transactions are synchronous (better-sqlite3) commits before a
+     * failure is reported.
      */
     createInTransaction?(transaction: unknown, instance: NewWorkflowInstance): Promise<{
         instance: WorkflowInstance;
@@ -213,9 +216,23 @@ export interface WorkflowStore {
      * store's own check in `write()` or `create()` is all there is, and the instance is retried as after any store error.
      */
     checkKey?(kind: WorkflowKeyKind, value: string): void;
+    /**
+     * Optional, for a store that can't keep some text (PostgreSQL can't keep U+0000, and neither PostgreSQL nor MySQL a
+     * lone UTF-16 surrogate in JSON): what `text` holds that the store can't keep in a `column`, such as `'U+0000'`, or
+     * `undefined`. `'json'` is text inside a JSON value (an input, a result, a payload, a journal entry, which holds its
+     * name); `'text'` is an id, a name, a key or a cancel reason in a column of its own. The engine asks before it stores
+     * what the application gives or a run makes, and refuses such text with a `TypeError` that names where it sits, so
+     * the call fails (a run fails and compensates) instead of every write that carries it. It doesn't ask about what a
+     * codec encodes, which the store sees only encoded. In an error's text, which can't be refused, U+0000 and lone
+     * surrogates are replaced with U+FFFD where the store refuses it. Without this method, nothing is refused or
+     * replaced, and the store's own failure in `write()` or `create()` is all there is.
+     */
+    unstorableText?(text: string, column: WorkflowTextColumn): string | undefined;
 }
 /** The ids, names and keys `WorkflowStore.checkKey()` checks. */
 export type WorkflowKeyKind = 'instanceId' | 'workflow' | 'concurrencyKey' | 'rateLimitKey' | 'journalName' | 'signal' | 'signalKey';
+/** Where `WorkflowStore.unstorableText()`'s text is stored: inside a JSON value, or in a text column of its own. */
+export type WorkflowTextColumn = 'json' | 'text';
 /** `WorkflowStore.get()`'s result, and `WorkflowClient.getStatus()`'s. */
 export interface WorkflowInstanceDetails extends WorkflowInstance {
     /** Signals the instance waits for, if suspended in `waitForSignal()`. */

package/dist/mysql/interfaces/mysql-workflow-store-options.interface.d.ts

@@ -18,7 +18,7 @@ export interface MySqlWorkflowStoreOptions {
      * Apply the store's pending migrations at startup, one statement at a time under a lock (`GET_LOCK()`), so processes
      * that start together migrate once, and a run that stopped halfway resumes where it stopped. With `false`, startup
      * fails with a `WorkflowSchemaError` while the schema is behind this version of the package: apply them with
-     * `npx nest-workflows migrate`, or with your own migration tool (`MySqlWorkflowStore.migrationSql()` or
+     * `npx @nestjs/workflows migrate`, or with your own migration tool (`MySqlWorkflowStore.migrationSql()` or
      * `migrationStatements()`). Default: `true`, except when `NODE_ENV` is `production`.
      */
     migrate?: boolean;

package/dist/mysql/mysql-workflow.store.d.ts

@@ -1,7 +1,7 @@
 import { type OnModuleInit } from '@nestjs/common';
 import { type MigrationSqlOptions, type MigrationStatementsOptions } from '@nestjs/store-kit/mysql';
 import type { WorkflowInstance, WorkflowStatus } from '../interfaces/workflow-instance.interface.js';
-import type { NewWorkflowInstance, NewWorkflowSignal, WorkflowCancelRequest, WorkflowClaim, WorkflowClaimRequest, WorkflowInstanceDetails, WorkflowKeyKind, WorkflowListQuery, WorkflowPurgeQuery, WorkflowPurgeResult, WorkflowReopen, WorkflowScheduleClaimRequest, WorkflowScheduleQuery, WorkflowScheduleRecord, WorkflowScheduleSave, WorkflowScheduleWrite, WorkflowSignalQuery, WorkflowSignalRecord, WorkflowSignalResult, WorkflowStore, WorkflowWrite } from '../interfaces/workflow-store.interface.js';
+import type { NewWorkflowInstance, NewWorkflowSignal, WorkflowCancelRequest, WorkflowClaim, WorkflowClaimRequest, WorkflowInstanceDetails, WorkflowKeyKind, WorkflowListQuery, WorkflowPurgeQuery, WorkflowPurgeResult, WorkflowReopen, WorkflowScheduleClaimRequest, WorkflowScheduleQuery, WorkflowScheduleRecord, WorkflowScheduleSave, WorkflowScheduleWrite, WorkflowSignalQuery, WorkflowSignalRecord, WorkflowSignalResult, WorkflowStore, WorkflowTextColumn, WorkflowWrite } from '../interfaces/workflow-store.interface.js';
 import type { WorkflowStorage } from '../storage/workflow.storage.js';
 import type { MySqlWorkflowStoreOptions } from './interfaces/mysql-workflow-store-options.interface.js';
 /**
@@ -34,6 +34,8 @@ import type { MySqlWorkflowStoreOptions } from './interfaces/mysql-workflow-stor
  *   journal entry's name 512. A longer one fails with a `RangeError` that names it, before any SQL. One a run makes up
  *   (a step's or a wait's name, `$compensate:<step>`, a child's id or keys) is thrown where the run makes it
  *   (`checkKey()`), so the run fails and compensates, as any error it throws.
+ * - JSON can't hold a lone UTF-16 surrogate (`unstorableText()`): the engine refuses one in an input, a payload, a
+ *   result or a step's name with a `TypeError` where the application or the run gives it, unless a codec encodes it.
  * - The application's transactions may be REPEATABLE READ, MySQL's default. `signal(..., { transaction })` finds the
  *   instances to wake with a locking read of their waits, which sees the latest committed ones whatever the level; the
  *   signal lock is held until the application's transaction ends, as on PostgreSQL. `start(..., { transaction })`
@@ -168,6 +170,8 @@ export declare class MySqlWorkflowStore implements WorkflowStore, OnModuleInit {
     write(id: string, token: string, write: WorkflowWrite): Promise<boolean>;
     /** What a run makes up (a step's name, a child's id...), checked by the engine before it writes or starts anything with it. */
     checkKey(kind: WorkflowKeyKind, value: string): void;
+    /** A lone surrogate in JSON: what the engine refuses before it writes (see the class). */
+    unstorableText(text: string, column: WorkflowTextColumn): string | undefined;
     /** The store's readiness (the server and the schema), then the signal lock's row: before its own first statement. */
     private ready;
     /**

package/dist/mysql/mysql-workflow.store.js

@@ -1,5 +1,6 @@
 import { Logger } from '@nestjs/common';
 import { columns, ensureLockRows, keyColumn, lockKeys, mysqlErrorCode, quoteTable, retryOnDeadlock, SqlParams, toBool, toInt, toJson, toText, } from '@nestjs/store-kit/mysql';
+import { loneSurrogateIn } from '../utils/storable-text.util.js';
 import { RateWindowClaim } from '../sql/rate-windows.js';
 import { CANCELLABLE_STATUSES, INSTANCE_COLUMNS, RUNNABLE_STATUSES, SCHEDULE_COLUMNS, SIGNAL_COLUMNS, toInstance, toSchedule } from '../sql/workflow-rows.js';
 import { checkKey, MYSQL_KEY_LIMITS as L } from './key-limits.js';
@@ -50,6 +51,8 @@ const ROWS_PER_INSERT = 1_000;
  *   journal entry's name 512. A longer one fails with a `RangeError` that names it, before any SQL. One a run makes up
  *   (a step's or a wait's name, `$compensate:<step>`, a child's id or keys) is thrown where the run makes it
  *   (`checkKey()`), so the run fails and compensates, as any error it throws.
+ * - JSON can't hold a lone UTF-16 surrogate (`unstorableText()`): the engine refuses one in an input, a payload, a
+ *   result or a step's name with a `TypeError` where the application or the run gives it, unless a codec encodes it.
  * - The application's transactions may be REPEATABLE READ, MySQL's default. `signal(..., { transaction })` finds the
  *   instances to wake with a locking read of their waits, which sees the latest committed ones whatever the level; the
  *   signal lock is held until the application's transaction ends, as on PostgreSQL. `start(..., { transaction })`
@@ -656,6 +659,10 @@ WHERE ${p.in('id', ids)}`, p.values);
     checkKey(kind, value) {
         checkKey(KEYS[kind], value, L[kind]);
     }
+    /** A lone surrogate in JSON: what the engine refuses before it writes (see the class). */
+    unstorableText(text, column) {
+        return column === 'json' ? loneSurrogateIn(text) : undefined;
+    }
     // ---------------------------------------------------------------- internals
     /** The store's readiness (the server and the schema), then the signal lock's row: before its own first statement. */
     async ready() {

package/dist/postgres/interfaces/postgres-workflow-store-options.interface.d.ts

@@ -15,7 +15,7 @@ export interface PostgresWorkflowStoreOptions {
     /**
      * Apply the store's pending migrations at startup, in one transaction under an advisory lock, so processes that
      * start together migrate once. With `false`, startup fails with a `WorkflowSchemaError` while the schema is behind
-     * this version of the package: apply them with `npx nest-workflows migrate`, or with your own migration tool
+     * this version of the package: apply them with `npx @nestjs/workflows migrate`, or with your own migration tool
      * (`PostgresWorkflowStore.migrationSql()`). Default: `true`, except when `NODE_ENV` is `production`.
      */
     migrate?: boolean;

package/dist/postgres/postgres-workflow.store.d.ts

@@ -1,7 +1,7 @@
 import { type OnModuleInit } from '@nestjs/common';
 import { type MigrationSqlOptions } from '@nestjs/store-kit/postgres';
 import type { WorkflowInstance, WorkflowStatus } from '../interfaces/workflow-instance.interface.js';
-import type { NewWorkflowInstance, NewWorkflowSignal, WorkflowCancelRequest, WorkflowClaim, WorkflowClaimRequest, WorkflowInstanceDetails, WorkflowListQuery, WorkflowPurgeQuery, WorkflowPurgeResult, WorkflowReopen, WorkflowScheduleClaimRequest, WorkflowScheduleQuery, WorkflowScheduleRecord, WorkflowScheduleSave, WorkflowScheduleWrite, WorkflowSignalQuery, WorkflowSignalRecord, WorkflowSignalResult, WorkflowStore, WorkflowWrite } from '../interfaces/workflow-store.interface.js';
+import type { NewWorkflowInstance, NewWorkflowSignal, WorkflowCancelRequest, WorkflowClaim, WorkflowClaimRequest, WorkflowInstanceDetails, WorkflowListQuery, WorkflowPurgeQuery, WorkflowPurgeResult, WorkflowReopen, WorkflowScheduleClaimRequest, WorkflowScheduleQuery, WorkflowScheduleRecord, WorkflowScheduleSave, WorkflowScheduleWrite, WorkflowSignalQuery, WorkflowSignalRecord, WorkflowSignalResult, WorkflowStore, WorkflowTextColumn, WorkflowWrite } from '../interfaces/workflow-store.interface.js';
 import type { WorkflowStorage } from '../storage/workflow.storage.js';
 import type { PostgresWorkflowStoreOptions } from './interfaces/postgres-workflow-store-options.interface.js';
 /**
@@ -26,6 +26,9 @@ import type { PostgresWorkflowStoreOptions } from './interfaces/postgres-workflo
  *
  * Given `storage`, it registers itself (`storage.registerSource(this)`), as every store does. It checks its schema,
  * or migrates it (`migrate`), in `onModuleInit` (so before the worker starts), or at its first call outside Nest.
+ *
+ * PostgreSQL keeps U+0000 in neither `text` nor `jsonb`, nor a lone UTF-16 surrogate in `jsonb` (`unstorableText()`):
+ * the engine refuses them with a `TypeError` where the application or a run gives them, unless a codec encodes them.
  */
 export declare class PostgresWorkflowStore implements WorkflowStore, OnModuleInit {
     /**
@@ -117,6 +120,8 @@ export declare class PostgresWorkflowStore implements WorkflowStore, OnModuleIni
         terminateRequested: boolean;
     } | null>;
     write(id: string, token: string, write: WorkflowWrite): Promise<boolean>;
+    /** U+0000 anywhere, and a lone surrogate in JSON: what the engine refuses before it writes (see the class). */
+    unstorableText(text: string, column: WorkflowTextColumn): string | undefined;
     private insertInstance;
     private insertSignal;
     /**

package/dist/postgres/postgres-workflow.store.js

@@ -1,5 +1,6 @@
 import { Logger } from '@nestjs/common';
 import { advisoryLock, assertReadCommittedTransaction, columns, quoteSchema, SqlParams, toBool, toInt, toJson, toText, } from '@nestjs/store-kit/postgres';
+import { loneSurrogateIn, nulIn } from '../utils/storable-text.util.js';
 import { RateWindowClaim } from '../sql/rate-windows.js';
 import { CANCELLABLE_STATUSES, INSTANCE_COLUMNS, RUNNABLE_STATUSES, SCHEDULE_COLUMNS, toInstance, toSchedule } from '../sql/workflow-rows.js';
 import { workflowStoreSchema } from './migrations/index.js';
@@ -29,6 +30,9 @@ const CANCELLABLE = `(${CANCELLABLE_STATUSES.map((status) => `'${status}'`).join
  *
  * Given `storage`, it registers itself (`storage.registerSource(this)`), as every store does. It checks its schema,
  * or migrates it (`migrate`), in `onModuleInit` (so before the worker starts), or at its first call outside Nest.
+ *
+ * PostgreSQL keeps U+0000 in neither `text` nor `jsonb`, nor a lone UTF-16 surrogate in `jsonb` (`unstorableText()`):
+ * the engine refuses them with a `TypeError` where the application or a run gives them, unless a codec encodes them.
  */
 export class PostgresWorkflowStore {
     /**
@@ -491,6 +495,10 @@ RETURNING cancel_requested::text AS cancel_requested, terminate_requested::text
             return true;
         }, READ_COMMITTED);
     }
+    /** U+0000 anywhere, and a lone surrogate in JSON: what the engine refuses before it writes (see the class). */
+    unstorableText(text, column) {
+        return nulIn(text) ?? (column === 'json' ? loneSurrogateIn(text) : undefined);
+    }
     // ---------------------------------------------------------------- internals
     async insertInstance(db, i) {
         // An instance deleted between the insert that met it and the read of it is created again.