@nestjs/workflows 0.0.3 → 0.0.4

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

@@ -11,7 +11,9 @@ import { StepFailedError } from '../errors/step-failed.error.js';
 import { NonRetryableStepError } from '../errors/non-retryable-step.error.js';
 import { isWorkflowInterrupt, WorkflowInterrupt, } from '../errors/workflow-interrupt.error.js';
 import { serializeError } from '../utils/serialize-error.util.js';
+import { assertStorableJson, assertStorableText, unstorableJson } from '../utils/storable-text.util.js';
 import { runInStepScope } from '../utils/step-scope.util.js';
+import { setTimer } from '../core/utils/timer.util.js';
 import { ChildWorkflowFailedError } from '../errors/child-workflow-failed.error.js';
 import { WorkflowIdConflictError } from '../errors/workflow-id-conflict.error.js';
 import { CHILD_ENDED_SIGNAL } from '../workflows.constants.js';
@@ -400,6 +402,10 @@ export class WorkflowExecution {
         // The journal first: a replay returns the child it started, whatever the keys of its workflow's limits
         // compute today (a deploy may change them); they are computed only to start it.
         const name = `$child:${id}`;
+        // Only for a child this run starts, as visit() checks names: a replay returns the one a store already kept.
+        if (this.mode === 'run' && !this.journal.has(name)) {
+            assertStorableText("A child's id", id, this.deps.textCheck('name'));
+        }
         this.visit(name, 'child', true);
         const request = { id, workflow: resolved.name, input: createHash('sha256').update(canonical(normalize(input) ?? null)).digest('base64url') };
         const entry = this.journal.get(name);
@@ -429,6 +435,7 @@ export class WorkflowExecution {
             priority: options.priority ?? this.instance.priority,
             parentId: this.instance.id,
             parentClose,
+            text: this.deps.textCheck,
         });
         this.checkKey('instanceId', child.id);
         this.checkKey('workflow', child.workflow);
@@ -485,7 +492,10 @@ export class WorkflowExecution {
             throw this.interrupt('halt');
         }
         this.assertAlive();
-        for (const branch of branches.values()) {
+        const branchNames = this.deps.textCheck('payload');
+        for (const [key, branch] of branches) {
+            // The entry's data holds the branches by name.
+            assertStorableText(`A waitForAny("${name}") branch's name`, key, branchNames);
             if (branch.wait) {
                 this.checkWait(branch.wait);
             }
@@ -587,7 +597,10 @@ export class WorkflowExecution {
             throw new TypeError(`ctx.setStatus() got ${bytes} bytes of JSON, over the ${MAX_CUSTOM_STATUS_BYTES}-byte limit. Keep the status a summary; ` +
                 'return large data from the workflow, or keep it in your own tables.');
         }
-        this.customStatus = json === undefined ? null : JSON.parse(json);
+        // Before it is kept: the write of a failing run carries the last status that was set.
+        const parsed = json === undefined ? null : JSON.parse(json);
+        assertStorableJson('ctx.setStatus() value', parsed, this.deps.textCheck('payload'));
+        this.customStatus = parsed;
     }
     /** `{ customStatus }` when `ctx.setStatus()` changed it since it was last written, else `{}`: spread into a write. */
     statusChange() {
@@ -686,6 +699,11 @@ export class WorkflowExecution {
             catch (error) {
                 throw new NonRetryableStepError(`Result of "${name}" is not JSON-serializable: ${error.message}`);
             }
+            // Like the above, the same result every time: the store would refuse it at every attempt.
+            const unstorable = unstorableJson(`Result of "${name}"`, value, this.deps.textCheck('payload'));
+            if (unstorable) {
+                throw new NonRetryableStepError(unstorable.message);
+            }
         }
         catch (error) {
             if (this.abort.signal.aborted) {
@@ -752,14 +770,14 @@ export class WorkflowExecution {
         });
         const overall = overallMs === undefined
             ? undefined
-            : setTimeout(() => expire(new StepTimeoutError(`Step "${name}" timed out after ${overallMs}ms.`)), overallMs).unref();
+            : setTimer(() => expire(new StepTimeoutError(`Step "${name}" timed out after ${overallMs}ms.`)), overallMs).unref();
         let idle;
         const armIdle = () => {
             if (idleMs === undefined) {
                 return;
             }
             clearTimeout(idle);
-            idle = setTimeout(() => expire(new StepTimeoutError(`Step "${name}" sent no heartbeat for ${idleMs}ms.`)), idleMs).unref();
+            idle = setTimer(() => expire(new StepTimeoutError(`Step "${name}" sent no heartbeat for ${idleMs}ms.`)), idleMs).unref();
         };
         armIdle();
         let current = entry;
@@ -784,7 +802,9 @@ export class WorkflowExecution {
                     }
                     return;
                 }
-                current = { ...current, progress: normalize(progress) };
+                const json = normalize(progress);
+                assertStorableJson('Step progress', json, this.deps.textCheck('payload'));
+                current = { ...current, progress: json };
                 update(current);
                 await this.write([current]);
             },
@@ -847,6 +867,7 @@ export class WorkflowExecution {
         if (!entry && this.mode === 'run') {
             this.assertJournalRoom(name);
             this.checkKey('journalName', name);
+            assertStorableText("A journal entry's name (a step's, a sleep's or a wait's)", name, this.deps.textCheck('name'));
         }
         if (entry && entry.kind !== kind) {
             throw this.setFatal(new WorkflowNonDeterminismError(`${this.describe()} does not match its journal: "${name}" was recorded as a ${entry.kind}, but the code now calls it as a ${kind}. ${ADVICE}`));
@@ -988,6 +1009,11 @@ export class WorkflowExecution {
     checkWait(wait) {
         this.checkKey('signal', wait.signal);
         this.checkKey('signalKey', wait.key);
+        // In the waits' own columns, and in the journal entry's data.
+        for (const check of [this.deps.textCheck('key'), this.deps.textCheck('payload')]) {
+            assertStorableText("A wait's signal name", wait.signal, check);
+            assertStorableText("A wait's signal key", wait.key, check);
+        }
     }
     /** Fenced write of staged entries plus `entries`. */
     async write(entries) {

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

@@ -8,6 +8,7 @@ import type { WorkflowInstance } from '../interfaces/workflow-instance.interface
 import type { WorkflowSchedule } from '../interfaces/workflow-schedule.interface.js';
 import type { WorkflowsModuleOptions } from '../interfaces/workflows-module-options.interface.js';
 import { WorkflowStorage } from '../storage/workflow.storage.js';
+import { type TextCheck, type TextPlace } from '../utils/storable-text.util.js';
 import type { WorkflowScheduleSpec } from '../utils/schedule-spec.util.js';
 import { WorkflowRegistry } from './workflow-registry.service.js';
 /**
@@ -27,6 +28,8 @@ export declare class WorkflowScheduler implements OnApplicationBootstrap {
     constructor(storage: WorkflowStorage, options: WorkflowsModuleOptions, registry: WorkflowRegistry, events: WorkflowEvents);
     /** Read at each call, never in the constructor: sources register while providers are created. */
     private get store();
+    /** What the store can't keep of a text at `place` (`EncodedWorkflowStore.textCheck`), for `WorkflowSchedules`. */
+    textCheck(place: TextPlace): TextCheck | undefined;
     onApplicationBootstrap(): Promise<void>;
     /** @internal Called by the worker: starts the due occurrences of the schedules of the workflows it runs. */
     produce(owner: string, leaseMs: number): Promise<ScheduleProduction>;
@@ -47,6 +50,11 @@ export declare class WorkflowScheduler implements OnApplicationBootstrap {
     readableView(record: ScheduleRecord): Promise<WorkflowSchedule>;
     /** The schedules the workflows this process runs declare (each name's highest registered version's), for the `Scheduler`. */
     private declared;
+    /**
+     * Whether the store can keep a declared schedule's input (`WorkflowStore.unstorableText()`). One it can't is left out,
+     * logged, instead of failing every reconciliation of the others; an input the schedule computes is checked as it starts.
+     */
+    private storable;
     private fire;
     /** The unfinished instances the schedule started. */
     private running;

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

@@ -18,6 +18,7 @@ import { WorkflowStateError } from '../errors/workflow-state.error.js';
 import { WorkflowEvents } from '../events/workflow-events.service.js';
 import { ENGINE_STORE, PAYLOAD_CODECS, WorkflowStorage } from '../storage/workflow.storage.js';
 import { newInstance } from '../utils/new-instance.util.js';
+import { unstorableJson } from '../utils/storable-text.util.js';
 import { workflowScheduleStore } from '../utils/schedule-store.util.js';
 import { WORKFLOWS_MODULE_OPTIONS } from '../workflows.module-definition.js';
 import { WorkflowRegistry } from './workflow-registry.service.js';
@@ -57,6 +58,10 @@ let WorkflowScheduler = class WorkflowScheduler {
     get store() {
         return this.storage[ENGINE_STORE];
     }
+    /** What the store can't keep of a text at `place` (`EncodedWorkflowStore.textCheck`), for `WorkflowSchedules`. */
+    textCheck(place) {
+        return this.store.textCheck(place);
+    }
     async onApplicationBootstrap() {
         // A definition error (an id two workflows declare) fails the startup; the store's errors don't.
         this.registry.schedules();
@@ -93,6 +98,7 @@ let WorkflowScheduler = class WorkflowScheduler {
                 priority: spec.priority === 0 ? undefined : spec.priority,
                 scheduleId: record.id,
                 scheduledAt: at,
+                text: this.store.textCheck,
             });
         }
         catch (error) {
@@ -142,12 +148,25 @@ let WorkflowScheduler = class WorkflowScheduler {
     }
     /** The schedules the workflows this process runs declare (each name's highest registered version's), for the `Scheduler`. */
     declared() {
-        this.declarations ??= new Map([...this.registry.schedules()].map(([id, schedule]) => [
+        this.declarations ??= new Map([...this.registry.schedules()]
+            .filter(([id, schedule]) => this.storable(id, schedule.input))
+            .map(([id, schedule]) => [
             id,
             { id, target: schedule.workflow, version: this.registry.latest(schedule.workflow).version, spec: schedule.spec, payload: schedule.input },
         ]));
         return this.declarations;
     }
+    /**
+     * Whether the store can keep a declared schedule's input (`WorkflowStore.unstorableText()`). One it can't is left out,
+     * logged, instead of failing every reconciliation of the others; an input the schedule computes is checked as it starts.
+     */
+    storable(id, input) {
+        const refused = typeof input === 'function' ? undefined : unstorableJson(`Schedule "${id}": its input`, input, this.store.textCheck('payload'));
+        if (refused) {
+            this.logger.error(`${refused.message} The schedule isn't saved, and doesn't start its workflow.`);
+        }
+        return !refused;
+    }
     async fire({ schedule, spec, declared, at, now }) {
         const workflow = this.registry.resolve(schedule.target, spec.version ?? undefined);
         const started = await this.startOccurrence(schedule, spec, declared, workflow, at, now);

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

@@ -16,6 +16,7 @@ import { systemClock } from '../core/time/clock.js';
 import { WorkflowNotFoundError } from '../errors/workflow-not-found.error.js';
 import { WorkflowStateError } from '../errors/workflow-state.error.js';
 import { normalize } from '../utils/normalize.util.js';
+import { assertStorableJson } from '../utils/storable-text.util.js';
 import { scheduleSpec } from '../utils/schedule-spec.util.js';
 import { WORKFLOWS_MODULE_OPTIONS } from '../workflows.module-definition.js';
 import { WorkflowRegistry } from './workflow-registry.service.js';
@@ -62,6 +63,7 @@ let WorkflowSchedules = class WorkflowSchedules {
         catch (error) {
             throw new TypeError(`${owner}: its input is not JSON-serializable: ${error.message}`);
         }
+        assertStorableJson(`${owner}: its input`, input, this.scheduler.textCheck('payload'));
         const saved = await this.engine.save(id, (current) => {
             if (current?.declared) {
                 throw declaredError(current);

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

@@ -16,6 +16,7 @@ import { LeasedWorker } from '../core/workers/leased-worker.js';
 import { WorkflowNonDeterminismError } from '../errors/workflow-non-determinism.error.js';
 import { isWorkflowInterrupt } from '../errors/workflow-interrupt.error.js';
 import { serializeError } from '../utils/serialize-error.util.js';
+import { assertStorableJson } from '../utils/storable-text.util.js';
 import { resolveRetry } from '../core/retries/retry.js';
 import { resolveJournalLimits } from '../utils/journal-limits.util.js';
 import { normalize } from '../utils/normalize.util.js';
@@ -64,6 +65,7 @@ let WorkflowWorker = class WorkflowWorker {
             get store() {
                 return storage[ENGINE_STORE];
             },
+            textCheck: (place) => storage[ENGINE_STORE].textCheck(place),
             resolve: (workflow, version) => registry.resolve(workflow, version),
             createChild: async (child) => {
                 const { instance, created } = await storage[ENGINE_STORE].create(child);
@@ -272,6 +274,7 @@ let WorkflowWorker = class WorkflowWorker {
             let output;
             try {
                 output = normalize(outcome.value);
+                assertStorableJson('Workflow output', output, this.store.textCheck('payload'));
             }
             catch (error) {
                 return this.compensate(exec, instance, serializeError(error), false);

package/dist/storage/encoded-workflow.store.d.ts

@@ -1,6 +1,7 @@
 import type { WorkflowPayloadContext } from '../interfaces/workflow-payload-codec.interface.js';
 import { type PayloadCodecs } from '../core/codecs/payload-codecs.js';
 import type { WorkflowScheduleMethods } from '../utils/schedule-store.util.js';
+import { type TextCheck, type TextPlace } from '../utils/storable-text.util.js';
 import type { WorkflowInstance, WorkflowStatus } from '../interfaces/workflow-instance.interface.js';
 import type { NewWorkflowInstance, NewWorkflowSignal, WorkflowCancelRequest, WorkflowClaim, WorkflowClaimRequest, WorkflowInstanceDetails, WorkflowListQuery, WorkflowPurgeQuery, WorkflowPurgeResult, WorkflowReopen, WorkflowSignalQuery, WorkflowSignalRecord, WorkflowSignalResult, WorkflowStore, WorkflowWrite } from '../interfaces/workflow-store.interface.js';
 /** @internal A `WorkflowStore` without its schedules, which the engine reaches through the core's `Scheduler`. */
@@ -24,6 +25,11 @@ export declare class EncodedWorkflowStore implements WorkflowInstanceStore {
     inner: WorkflowStore, codecs: PayloadCodecs<WorkflowPayloadContext>);
     /** Whether a codec encodes what is written. */
     get encodes(): boolean;
+    /**
+     * What the store can't keep of a text at `place` (`WorkflowStore.unstorableText()`), or `undefined` where it keeps
+     * any: a store without the method, and a payload or a cancel reason a codec encodes, which the store sees encoded.
+     */
+    readonly textCheck: (place: TextPlace) => TextCheck | undefined;
     create(instance: NewWorkflowInstance): Promise<{
         instance: WorkflowInstance;
         created: boolean;
@@ -53,6 +59,11 @@ export declare class EncodedWorkflowStore implements WorkflowInstanceStore {
         terminateRequested: boolean;
     } | null>;
     write(id: string, token: string, write: WorkflowWrite): Promise<boolean>;
+    /**
+     * `error` with what the store can't keep in its text replaced with U+FFFD (`storableText()`), as an error is recorded
+     * whatever it holds: its name, and its message and stack unless a codec encodes them.
+     */
+    private storableError;
     private encodeNew;
     private encodeSignal;
     private encodeEntries;

package/dist/storage/encoded-workflow.store.js

@@ -1,6 +1,7 @@
 import { Logger } from '@nestjs/common';
 import { isEncodedPayload as encoded } from '../core/codecs/payload-codecs.js';
 import { andThen, toPromise } from '../core/utils/maybe.util.js';
+import { storableText } from '../utils/storable-text.util.js';
 /**
  * @internal The store as the engine sees it with a codec: payloads encoded on the way in, decoded on the way out, so
  * the store sees only what the codec returns, and the engine only plain values. Ids, names, keys, statuses and
@@ -13,6 +14,18 @@ export class EncodedWorkflowStore {
         this.inner = inner;
         this.codecs = codecs;
         this.unreadable = new Set();
+        /**
+         * What the store can't keep of a text at `place` (`WorkflowStore.unstorableText()`), or `undefined` where it keeps
+         * any: a store without the method, and a payload or a cancel reason a codec encodes, which the store sees encoded.
+         */
+        this.textCheck = (place) => {
+            const inner = this.inner;
+            if (typeof inner.unstorableText !== 'function' || (this.encodes && (place === 'payload' || place === 'cancelReason'))) {
+                return undefined;
+            }
+            const column = place === 'payload' || place === 'name' ? 'json' : 'text';
+            return (text) => inner.unstorableText(text, column);
+        };
         // Only when the store has them: the client tells a store that can't join transactions by their absence.
         // Nothing is awaited before the store's call when the codec is synchronous (see WorkflowClient.start()).
         if (typeof inner.createInTransaction === 'function') {
@@ -52,7 +65,10 @@ export class EncodedWorkflowStore {
         return this.inner.requestCancel(id, { ...request, reason });
     }
     async reopen(id, reopen) {
-        const [error, entries] = await Promise.all([this.codecs.encodeError(reopen.error, { field: 'error', instanceId: id }), this.encodeEntries(reopen.entries, id)]);
+        const [error, entries] = await Promise.all([
+            this.codecs.encodeError(this.storableError(reopen.error), { field: 'error', instanceId: id }),
+            this.encodeEntries(reopen.entries, id),
+        ]);
         return this.inner.reopen(id, { ...reopen, error, entries });
     }
     delete(id, statuses) {
@@ -93,7 +109,7 @@ export class EncodedWorkflowStore {
         const [entries, output, error, customStatus, signal] = await Promise.all([
             this.encodeEntries(write.entries, id),
             this.codecs.encode(write.output, context('output')),
-            this.codecs.encodeError(write.error, context('error')),
+            this.codecs.encodeError(this.storableError(write.error), context('error')),
             this.codecs.encode(write.customStatus, context('customStatus')),
             write.signal ? this.encodeSignal(write.signal) : undefined,
         ]);
@@ -107,6 +123,25 @@ export class EncodedWorkflowStore {
         });
     }
     // ---------------------------------------------------------------- payloads
+    /**
+     * `error` with what the store can't keep in its text replaced with U+FFFD (`storableText()`), as an error is recorded
+     * whatever it holds: its name, and its message and stack unless a codec encodes them.
+     */
+    storableError(error) {
+        const check = this.textCheck('name');
+        if (!check || error === null || error === undefined) {
+            return error;
+        }
+        const text = (value) => (typeof value !== 'string' || this.encodes ? value : storableText(value, check));
+        const { compensation } = error;
+        return {
+            ...error,
+            name: typeof error.name === 'string' ? storableText(error.name, check) : error.name,
+            message: text(error.message),
+            ...(error.stack === undefined ? {} : { stack: text(error.stack) }),
+            ...(compensation === undefined ? {} : { compensation: this.storableError(compensation) }),
+        };
+    }
     encodeNew(instance) {
         return andThen(this.codecs.encode(instance.input, { field: 'input', instanceId: instance.id }), (input) => ({ ...instance, input }));
     }
@@ -120,7 +155,7 @@ export class EncodedWorkflowStore {
                 this.codecs.encode(entry.result, context('result')),
                 this.codecs.encode(entry.progress, context('progress')),
                 this.codecs.encode(entry.data, context('data')),
-                this.codecs.encodeError(entry.error, context('error')),
+                this.codecs.encodeError(this.storableError(entry.error), context('error')),
             ]);
             return { ...entry, result, progress, data, error };
         }));

package/dist/utils/index.d.ts

@@ -5,3 +5,4 @@ export * from './step-scope.util.js';
 export * from './journal-limits.util.js';
 export * from './new-instance.util.js';
 export * from './normalize.util.js';
+export * from './storable-text.util.js';

package/dist/utils/index.js

@@ -5,3 +5,4 @@ export * from './step-scope.util.js';
 export * from './journal-limits.util.js';
 export * from './new-instance.util.js';
 export * from './normalize.util.js';
+export * from './storable-text.util.js';

package/dist/utils/new-instance.util.d.ts

@@ -2,6 +2,7 @@ import type { WorkflowMetadata } from '../interfaces/workflow-decorator-options.
 import type { WorkflowInstance, WorkflowParentClose } from '../interfaces/workflow-instance.interface.js';
 import type { NewWorkflowInstance } from '../interfaces/workflow-store.interface.js';
 import type { Duration } from '../core/time/duration.js';
+import { type TextChecks } from './storable-text.util.js';
 export interface NewInstanceOptions {
     caller: string;
     now: number;
@@ -13,6 +14,8 @@ export interface NewInstanceOptions {
     parentClose?: WorkflowParentClose;
     scheduleId?: string;
     scheduledAt?: number;
+    /** The store's checks of text (`EncodedWorkflowStore.textCheck`): what it can't keep is refused before it is asked to. */
+    text: TextChecks;
 }
 /** What `WorkflowClient.start()` and `ctx.startChild()` ask the store to create. */
 export declare function newInstance(workflow: WorkflowMetadata, id: unknown, input: unknown, options: NewInstanceOptions): NewWorkflowInstance;

package/dist/utils/new-instance.util.js

@@ -3,16 +3,23 @@ import { assertPriority } from '../core/limits/limits.js';
 import { canonical } from '../core/utils/canonical.util.js';
 import { runTimeoutMs } from './run-timeout.util.js';
 import { normalize } from './normalize.util.js';
+import { assertStorableJson, assertStorableText } from './storable-text.util.js';
 /** What `WorkflowClient.start()` and `ctx.startChild()` ask the store to create. */
 export function newInstance(workflow, id, input, options) {
     if (typeof id !== 'string' || id.length === 0) {
         throw new TypeError(`Invalid workflow instance id ${JSON.stringify(id)}. Use a non-empty string, such as \`order-\${orderId}\`.`);
     }
+    assertStorableText('An instance id', id, options.text('key'));
     if (options.priority !== undefined) {
         assertPriority(options.priority, options.caller);
     }
     const json = normalize(input);
+    assertStorableJson('Input', json, options.text('payload'));
     const timeoutMs = options.timeout === undefined ? workflow.timeout : runTimeoutMs(options.timeout, options.caller);
+    const concurrencyKey = keyOf(workflow, json, options.caller, 'concurrency', options.concurrencyKey);
+    assertStorableText('A concurrency key', concurrencyKey, options.text('key'));
+    const rateLimitKey = keyOf(workflow, json, options.caller, 'rateLimit', options.rateLimitKey);
+    assertStorableText('A rate-limit key', rateLimitKey, options.text('key'));
     return {
         id,
         workflow: workflow.name,
@@ -21,8 +28,8 @@ export function newInstance(workflow, id, input, options) {
         deadline: timeoutMs === undefined ? null : options.now + timeoutMs,
         parentId: options.parentId ?? null,
         parentClose: options.parentClose ?? null,
-        concurrencyKey: keyOf(workflow, json, options.caller, 'concurrency', options.concurrencyKey),
-        rateLimitKey: keyOf(workflow, json, options.caller, 'rateLimit', options.rateLimitKey),
+        concurrencyKey,
+        rateLimitKey,
         priority: options.priority ?? 0,
         scheduleId: options.scheduleId ?? null,
         scheduledAt: options.scheduledAt ?? null,

package/dist/utils/serialize-error.util.js

@@ -6,7 +6,13 @@ import { inspect } from 'node:util';
  */
 export function serializeError(error) {
     if (error instanceof Error) {
-        return { name: error.name || 'Error', message: String(error.message), stack: error.stack };
+        // Strings, as the record promises: a name or stack that isn't one is described, not thrown on.
+        const stack = stackOf(error);
+        return {
+            name: text(error.name || 'Error'),
+            message: text(error.message),
+            ...(stack === undefined ? {} : { stack }),
+        };
     }
     if (typeof error === 'string') {
         return { name: 'Error', message: error };
@@ -20,3 +26,21 @@ export function serializeError(error) {
     }
     return { name: 'Error', message: message ?? inspect(error, { depth: 3, breakLength: Infinity }) };
 }
+/** `String(value)`, or `util.inspect()` for a value `String()` throws on (no prototype, a throwing `toString()`). */
+function text(value) {
+    try {
+        return String(value);
+    }
+    catch {
+        return inspect(value, { depth: 3, breakLength: Infinity });
+    }
+}
+/** The error's stack, or `undefined`: V8 formats it on first read from the error's name, and throws if it can't. */
+function stackOf(error) {
+    try {
+        return error.stack === undefined ? undefined : text(error.stack);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/utils/storable-text.util.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Where the engine stores a piece of text, which decides what it asks the store (`WorkflowStore.unstorableText()`):
+ * - `payload`: an input, a result, a payload, a status, an output, in a JSON column, which a codec encodes;
+ * - `cancelReason`: a cancel's reason, in a text column, which a codec encodes;
+ * - `name`: a journal entry's name (a step's, a wait's, `$child:<id>`), which the entry's JSON holds too, never encoded;
+ * - `key`: an id, a name or a key in a text column of its own, never encoded.
+ */
+export type TextPlace = 'payload' | 'cancelReason' | 'name' | 'key';
+/** What the store can't keep of `text` at a place (such as `'U+0000'`), or `undefined`. */
+export type TextCheck = (text: string) => string | undefined;
+/** A place's check, or `undefined` where the store keeps any text (`EncodedWorkflowStore.textCheck()`). */
+export type TextChecks = (place: TextPlace) => TextCheck | undefined;
+/** `'U+0000'` when `text` holds it (PostgreSQL keeps it in neither `text` nor `jsonb`), else `undefined`. */
+export declare function nulIn(text: string): string | undefined;
+/** `'a lone UTF-16 surrogate'` when `text` holds one (PostgreSQL and MySQL refuse it in JSON), else `undefined`. */
+export declare function loneSurrogateIn(text: string): string | undefined;
+/**
+ * The first string of a JSON value (what `JSON.parse()` returns), a value or an object's key, that `check` refuses,
+ * with its path (`$.lines[0].note`), or `undefined`. Walks with a stack of its own, so a value as deep as
+ * `JSON.stringify()` takes can't overflow the call stack; the path is built only for what it finds.
+ */
+export declare function findUnstorableText(value: unknown, check: TextCheck): {
+    path: string;
+    problem: string;
+} | undefined;
+/** Throws a `TypeError` that names `what` when `check` refuses `text`. */
+export declare function assertStorableText(what: string, text: string | null | undefined, check: TextCheck | undefined): void;
+/** The same for a JSON value (what `normalize()` returns), naming where in `what` the text sits. */
+export declare function assertStorableJson(what: string, value: unknown, check: TextCheck | undefined): void;
+/** `assertStorableJson()`'s error, for a caller that reports it in its own way, or `undefined`. */
+export declare function unstorableJson(what: string, value: unknown, check: TextCheck | undefined): TypeError | undefined;
+/**
+ * `text`, with U+0000 and lone surrogates replaced with U+FFFD when `check` refuses it: for an error's text, which is
+ * recorded whatever it holds.
+ */
+export declare function storableText(text: string, check: TextCheck | undefined): string;

package/dist/utils/storable-text.util.js

@@ -0,0 +1,96 @@
+/** `'U+0000'` when `text` holds it (PostgreSQL keeps it in neither `text` nor `jsonb`), else `undefined`. */
+export function nulIn(text) {
+    return text.includes('\u0000') ? 'U+0000' : undefined;
+}
+/** `'a lone UTF-16 surrogate'` when `text` holds one (PostgreSQL and MySQL refuse it in JSON), else `undefined`. */
+export function loneSurrogateIn(text) {
+    return text.isWellFormed() ? undefined : 'a lone UTF-16 surrogate';
+}
+/**
+ * The first string of a JSON value (what `JSON.parse()` returns), a value or an object's key, that `check` refuses,
+ * with its path (`$.lines[0].note`), or `undefined`. Walks with a stack of its own, so a value as deep as
+ * `JSON.stringify()` takes can't overflow the call stack; the path is built only for what it finds.
+ */
+export function findUnstorableText(value, check) {
+    const pending = [{ value, parent: undefined, at: undefined }];
+    for (let step = pending.pop(); step; step = pending.pop()) {
+        if (step.keyProblem) {
+            return { path: `${pathOf(step)} (its key)`, problem: step.keyProblem };
+        }
+        const current = step.value;
+        if (typeof current === 'string') {
+            const problem = check(current);
+            if (problem) {
+                return { path: pathOf(step), problem };
+            }
+        }
+        else if (Array.isArray(current)) {
+            // Last first, so the first is checked first. Numbers, booleans and null hold no text.
+            for (let i = current.length - 1; i >= 0; i--) {
+                if (holdsText(current[i])) {
+                    pending.push({ value: current[i], parent: step, at: i });
+                }
+            }
+        }
+        else if (current !== null && typeof current === 'object') {
+            const keys = Object.keys(current);
+            for (let i = keys.length - 1; i >= 0; i--) {
+                const key = keys[i];
+                const child = current[key];
+                const keyProblem = check(key);
+                if (keyProblem || holdsText(child)) {
+                    pending.push({ value: child, parent: step, at: key, keyProblem });
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/** Throws a `TypeError` that names `what` when `check` refuses `text`. */
+export function assertStorableText(what, text, check) {
+    const problem = check && typeof text === 'string' ? check(text) : undefined;
+    if (problem) {
+        throw unstorable(what, problem);
+    }
+}
+/** The same for a JSON value (what `normalize()` returns), naming where in `what` the text sits. */
+export function assertStorableJson(what, value, check) {
+    const refused = unstorableJson(what, value, check);
+    if (refused) {
+        throw refused;
+    }
+}
+/** `assertStorableJson()`'s error, for a caller that reports it in its own way, or `undefined`. */
+export function unstorableJson(what, value, check) {
+    const found = check && findUnstorableText(value, check);
+    return found ? unstorable(`${what} at ${found.path}`, found.problem) : undefined;
+}
+/**
+ * `text`, with U+0000 and lone surrogates replaced with U+FFFD when `check` refuses it: for an error's text, which is
+ * recorded whatever it holds.
+ */
+export function storableText(text, check) {
+    return check?.(text) === undefined ? text : text.replaceAll('\u0000', '�').toWellFormed();
+}
+function unstorable(where, problem) {
+    return new TypeError(`${where} holds ${problem}, which the workflow store can't keep.`);
+}
+function holdsText(value) {
+    return typeof value === 'string' || (value !== null && typeof value === 'object');
+}
+function pathOf(step) {
+    let path = '';
+    for (let at = step; at; at = at.parent) {
+        path = segment(at.at) + path;
+    }
+    return path;
+}
+function segment(at) {
+    if (at === undefined) {
+        return '$';
+    }
+    if (typeof at === 'number') {
+        return `[${at}]`;
+    }
+    return /^[A-Za-z_$][\w$]*$/.test(at) ? `.${at}` : `[${JSON.stringify(at)}]`;
+}