@nestjs/workflows 0.0.2 → 0.0.4

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.js

@@ -3,6 +3,7 @@ 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
@@ -122,7 +123,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 +186,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();
@@ -215,7 +216,7 @@ export class LeasedWorker {
         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 {

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, 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;
@@ -204,7 +207,32 @@ export interface WorkflowStore {
      * See `WorkflowWrite` for what each field does.
      */
     write(id: string, token: string, write: WorkflowWrite): Promise<boolean>;
+    /**
+     * Optional, for a store whose ids, names or keys are bounded (columns of a fixed length): throws, synchronously, an
+     * error that names the key (a `RangeError`) when the store can't hold `value` as a `kind`. The engine calls it for
+     * what a run makes up as it goes (a step's or a wait's name, `$compensate:<step>`, a child's id and keys, a wait's
+     * signal and key) before it journals or starts anything with it, so the error fails the run at the call that made
+     * the key, and the instance compensates, instead of failing every write that carries it. Without this method, the
+     * 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, 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';
 /**
@@ -31,7 +31,11 @@ import type { MySqlWorkflowStoreOptions } from './interfaces/mysql-workflow-stor
  * On MySQL:
  * - Ids, names and keys are case- and accent-sensitive, and bounded: an instance id, a workflow's or a signal's name,
  *   a signal's key or id, a concurrency or rate-limit key hold at most 255 characters, a schedule's id 230, a
- *   journal entry's name 512. A longer one fails with a `RangeError` that names it, before any SQL.
+ *   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 })`
@@ -164,6 +168,10 @@ export declare class MySqlWorkflowStore implements WorkflowStore, OnModuleInit {
         terminateRequested: boolean;
     } | null>;
     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';
@@ -47,7 +48,11 @@ const ROWS_PER_INSERT = 1_000;
  * On MySQL:
  * - Ids, names and keys are case- and accent-sensitive, and bounded: an instance id, a workflow's or a signal's name,
  *   a signal's key or id, a concurrency or rate-limit key hold at most 255 characters, a schedule's id 230, a
- *   journal entry's name 512. A longer one fails with a `RangeError` that names it, before any SQL.
+ *   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 })`
@@ -604,8 +609,8 @@ WHERE ${p.in('id', ids)}`, p.values);
             checkSignal(write.signal);
         }
         for (const wait of write.release?.waits ?? []) {
-            checkKey("a wait's signal name", wait.signal, L.signal);
-            checkKey("a wait's signal key", wait.key, L.signalKey);
+            checkKey(KEYS.signal, wait.signal, L.signal);
+            checkKey(KEYS.signalKey, wait.key, L.signalKey);
         }
         return retryOnDeadlock(this.executor, async (tx) => {
             const release = write.release;
@@ -650,6 +655,14 @@ WHERE ${p.in('id', ids)}`, p.values);
             return true;
         });
     }
+    /** 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, 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() {
@@ -823,6 +836,16 @@ function checkSignal(s) {
 }
 function checkEntries(entries) {
     for (const entry of entries) {
-        checkKey("a journal entry's name (a step's, a wait's, or the engine's, such as $child: and a child's id)", entry.name, L.journalName);
+        checkKey(KEYS.journalName, entry.name, L.journalName);
     }
 }
+/** How the errors of `checkKey()`, and of `write()`'s own checks, name each key. */
+const KEYS = {
+    instanceId: 'an instance id',
+    workflow: "a workflow's name",
+    concurrencyKey: 'a concurrency key',
+    rateLimitKey: 'a rate-limit key',
+    journalName: "a journal entry's name (a step's, a wait's, or the engine's, such as $child: and a child's id)",
+    signal: "a wait's signal name",
+    signalKey: "a wait's signal key",
+};

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.

package/dist/services/workflow-client.service.d.ts

@@ -39,7 +39,12 @@ export declare class WorkflowClient implements BeforeApplicationShutdown {
      * with a different workflow or input. With `transaction`, the instance is
      * created in your transaction and commits or rolls back with it. Inside a
      * workflow step, a start without an `id` gets one derived from the step, so a
-     * retried step gets its instance back instead of starting another.
+     * retried step gets its instance back instead of starting another. An id, a
+     * key or an input string the store can't keep (`WorkflowStore.unstorableText()`:
+     * U+0000 on PostgreSQL, a lone UTF-16 surrogate in JSON on PostgreSQL and MySQL)
+     * is refused with a `TypeError`. Await it in your transaction's callback: a
+     * driver whose callback can't be async (better-sqlite3) commits before a failure
+     * is reported.
      */
     start<W>(workflow: Type<W> | string, input: WorkflowInput<W>, options?: StartWorkflowOptions): Promise<WorkflowStartResult>;
     /**
@@ -72,7 +77,8 @@ export declare class WorkflowClient implements BeforeApplicationShutdown {
     private outcomeOf;
     /**
      * `start()`, then `result()`: resolves with the output of the instance (the existing one, for
-     * an id that already has one), or rejects as `result()` does. `wait` is `result()`'s options;
+     * an id that already has one), or rejects as `result()` does. `wait` is `result()`'s options,
+     * counted once the instance is stored (`start()` isn't bounded by them);
      * `options.timeout` stays the instance's run timeout. Not with `{ transaction }`: the instance
      * wouldn't exist before your transaction commits.
      */
@@ -107,6 +113,9 @@ export declare class WorkflowClient implements BeforeApplicationShutdown {
      * instances parked on a matching wait right now. With `transaction`, the
      * signal and the wake-ups commit or roll back with your transaction. With
      * `id`, or from inside a workflow step, a repeated signal is stored once.
+     * A name, key, id or payload string the store can't keep is refused with a
+     * `TypeError`, as in `start()`. Await it in your transaction's callback, as
+     * `start()`.
      */
     signal<T>(signal: WorkflowSignal<T> | string, payload: NoInfer<T>, options?: SignalWorkflowOptions): Promise<WorkflowSignalSendResult>;
     /**

package/dist/services/workflow-client.service.js

@@ -25,6 +25,7 @@ import { assertSameInstance, newInstance } from '../utils/new-instance.util.js';
 import { signalName } from '../signals/workflow.signal.js';
 import { ENGINE_STORE, WorkflowStorage } from '../storage/workflow.storage.js';
 import { stepSignalId, stepStartId } from '../utils/step-scope.util.js';
+import { assertStorableJson, assertStorableText } from '../utils/storable-text.util.js';
 import { WorkflowRegistry } from './workflow-registry.service.js';
 import { WorkflowSchedules } from './workflow-schedules.service.js';
 import { WorkflowWorker } from './workflow-worker.service.js';
@@ -75,7 +76,12 @@ let WorkflowClient = class WorkflowClient {
      * with a different workflow or input. With `transaction`, the instance is
      * created in your transaction and commits or rolls back with it. Inside a
      * workflow step, a start without an `id` gets one derived from the step, so a
-     * retried step gets its instance back instead of starting another.
+     * retried step gets its instance back instead of starting another. An id, a
+     * key or an input string the store can't keep (`WorkflowStore.unstorableText()`:
+     * U+0000 on PostgreSQL, a lone UTF-16 surrogate in JSON on PostgreSQL and MySQL)
+     * is refused with a `TypeError`. Await it in your transaction's callback: a
+     * driver whose callback can't be async (better-sqlite3) commits before a failure
+     * is reported.
      */
     async start(workflow, input, options = {}) {
         const resolved = this.registry.resolve(workflow, options.version);
@@ -84,13 +90,14 @@ let WorkflowClient = class WorkflowClient {
         const data = newInstance(resolved, id, input, {
             caller: 'start()',
             now: this.clock.now(),
+            text: this.store.textCheck,
             timeout: options.timeout,
             concurrencyKey: options.concurrencyKey,
             rateLimitKey: options.rateLimitKey,
             priority: options.priority,
         });
-        // Nothing is awaited before the store's call: on a driver whose transactions are
-        // synchronous, its statements must run before the application's transaction callback returns.
+        // Nothing is awaited before the store's call: calls issued back to back (the CQRS publisher's)
+        // reach the transaction's connection in the order they were made.
         const { instance, created } = await (options.transaction === undefined
             ? this.store.create(data)
             : this.storeMethod('createInTransaction', 'start')(options.transaction, data));
@@ -150,7 +157,8 @@ let WorkflowClient = class WorkflowClient {
     }
     /**
      * `start()`, then `result()`: resolves with the output of the instance (the existing one, for
-     * an id that already has one), or rejects as `result()` does. `wait` is `result()`'s options;
+     * an id that already has one), or rejects as `result()` does. `wait` is `result()`'s options,
+     * counted once the instance is stored (`start()` isn't bounded by them);
      * `options.timeout` stays the instance's run timeout. Not with `{ transaction }`: the instance
      * wouldn't exist before your transaction commits.
      */
@@ -208,6 +216,7 @@ let WorkflowClient = class WorkflowClient {
         return this.stop(id, reason, true);
     }
     async stop(id, reason, terminate) {
+        assertStorableText('Reason', reason, this.store.textCheck('cancelReason'));
         const accepted = await this.store.requestCancel(id, { reason: reason ?? null, now: this.clock.now(), terminate });
         // Accepted is accepted: an instance whose payloads no codec can read any more is returned as stored.
         const details = await this.store.get(id).catch(() => this.store.inner.get(id));
@@ -228,6 +237,9 @@ let WorkflowClient = class WorkflowClient {
      * instances parked on a matching wait right now. With `transaction`, the
      * signal and the wake-ups commit or roll back with your transaction. With
      * `id`, or from inside a workflow step, a repeated signal is stored once.
+     * A name, key, id or payload string the store can't keep is refused with a
+     * `TypeError`, as in `start()`. Await it in your transaction's callback, as
+     * `start()`.
      */
     async signal(signal, payload, options = {}) {
         const name = signalName(signal);
@@ -236,7 +248,13 @@ let WorkflowClient = class WorkflowClient {
             throw new TypeError(`Invalid signal id ${JSON.stringify(options.id)}. Use a non-empty string, such as the id of the event that causes it.`);
         }
         const dedupeId = options.id ?? stepSignalId(name, key) ?? null;
-        const data = { name, key, dedupeId, payload: normalize(payload), now: this.clock.now() };
+        const keyCheck = this.store.textCheck('key');
+        assertStorableText('A signal name', name, keyCheck);
+        assertStorableText('A signal key', key, keyCheck);
+        assertStorableText('A signal id', dedupeId, keyCheck);
+        const json = normalize(payload);
+        assertStorableJson('Signal payload', json, this.store.textCheck('payload'));
+        const data = { name, key, dedupeId, payload: json, now: this.clock.now() };
         // Nothing is awaited before the store's call, as in start().
         const result = await (options.transaction === undefined
             ? this.store.signal(data)