@nestjs/workflows 0.0.1

package/dist/testing/schedule-store.contract.d.ts

@@ -0,0 +1,33 @@
+import type { ScheduleStore } from '../core/interfaces/schedule-store.interface.js';
+export interface ScheduleStoreContractOptions {
+    /**
+     * Also run the concurrency cases: claims and saves in flight at once. Set it for a store on a connection pool (they
+     * are the cases a store without the right locks fails); a single connection serializes them, which they must
+     * survive too.
+     */
+    concurrent?: boolean;
+    /** Called after each case with the store `createStore` returned (close it, drop its tables). */
+    dispose?: (store: ScheduleStore) => unknown;
+}
+export interface ScheduleStoreContractCase {
+    name: string;
+    /** Throws on failure. */
+    run(): Promise<void>;
+}
+/**
+ * The core's `ScheduleStore` contract as test cases, for any test runner: what a store of schedules must do for the
+ * `Scheduler`, whatever it runs on (SQL, Redis scripts, memory), races included.
+ *
+ * ```ts
+ * const cases = scheduleStoreContract(async () => new RedisScheduleStore(await freshRedis()), { concurrent: true });
+ * for (const c of cases) it(c.name, c.run);
+ * ```
+ *
+ * `createStore` is called once per case and must return a store without schedules.
+ */
+export declare function scheduleStoreContract(createStore: () => ScheduleStore | Promise<ScheduleStore>, options?: ScheduleStoreContractOptions): ScheduleStoreContractCase[];
+/**
+ * @internal The contract's cases, by `group`, added with `add`: `workflowStoreContract()` runs them on a workflow
+ * store's schedules.
+ */
+export declare function scheduleCases(add: (name: string, run: (store: ScheduleStore) => Promise<void>) => void, group: 'base' | 'concurrent'): void;

package/dist/testing/schedule-store.contract.js

@@ -0,0 +1,161 @@
+import { randomUUID } from 'node:crypto';
+import { equal, expect, jitter } from './assertions.js';
+/**
+ * The core's `ScheduleStore` contract as test cases, for any test runner: what a store of schedules must do for the
+ * `Scheduler`, whatever it runs on (SQL, Redis scripts, memory), races included.
+ *
+ * ```ts
+ * const cases = scheduleStoreContract(async () => new RedisScheduleStore(await freshRedis()), { concurrent: true });
+ * for (const c of cases) it(c.name, c.run);
+ * ```
+ *
+ * `createStore` is called once per case and must return a store without schedules.
+ */
+export function scheduleStoreContract(createStore, options = {}) {
+    const cases = [];
+    const add = (name, run) => cases.push({
+        name,
+        run: async () => {
+            const store = await createStore();
+            try {
+                await run(store);
+            }
+            finally {
+                await options.dispose?.(store);
+            }
+        },
+    });
+    scheduleCases(add, 'base');
+    if (options.concurrent) {
+        scheduleCases(add, 'concurrent');
+    }
+    return cases;
+}
+/**
+ * @internal The contract's cases, by `group`, added with `add`: `workflowStoreContract()` runs them on a workflow
+ * store's schedules.
+ */
+export function scheduleCases(add, group) {
+    if (group === 'concurrent') {
+        add('concurrent claimSchedules() never return the same schedule twice, and saves of one revision land once', async (store) => {
+            for (let i = 0; i < 40; i++) {
+                await store.saveSchedule(schedule(`s${String(i).padStart(2, '0')}`, { wakeAt: i }));
+            }
+            const owners = new Map();
+            const claimer = async (owner) => {
+                for (;;) {
+                    const claimed = await store.claimSchedules({ owner, token: randomUUID(), now: 1_000, leaseUntil: FAR, limit: 3, targets: [TARGET] });
+                    if (claimed.length === 0) {
+                        return;
+                    }
+                    for (const record of claimed) {
+                        if (owners.has(record.id)) {
+                            throw new Error(`${record.id} was claimed by ${owners.get(record.id)} and ${owner}`);
+                        }
+                        owners.set(record.id, owner);
+                    }
+                    await jitter();
+                }
+            };
+            await Promise.all(['c1', 'c2', 'c3', 'c4', 'c5'].map(claimer));
+            equal(owners.size, 40, 'every schedule claimed');
+            const saves = await Promise.all(Array.from({ length: 8 }, (_, i) => jitter().then(() => store.saveSchedule(schedule('s00', { paused: true, now: 2_000 + i, expectRevision: 1 })))));
+            equal(saves.filter((saved) => saved !== null).length, 1, 'one save at revision 1');
+            const inserts = await Promise.all(Array.from({ length: 8 }, () => jitter().then(() => store.saveSchedule(schedule('new')))));
+            equal(inserts.filter((saved) => saved !== null).length, 1, 'one insert');
+        });
+        return;
+    }
+    add('saveSchedule() creates a schedule once, and replaces one only at the revision it read', async (store) => {
+        const payload = { tenant: "O'Reilly — ü 🚀", ids: [1, null], empty: '' };
+        const created = await store.saveSchedule(schedule('s1', { payload, now: 10 }));
+        expect(created, { id: 's1', target: TARGET, declared: false, spec: SPEC, payload, paused: false, wakeAt: 100, state: { next: 100, runs: 0 }, revision: 1, leaseOwner: null, leaseUntil: null, createdAt: 10, updatedAt: 10 }, 'the new schedule');
+        equal(await store.saveSchedule(schedule('s1', { now: 11 })), null, 'a second insert');
+        equal(await store.getSchedule('s1'), created, 'getSchedule()');
+        equal(await store.getSchedule('missing'), null, 'an unknown id');
+        const replaced = await store.saveSchedule(schedule('s1', { paused: true, payload: null, wakeAt: null, declared: true, now: 20, expectRevision: 1 }));
+        expect(replaced, { revision: 2, paused: true, payload: null, wakeAt: null, declared: true, createdAt: 10, updatedAt: 20 }, 'replaced at revision 1');
+        equal(await store.saveSchedule(schedule('s1', { now: 21, expectRevision: 1 })), null, 'a save at a stale revision');
+        equal(await store.saveSchedule(schedule('other', { now: 21, expectRevision: 1 })), null, 'a save of an unknown id');
+        expect(await store.getSchedule('s1'), { revision: 2, paused: true, updatedAt: 20 }, 'unchanged by them');
+        const encoded = await store.saveSchedule(schedule('s2', { payload: '$wf1:aes-256-gcm:k1.Zm9v' }));
+        equal(encoded?.payload, '$wf1:aes-256-gcm:k1.Zm9v', 'a string payload, as it is');
+    });
+    add('listSchedules() filters by target and declared, and pages by id; deleteSchedule() deletes at a revision, or any', async (store) => {
+        for (const [id, target, declared] of [['c', TARGET, true], ['a', TARGET, false], ['b', OTHER, true], ['d', TARGET, false]]) {
+            await store.saveSchedule(schedule(id, { target, declared }));
+        }
+        const ids = async (query = {}) => (await store.listSchedules({ limit: 100, offset: 0, ...query })).map((s) => s.id);
+        equal(await ids(), ['a', 'b', 'c', 'd'], 'every schedule, by id');
+        equal(await ids({ target: TARGET }), ['a', 'c', 'd'], 'by target');
+        equal(await ids({ declared: true }), ['b', 'c'], 'the declared ones');
+        equal(await ids({ target: TARGET, declared: false }), ['a', 'd'], 'by both');
+        equal(await ids({ target: TARGET, limit: 1, offset: 1 }), ['c'], 'a page');
+        equal(await store.deleteSchedule('a', 2), false, 'at another revision');
+        equal(await store.deleteSchedule('a', 1), true, 'at its revision');
+        equal(await store.deleteSchedule('c'), true, 'at any revision');
+        equal(await store.deleteSchedule('c'), false, 'already gone');
+        equal(await ids(), ['b', 'd'], 'the rest');
+        expect(await store.saveSchedule(schedule('a')), { revision: 1 }, 'the id, free again');
+    });
+    add('claimSchedules() leases due, unpaused, unleased schedules of the given targets, most overdue first', async (store) => {
+        await store.saveSchedule(schedule('late', { wakeAt: 50 }));
+        await store.saveSchedule(schedule('early', { wakeAt: 10 }));
+        await store.saveSchedule(schedule('paused', { wakeAt: 10, paused: true }));
+        await store.saveSchedule(schedule('ended', { wakeAt: null }));
+        await store.saveSchedule(schedule('future', { wakeAt: 5_000 }));
+        await store.saveSchedule(schedule('others', { wakeAt: 20, target: OTHER }));
+        const claim = (now, o = {}) => store.claimSchedules({ owner: o.owner ?? 'w1', token: o.token ?? randomUUID(), now, leaseUntil: now + 1_000, limit: o.limit ?? 100, targets: o.targets ?? [TARGET] });
+        const first = await claim(100, { token: 't1' });
+        equal(first.map((s) => s.id), ['early', 'late'], 'due and unpaused, by wakeAt');
+        expect(first[0], { leaseOwner: 'w1', leaseUntil: 1_100, revision: 1, updatedAt: 0 }, 'leased, nothing else changed');
+        equal(await claim(1_100), [], 'leased until 1100 inclusive');
+        equal((await claim(1_101, { owner: 'w2' })).map((s) => [s.id, s.leaseOwner]), [['early', 'w2'], ['late', 'w2']], 'claimed again once the lease expired');
+        equal((await claim(1_101, { targets: [OTHER, 'unknown'] })).map((s) => s.id), ['others'], 'only the given targets');
+        equal((await claim(9_000, { limit: 1 })).map((s) => s.id), ['early'], 'at most limit');
+    });
+    add('writeSchedule() writes only under the lease token, and a save that releases the lease makes the token stale', async (store) => {
+        await store.saveSchedule(schedule('s', { wakeAt: 10 }));
+        const claim = (now, token) => store.claimSchedules({ owner: 'w1', token, now, leaseUntil: now + 1_000, limit: 10, targets: [TARGET] });
+        await claim(10, 't1');
+        const state = { next: 500, runs: 1, pending: [{ at: 10, cancel: [] }] };
+        equal(await store.writeSchedule('s', 't1', { now: 11, state, wakeAt: 11, release: false }), true, 'the lease holder');
+        expect(await store.getSchedule('s'), { state, wakeAt: 11, revision: 2, updatedAt: 11, leaseUntil: 1_010 }, 'written, still leased');
+        equal(await store.writeSchedule('s', 'other', { now: 12, state: {}, wakeAt: 0, release: true }), false, 'another token');
+        equal(await store.writeSchedule('missing', 't1', { now: 12, state: {}, wakeAt: 0, release: true }), false, 'an unknown id');
+        // A save that keeps the lease (a pause) leaves the holder its write, which keeps the save's fields.
+        const current = (await store.getSchedule('s'));
+        await store.saveSchedule(schedule('s', { paused: true, wakeAt: current.wakeAt, state: current.state, now: 13, expectRevision: current.revision }));
+        equal(await store.writeSchedule('s', 't1', { now: 14, state: { next: 500, runs: 1, pending: [] }, wakeAt: 500, release: true }), true, 'after a save that kept the lease');
+        expect(await store.getSchedule('s'), { paused: true, wakeAt: 500, revision: 4, leaseUntil: null, state: { pending: [] } }, 'released, still paused');
+        equal(await claim(600, 't2'), [], 'a paused schedule is not claimed');
+        await store.saveSchedule(schedule('s', { paused: false, wakeAt: 600, now: 15, expectRevision: 4 }));
+        equal((await claim(600, 't3')).map((s) => s.id), ['s'], 'resumed');
+        await store.saveSchedule(schedule('s', { wakeAt: 700, now: 16, expectRevision: 5, releaseLease: true }));
+        equal(await store.writeSchedule('s', 't3', { now: 17, state: {}, wakeAt: 0, release: true }), false, 'the token of a lease a save released');
+        expect(await store.getSchedule('s'), { wakeAt: 700, leaseUntil: null, revision: 6 }, "the save's");
+        equal((await claim(700, 't4')).map((s) => s.id), ['s'], 'claimable at once');
+    });
+}
+const FAR = 9_000_000_000_000; // a deadline nobody reaches in a test
+const TARGET = 'order-fulfilment';
+const OTHER = 'invoice-batch';
+/** A schedule's spec, as the scheduler stores it: JSON the store keeps as it is. */
+const SPEC = { cron: '0 0 8 * * MON', tz: 'Europe/Warsaw', startAt: null, limit: 52, missed: 'once', overlap: 'buffer-one' };
+/** `saveSchedule()`'s argument for a schedule of `TARGET`, due at 100, to insert unless `expectRevision` says otherwise. */
+function schedule(id, o = {}) {
+    return {
+        id,
+        target: TARGET,
+        declared: false,
+        spec: SPEC,
+        payload: null,
+        paused: false,
+        wakeAt: 100,
+        state: { next: 100, runs: 0, pending: [] },
+        expectRevision: null,
+        releaseLease: false,
+        now: 0,
+        ...o,
+    };
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,7 @@
+export * from './run-timeout.util.js';
+export * from './schedule-spec.util.js';
+export * from './serialize-error.util.js';
+export * from './step-scope.util.js';
+export * from './journal-limits.util.js';
+export * from './new-instance.util.js';
+export * from './normalize.util.js';

package/dist/utils/index.js

@@ -0,0 +1,7 @@
+export * from './run-timeout.util.js';
+export * from './schedule-spec.util.js';
+export * from './serialize-error.util.js';
+export * from './step-scope.util.js';
+export * from './journal-limits.util.js';
+export * from './new-instance.util.js';
+export * from './normalize.util.js';

package/dist/utils/journal-limits.util.d.ts

@@ -0,0 +1,6 @@
+import type { WorkflowJournalLimits } from '../interfaces/workflows-module-options.interface.js';
+export declare const DEFAULT_JOURNAL_LIMITS: Required<WorkflowJournalLimits>;
+/** The module's `journal` option over the defaults; throws for a limit that isn't a positive number. */
+export declare function resolveJournalLimits(limits?: WorkflowJournalLimits): Required<WorkflowJournalLimits>;
+/** An entry's size as the journal stores it: UTF-8 JSON. */
+export declare function entryBytes(entry: unknown): number;

package/dist/utils/journal-limits.util.js

@@ -0,0 +1,25 @@
+export const DEFAULT_JOURNAL_LIMITS = {
+    warnEntries: 1_000,
+    warnBytes: 1_000_000,
+    maxEntries: 10_000,
+    maxBytes: 10_000_000,
+};
+/** The module's `journal` option over the defaults; throws for a limit that isn't a positive number. */
+export function resolveJournalLimits(limits = {}) {
+    const resolved = { ...DEFAULT_JOURNAL_LIMITS };
+    for (const key of Object.keys(DEFAULT_JOURNAL_LIMITS)) {
+        const value = limits[key];
+        if (value === undefined) {
+            continue;
+        }
+        if (typeof value !== 'number' || Number.isNaN(value) || value <= 0) {
+            throw new TypeError(`journal.${key} (${String(value)}) must be a positive number, or Infinity to turn the check off.`);
+        }
+        resolved[key] = value;
+    }
+    return resolved;
+}
+/** An entry's size as the journal stores it: UTF-8 JSON. */
+export function entryBytes(entry) {
+    return Buffer.byteLength(JSON.stringify(entry) ?? '', 'utf8');
+}

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

@@ -0,0 +1,26 @@
+import type { WorkflowMetadata } from '../interfaces/workflow-decorator-options.interface.js';
+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';
+export interface NewInstanceOptions {
+    caller: string;
+    now: number;
+    timeout?: Duration;
+    concurrencyKey?: string;
+    rateLimitKey?: string;
+    priority?: number;
+    parentId?: string;
+    parentClose?: WorkflowParentClose;
+    scheduleId?: string;
+    scheduledAt?: number;
+}
+/** What `WorkflowClient.start()` and `ctx.startChild()` ask the store to create. */
+export declare function newInstance(workflow: WorkflowMetadata, id: unknown, input: unknown, options: NewInstanceOptions): NewWorkflowInstance;
+/**
+ * Throws `WorkflowIdConflictError` when the instance `create()` found under the id isn't the one
+ * asked for: another workflow, another input (when `input`), or another parent (when `parent`).
+ */
+export declare function assertSameInstance(existing: WorkflowInstance, wanted: NewWorkflowInstance, compare: {
+    input: boolean;
+    parent: boolean;
+}): void;

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

@@ -0,0 +1,87 @@
+import { WorkflowIdConflictError } from '../errors/workflow-id-conflict.error.js';
+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';
+/** 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}\`.`);
+    }
+    if (options.priority !== undefined) {
+        assertPriority(options.priority, options.caller);
+    }
+    const json = normalize(input);
+    const timeoutMs = options.timeout === undefined ? workflow.timeout : runTimeoutMs(options.timeout, options.caller);
+    return {
+        id,
+        workflow: workflow.name,
+        version: workflow.version,
+        input: json,
+        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),
+        priority: options.priority ?? 0,
+        scheduleId: options.scheduleId ?? null,
+        scheduledAt: options.scheduledAt ?? null,
+        now: options.now,
+    };
+}
+const LIMITS = {
+    concurrency: { option: 'concurrencyKey', limit: 'concurrency limit', key: 'concurrency key', declare: '{ concurrency: { limit, key } }' },
+    rateLimit: { option: 'rateLimitKey', limit: 'rate limit', key: 'rate limit key', declare: '{ rateLimit: { max, duration, key } }' },
+};
+/**
+ * The instance's key for its workflow's per-key concurrency or rate limit: the start's, else the one the limit's
+ * `key` computes from the input.
+ */
+function keyOf(workflow, input, caller, kind, given) {
+    const limit = workflow[kind];
+    const { option, limit: what, key: named, declare } = LIMITS[kind];
+    if (given !== undefined) {
+        if (typeof given !== 'string' || given.length === 0) {
+            throw new TypeError(`${caller}: invalid ${option} ${JSON.stringify(given)}. Use a non-empty string.`);
+        }
+        // Unknown here (started by name from a process that doesn't register it): the key stands.
+        if (limit !== undefined && limit?.perKey == null) {
+            throw new TypeError(`${caller}: workflow "${workflow.name}" has no ${what} per key, so ${option} would count for nothing. Declare one with @Workflow(name, ${declare}).`);
+        }
+        return given;
+    }
+    if (!limit?.key) {
+        return null;
+    }
+    let key;
+    try {
+        key = limit.key(input);
+    }
+    catch (error) {
+        throw new TypeError(`The ${named} of workflow "${workflow.name}" threw: ${error?.message ?? String(error)}`);
+    }
+    if (key === null || key === undefined) {
+        return null;
+    }
+    if (typeof key !== 'string' || key.length === 0) {
+        throw new TypeError(`The ${named} of workflow "${workflow.name}" returned ${JSON.stringify(key)}. Return a non-empty string, or null for none.`);
+    }
+    return key;
+}
+/**
+ * Throws `WorkflowIdConflictError` when the instance `create()` found under the id isn't the one
+ * asked for: another workflow, another input (when `input`), or another parent (when `parent`).
+ */
+export function assertSameInstance(existing, wanted, compare) {
+    if (existing.workflow !== wanted.workflow) {
+        throw new WorkflowIdConflictError(`Instance "${wanted.id}" already exists for workflow "${existing.workflow}", not "${wanted.workflow}".`);
+    }
+    if (compare.parent && existing.parentId !== (wanted.parentId ?? null)) {
+        const parent = existing.parentId === null ? 'no parent' : `parent "${existing.parentId}"`;
+        throw new WorkflowIdConflictError(`Instance "${wanted.id}" of "${wanted.workflow}" already exists with ${parent}.`);
+    }
+    // A store may read an `undefined` input back as `null`.
+    if (compare.input && canonical(existing.input ?? null) !== canonical(wanted.input ?? null)) {
+        throw new WorkflowIdConflictError(`Instance "${wanted.id}" of "${wanted.workflow}" already exists with a different input.`);
+    }
+}

package/dist/utils/normalize.util.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Round-trips through JSON so the first run sees exactly what every replay
+ * will see (a `Date` becomes a string in both, `undefined` stays `undefined`).
+ */
+export declare function normalize<T>(value: T): T;

package/dist/utils/normalize.util.js

@@ -0,0 +1,11 @@
+/**
+ * Round-trips through JSON so the first run sees exactly what every replay
+ * will see (a `Date` becomes a string in both, `undefined` stays `undefined`).
+ */
+export function normalize(value) {
+    if (value === undefined) {
+        return value;
+    }
+    const json = JSON.stringify(value);
+    return json === undefined ? undefined : JSON.parse(json);
+}

package/dist/utils/run-timeout.util.d.ts

@@ -0,0 +1,3 @@
+import { type Duration } from '../core/time/duration.js';
+/** A workflow's run timeout in milliseconds: a zero one would time out before the first step. */
+export declare function runTimeoutMs(timeout: Duration, owner: string): number;

package/dist/utils/run-timeout.util.js

@@ -0,0 +1,15 @@
+import { parseDuration } from '../core/time/duration.js';
+/** A workflow's run timeout in milliseconds: a zero one would time out before the first step. */
+export function runTimeoutMs(timeout, owner) {
+    let ms;
+    try {
+        ms = parseDuration(timeout);
+    }
+    catch {
+        ms = 0;
+    }
+    if (ms <= 0) {
+        throw new TypeError(`Invalid timeout ${JSON.stringify(timeout)} for ${owner}. Use a positive duration, such as "30d".`);
+    }
+    return ms;
+}

package/dist/utils/schedule-spec.util.d.ts

@@ -0,0 +1,16 @@
+import type { ScheduleSpec } from '../core/interfaces/schedule.interface.js';
+import type { WorkflowScheduleOptions } from '../interfaces/workflow-schedule.interface.js';
+/** A workflow schedule's spec as the engine stores it (`WorkflowScheduleRecord.spec`): the core's, and what it starts. */
+export interface WorkflowScheduleSpec extends ScheduleSpec {
+    /** The priority of the instances it starts: `0` for none. */
+    priority: number;
+    /** The pinned version, or `null`: the highest the starting worker registers. */
+    version: number | null;
+    /** The input is a function of the occurrence (a declared schedule): only a worker that declares it can compute it. */
+    inputFn: boolean;
+}
+/** Checks a schedule's options and returns its spec; throws a `TypeError` that names `owner` for anything invalid. */
+export declare function scheduleSpec(owner: string, options: WorkflowScheduleOptions, extra: {
+    version: number | null;
+    inputFn: boolean;
+}): WorkflowScheduleSpec;

package/dist/utils/schedule-spec.util.js

@@ -0,0 +1,9 @@
+import { assertPriority } from '../core/limits/limits.js';
+import { parseSchedule } from '../core/scheduling/schedule-spec.js';
+/** Checks a schedule's options and returns its spec; throws a `TypeError` that names `owner` for anything invalid. */
+export function scheduleSpec(owner, options, extra) {
+    const spec = parseSchedule(options, owner);
+    const priority = options.priority ?? 0;
+    assertPriority(priority, owner);
+    return { ...spec, priority, ...extra };
+}

package/dist/utils/schedule-store.util.d.ts

@@ -0,0 +1,15 @@
+import type { ScheduleStore } from '../core/interfaces/schedule-store.interface.js';
+import type { WorkflowStore } from '../interfaces/workflow-store.interface.js';
+/** The `WorkflowStore` methods that hold schedules: the core's `ScheduleStore`, in workflows' words. */
+export type WorkflowScheduleMethods = 'saveSchedule' | 'getSchedule' | 'listSchedules' | 'deleteSchedule' | 'claimSchedules' | 'writeSchedule';
+/**
+ * A workflow store's schedules as the core's `ScheduleStore`, for its `Scheduler`: a schedule's workflow is its
+ * target, and its input its payload. `store` is read at each call (the registered store), so it sees what the store's
+ * methods are then.
+ */
+export declare function workflowScheduleStore(store: () => Pick<WorkflowStore, WorkflowScheduleMethods>): ScheduleStore;
+/**
+ * A core `ScheduleStore` as a workflow store's schedule methods: how the in-memory workflow store keeps its schedules
+ * in the core's `InMemoryScheduleStore`.
+ */
+export declare function workflowScheduleMethods(store: ScheduleStore): Pick<WorkflowStore, WorkflowScheduleMethods>;

package/dist/utils/schedule-store.util.js

@@ -0,0 +1,44 @@
+/**
+ * A workflow store's schedules as the core's `ScheduleStore`, for its `Scheduler`: a schedule's workflow is its
+ * target, and its input its payload. `store` is read at each call (the registered store), so it sees what the store's
+ * methods are then.
+ */
+export function workflowScheduleStore(store) {
+    return {
+        saveSchedule: async (save) => orNull(await store().saveSchedule(toWorkflowsSave(save)), fromWorkflows),
+        getSchedule: async (id) => orNull(await store().getSchedule(id), fromWorkflows),
+        listSchedules: async ({ target, ...query }) => (await store().listSchedules({ ...query, ...(target === undefined ? {} : { workflow: target }) })).map(fromWorkflows),
+        deleteSchedule: (id, revision) => store().deleteSchedule(id, revision),
+        claimSchedules: async ({ targets, ...request }) => (await store().claimSchedules({ ...request, workflows: targets })).map(fromWorkflows),
+        writeSchedule: (id, token, write) => store().writeSchedule(id, token, write),
+    };
+}
+/**
+ * A core `ScheduleStore` as a workflow store's schedule methods: how the in-memory workflow store keeps its schedules
+ * in the core's `InMemoryScheduleStore`.
+ */
+export function workflowScheduleMethods(store) {
+    return {
+        saveSchedule: async (save) => orNull(await store.saveSchedule(fromWorkflowsSave(save)), toWorkflows),
+        getSchedule: async (id) => orNull(await store.getSchedule(id), toWorkflows),
+        listSchedules: async ({ workflow, ...query }) => (await store.listSchedules({ ...query, ...(workflow === undefined ? {} : { target: workflow }) })).map(toWorkflows),
+        deleteSchedule: (id, revision) => store.deleteSchedule(id, revision),
+        claimSchedules: async ({ workflows, ...request }) => (await store.claimSchedules({ ...request, targets: workflows })).map(toWorkflows),
+        writeSchedule: (id, token, write) => store.writeSchedule(id, token, write),
+    };
+}
+function toWorkflowsSave({ target, payload, ...save }) {
+    return { ...save, workflow: target, input: payload };
+}
+function fromWorkflowsSave({ workflow, input, ...save }) {
+    return { ...save, target: workflow, payload: input };
+}
+function fromWorkflows({ workflow, input, ...record }) {
+    return { ...record, target: workflow, payload: input };
+}
+function toWorkflows({ target, payload, ...record }) {
+    return { ...record, workflow: target, input: payload };
+}
+function orNull(value, map) {
+    return value === null ? null : map(value);
+}

package/dist/utils/serialize-error.util.d.ts

@@ -0,0 +1,7 @@
+import type { SerializedWorkflowError } from '../interfaces/serialized-workflow-error.interface.js';
+/**
+ * Never throws: a thrown value the engine can't serialize (a circular object, a
+ * BigInt, `undefined`) is described by `util.inspect()` instead, so the instance
+ * still records an outcome.
+ */
+export declare function serializeError(error: unknown): SerializedWorkflowError;

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

@@ -0,0 +1,22 @@
+import { inspect } from 'node:util';
+/**
+ * Never throws: a thrown value the engine can't serialize (a circular object, a
+ * BigInt, `undefined`) is described by `util.inspect()` instead, so the instance
+ * still records an outcome.
+ */
+export function serializeError(error) {
+    if (error instanceof Error) {
+        return { name: error.name || 'Error', message: String(error.message), stack: error.stack };
+    }
+    if (typeof error === 'string') {
+        return { name: 'Error', message: error };
+    }
+    let message;
+    try {
+        message = JSON.stringify(error);
+    }
+    catch {
+        // circular, or a BigInt: described below
+    }
+    return { name: 'Error', message: message ?? inspect(error, { depth: 3, breakLength: Infinity }) };
+}

package/dist/utils/step-scope.util.d.ts

@@ -0,0 +1,16 @@
+/** Runs a step attempt's function, so the signals it sends and the workflows it starts can derive their ids from the step. */
+export declare function runInStepScope<T>(idempotencyKey: string, fn: () => T): T;
+/**
+ * The dedupe id of a signal sent without one from inside a step, directly or through a mapped
+ * event: the step's `idempotencyKey`, the key, and how many signals with this name and key the
+ * attempt sent before it. A retried attempt sends the same ids in the same order, so the store
+ * keeps each signal once. `undefined` outside a step.
+ */
+export declare function stepSignalId(name: string, key: string | null): string | undefined;
+/**
+ * The id of a workflow started without one from inside a step: the step's `idempotencyKey`, the
+ * workflow's name, and how many instances of that workflow the attempt started before it. A
+ * retried attempt starts the same ids in the same order, so it gets its first instances back
+ * instead of new ones. `undefined` outside a step.
+ */
+export declare function stepStartId(workflow: string): string | undefined;

package/dist/utils/step-scope.util.js

@@ -0,0 +1,38 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const scope = new AsyncLocalStorage();
+/** Runs a step attempt's function, so the signals it sends and the workflows it starts can derive their ids from the step. */
+export function runInStepScope(idempotencyKey, fn) {
+    return scope.run({ idempotencyKey, signals: new Map(), starts: new Map() }, fn);
+}
+/**
+ * The dedupe id of a signal sent without one from inside a step, directly or through a mapped
+ * event: the step's `idempotencyKey`, the key, and how many signals with this name and key the
+ * attempt sent before it. A retried attempt sends the same ids in the same order, so the store
+ * keeps each signal once. `undefined` outside a step.
+ */
+export function stepSignalId(name, key) {
+    const step = scope.getStore();
+    if (!step) {
+        return undefined;
+    }
+    const counter = JSON.stringify([name, key]);
+    const n = (step.signals.get(counter) ?? 0) + 1;
+    step.signals.set(counter, n);
+    // JSON keeps the parts apart whatever they contain.
+    return JSON.stringify([step.idempotencyKey, key, n]);
+}
+/**
+ * The id of a workflow started without one from inside a step: the step's `idempotencyKey`, the
+ * workflow's name, and how many instances of that workflow the attempt started before it. A
+ * retried attempt starts the same ids in the same order, so it gets its first instances back
+ * instead of new ones. `undefined` outside a step.
+ */
+export function stepStartId(workflow) {
+    const step = scope.getStore();
+    if (!step) {
+        return undefined;
+    }
+    const n = (step.starts.get(workflow) ?? 0) + 1;
+    step.starts.set(workflow, n);
+    return JSON.stringify([step.idempotencyKey, workflow, n]);
+}

package/dist/workflows.constants.d.ts

@@ -0,0 +1,10 @@
+export declare const WORKFLOW_METADATA = "workflows:workflow";
+/**
+ * The signal a child instance sends its parent when it ends, keyed by the child's id. Signal names
+ * starting with "$" are the engine's: `WorkflowSignal` and `WorkflowClient.signal()` refuse them.
+ */
+export declare const CHILD_ENDED_SIGNAL = "$child-ended";
+/** `@StartOn()` and `@SignalOn()` (`@nestjs/workflows/cqrs`) on a workflow class. */
+export declare const WORKFLOW_EVENT_ROUTES_METADATA = "workflows:event-routes";
+/** The module's payload codecs, resolved (`WorkflowsModuleOptions.codec`). */
+export declare const WORKFLOW_PAYLOAD_CODECS: unique symbol;

package/dist/workflows.constants.js

@@ -0,0 +1,10 @@
+export const WORKFLOW_METADATA = 'workflows:workflow';
+/**
+ * The signal a child instance sends its parent when it ends, keyed by the child's id. Signal names
+ * starting with "$" are the engine's: `WorkflowSignal` and `WorkflowClient.signal()` refuse them.
+ */
+export const CHILD_ENDED_SIGNAL = '$child-ended';
+/** `@StartOn()` and `@SignalOn()` (`@nestjs/workflows/cqrs`) on a workflow class. */
+export const WORKFLOW_EVENT_ROUTES_METADATA = 'workflows:event-routes';
+/** The module's payload codecs, resolved (`WorkflowsModuleOptions.codec`). */
+export const WORKFLOW_PAYLOAD_CODECS = Symbol('WORKFLOW_PAYLOAD_CODECS');

package/dist/workflows.module-definition.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowsModuleOptions } from './interfaces/workflows-module-options.interface.js';
+export declare const ConfigurableModuleClass: import("@nestjs/common").ConfigurableModuleCls<WorkflowsModuleOptions, "forRoot", "createWorkflowsOptions", {
+    isGlobal?: boolean;
+}>, WORKFLOWS_MODULE_OPTIONS: string | symbol;

package/dist/workflows.module-definition.js

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from '@nestjs/common';
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN: WORKFLOWS_MODULE_OPTIONS } = new ConfigurableModuleBuilder({ moduleName: 'Workflows' })
+    .setClassMethodName('forRoot')
+    .setFactoryMethodName('createWorkflowsOptions')
+    .setExtras({ isGlobal: true }, (definition, { isGlobal }) => ({ ...definition, global: isGlobal }))
+    .build();