@nestjs/workflows 0.0.1

package/dist/stores/in-memory-workflow.store.d.ts

@@ -0,0 +1,75 @@
+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';
+/**
+ * The default store, used when no source is registered: everything lives in this process's
+ * memory, so it is lost on restart and not shared with other instances of the application.
+ * Also the store for tests: `overrideProvider(YourStore).useValue(new InMemoryWorkflowStore())`
+ * (a plain instance doesn't register, so the default applies), or register one instance with
+ * `WorkflowStorage.registerSource(store, { replace: true })` in several applications of one
+ * test to share its "database" between them, as a restart would.
+ *
+ * Every method does its work synchronously before its first `await`, so calls never
+ * interleave: claims, fenced writes and signals are atomic without locks. Values are copied
+ * on the way in and out, as a database would.
+ *
+ * It can't join your database's transactions: `createInTransaction()` and
+ * `signalInTransaction()` (`start()` and `signal()` with `{ transaction }`) write at once, so
+ * a rollback doesn't undo them, and the first call logs a warning (once per store).
+ */
+export declare class InMemoryWorkflowStore implements WorkflowStore {
+    private static readonly logger;
+    private readonly rows;
+    private readonly signalLog;
+    /** Rate-limit windows by `JSON.stringify([workflow])` or `JSON.stringify([workflow, key])`. */
+    private readonly windows;
+    /** The schedules: the core's in-memory store, in workflows' words. */
+    private readonly scheduleStore;
+    private readonly scheduleMethods;
+    private warnedAboutTransactions;
+    /** `create()`, at once: it can't join `transaction` (see the class). */
+    createInTransaction(transaction: unknown, i: NewWorkflowInstance): Promise<{
+        instance: WorkflowInstance;
+        created: boolean;
+    }>;
+    /** `signal()`, at once: it can't join `transaction` (see the class). */
+    signalInTransaction(transaction: unknown, s: NewWorkflowSignal): Promise<WorkflowSignalResult>;
+    private cannotJoin;
+    create(i: NewWorkflowInstance): Promise<{
+        instance: WorkflowInstance;
+        created: boolean;
+    }>;
+    get(id: string, options?: {
+        journal?: boolean;
+    }): Promise<WorkflowInstanceDetails | null>;
+    list(query: WorkflowListQuery): Promise<WorkflowInstance[]>;
+    requestCancel(id: string, { reason, now, terminate }: WorkflowCancelRequest): Promise<boolean>;
+    reopen(id: string, r: WorkflowReopen): Promise<boolean>;
+    delete(id: string, statuses: WorkflowStatus[]): Promise<boolean>;
+    signal(s: NewWorkflowSignal): Promise<WorkflowSignalResult>;
+    private record;
+    signals(query: WorkflowSignalQuery): Promise<WorkflowSignalRecord[]>;
+    purge(query: WorkflowPurgeQuery): Promise<WorkflowPurgeResult>;
+    saveSchedule(save: WorkflowScheduleSave): Promise<WorkflowScheduleRecord | null>;
+    getSchedule(id: string): Promise<WorkflowScheduleRecord | null>;
+    listSchedules(query: WorkflowScheduleQuery): Promise<WorkflowScheduleRecord[]>;
+    deleteSchedule(id: string, revision?: number): Promise<boolean>;
+    claimSchedules(request: WorkflowScheduleClaimRequest): Promise<WorkflowScheduleRecord[]>;
+    writeSchedule(id: string, token: string, write: WorkflowScheduleWrite): Promise<boolean>;
+    claim(request: WorkflowClaimRequest): Promise<WorkflowClaim>;
+    /**
+     * The staged pick of `WorkflowStore.claim()` under limits: candidates with no room at all are passed over first;
+     * then each concurrency key keeps its first candidates, as many as it has free slots; of those, each rate-limit
+     * key as many as its window has room for; of those, each workflow as many as both its free slots and its window
+     * allow; then the first `limit`.
+     */
+    private pick;
+    /** Records the claims of `claimed` in their rate-limit windows, starting a window where the last one ended. */
+    private recordWindows;
+    renew(id: string, token: string, leaseUntil: number): Promise<{
+        cancelRequested: boolean;
+        terminateRequested: boolean;
+    } | null>;
+    write(id: string, token: string, w: WorkflowWrite): Promise<boolean>;
+    private leased;
+    private lastSignalId;
+}

package/dist/stores/in-memory-workflow.store.js

@@ -0,0 +1,380 @@
+import { Logger } from '@nestjs/common';
+import { rateWindowRoom, takeRateWindow } from '../core/limits/limits.js';
+import { InMemoryScheduleStore } from '../core/scheduling/in-memory-schedule.store.js';
+import { workflowScheduleMethods } from '../utils/schedule-store.util.js';
+const RUNNABLE = new Set(['pending', 'running', 'suspended', 'compensating']);
+const FINISHED = new Set(['completed', 'failed', 'cancelled', 'compensation_failed']);
+const CANCELLABLE = new Set(['pending', 'running', 'suspended']);
+/**
+ * The default store, used when no source is registered: everything lives in this process's
+ * memory, so it is lost on restart and not shared with other instances of the application.
+ * Also the store for tests: `overrideProvider(YourStore).useValue(new InMemoryWorkflowStore())`
+ * (a plain instance doesn't register, so the default applies), or register one instance with
+ * `WorkflowStorage.registerSource(store, { replace: true })` in several applications of one
+ * test to share its "database" between them, as a restart would.
+ *
+ * Every method does its work synchronously before its first `await`, so calls never
+ * interleave: claims, fenced writes and signals are atomic without locks. Values are copied
+ * on the way in and out, as a database would.
+ *
+ * It can't join your database's transactions: `createInTransaction()` and
+ * `signalInTransaction()` (`start()` and `signal()` with `{ transaction }`) write at once, so
+ * a rollback doesn't undo them, and the first call logs a warning (once per store).
+ */
+export class InMemoryWorkflowStore {
+    constructor() {
+        this.rows = new Map();
+        this.signalLog = [];
+        /** Rate-limit windows by `JSON.stringify([workflow])` or `JSON.stringify([workflow, key])`. */
+        this.windows = new Map();
+        /** The schedules: the core's in-memory store, in workflows' words. */
+        this.scheduleStore = new InMemoryScheduleStore();
+        this.scheduleMethods = workflowScheduleMethods(this.scheduleStore);
+        this.warnedAboutTransactions = false;
+    }
+    /** `create()`, at once: it can't join `transaction` (see the class). */
+    async createInTransaction(transaction, i) {
+        this.cannotJoin('createInTransaction');
+        return this.create(i);
+    }
+    /** `signal()`, at once: it can't join `transaction` (see the class). */
+    async signalInTransaction(transaction, s) {
+        this.cannotJoin('signalInTransaction');
+        return this.signal(s);
+    }
+    cannotJoin(method) {
+        if (this.warnedAboutTransactions) {
+            return;
+        }
+        this.warnedAboutTransactions = true;
+        InMemoryWorkflowStore.logger.warn(`InMemoryWorkflowStore.${method}() received your transaction handle, and can't join it: the write applies at ` +
+            "once, so a rolled-back transaction won't undo it. Register a store for your database with " +
+            'WorkflowStorage.registerSource(). (Logged once.)');
+    }
+    async create(i) {
+        const existing = this.rows.get(i.id);
+        if (existing) {
+            return { instance: copy(existing.instance), created: false };
+        }
+        const instance = {
+            id: i.id,
+            workflow: i.workflow,
+            version: i.version,
+            parentId: i.parentId ?? null,
+            parentClose: i.parentClose ?? null,
+            concurrencyKey: i.concurrencyKey ?? null,
+            rateLimitKey: i.rateLimitKey ?? null,
+            priority: i.priority ?? 0,
+            scheduleId: i.scheduleId ?? null,
+            scheduledAt: i.scheduledAt ?? null,
+            status: 'pending',
+            input: copy(i.input),
+            output: undefined,
+            error: null,
+            wakeAt: i.now,
+            leaseOwner: null,
+            leaseUntil: null,
+            cancelRequested: false,
+            terminateRequested: false,
+            cancelReason: null,
+            deadline: i.deadline,
+            customStatus: null,
+            signalCursor: this.lastSignalId(),
+            runs: 0,
+            createdAt: i.now,
+            updatedAt: i.now,
+        };
+        this.rows.set(i.id, { instance, leaseToken: null, journal: new Map(), waits: [] });
+        return { instance: copy(instance), created: true };
+    }
+    async get(id, options = {}) {
+        const row = this.rows.get(id);
+        if (!row) {
+            return null;
+        }
+        return {
+            ...copy(row.instance),
+            waits: copy(row.waits),
+            ...(options.journal ? { journal: copy([...row.journal.values()]) } : {}),
+        };
+    }
+    async list(query) {
+        return [...this.rows.values()]
+            .map((row) => row.instance)
+            .filter((i) => (query.status === undefined || query.status.includes(i.status)) &&
+            (query.workflow === undefined || i.workflow === query.workflow) &&
+            (query.version === undefined || i.version === query.version) &&
+            (query.parentId === undefined || i.parentId === query.parentId) &&
+            (query.scheduleId === undefined || i.scheduleId === query.scheduleId))
+            .sort((a, b) => a.createdAt - b.createdAt || compare(a.id, b.id))
+            .slice(query.offset, query.offset + query.limit)
+            .map(copy);
+    }
+    async requestCancel(id, { reason, now, terminate }) {
+        const instance = this.rows.get(id)?.instance;
+        const applies = terminate ? RUNNABLE.has(instance?.status ?? '') && !instance.terminateRequested : CANCELLABLE.has(instance?.status ?? '') && !instance.cancelRequested;
+        if (!instance || !applies) {
+            return false;
+        }
+        instance.cancelRequested = true;
+        instance.terminateRequested ||= terminate;
+        instance.cancelReason = reason;
+        instance.updatedAt = now;
+        if (instance.wakeAt === null || instance.wakeAt > now) {
+            instance.wakeAt = now;
+        }
+        return true;
+    }
+    async reopen(id, r) {
+        const row = this.rows.get(id);
+        if (!row || row.leaseToken !== null || row.instance.status !== r.expect.status || row.instance.runs !== r.expect.runs) {
+            return false;
+        }
+        for (const entry of r.entries) {
+            row.journal.set(entry.name, copy(entry));
+        }
+        const i = row.instance;
+        i.status = r.status;
+        i.error = copy(r.error);
+        if (r.deadline !== undefined) {
+            i.deadline = r.deadline;
+        }
+        i.wakeAt = r.now;
+        i.updatedAt = r.now;
+        return true;
+    }
+    async delete(id, statuses) {
+        const row = this.rows.get(id);
+        if (!row || !statuses.includes(row.instance.status)) {
+            return false;
+        }
+        this.rows.delete(id);
+        return true;
+    }
+    async signal(s) {
+        return this.record(s);
+    }
+    record(s) {
+        const earlier = s.dedupeId === null ? undefined : this.signalLog.find((r) => r.name === s.name && r.dedupeId === s.dedupeId);
+        if (earlier) {
+            return { id: earlier.id, woken: 0, created: false, key: earlier.key };
+        }
+        const id = this.lastSignalId() + 1;
+        this.signalLog.push({ id, name: s.name, key: s.key, dedupeId: s.dedupeId, payload: copy(s.payload), createdAt: s.now });
+        let woken = 0;
+        for (const { instance, waits } of this.rows.values()) {
+            if (instance.status !== 'suspended' || (instance.wakeAt !== null && instance.wakeAt <= s.now)) {
+                continue;
+            }
+            if (!waits.some((wait) => wait.signal === s.name && wait.key === s.key)) {
+                continue;
+            }
+            instance.wakeAt = s.now;
+            instance.updatedAt = s.now;
+            woken++;
+        }
+        return { id, woken, created: true, key: s.key };
+    }
+    async signals(query) {
+        return this.signalLog
+            .filter((s) => s.name === query.name && s.key === query.key && s.id > query.afterId && s.id <= query.upToId)
+            .map(({ dedupeId: _dedupeId, ...record }) => copy(record));
+    }
+    async purge(query) {
+        const finished = [...this.rows.values()]
+            .map((row) => row.instance)
+            .filter((i) => FINISHED.has(i.status) && query.statuses.includes(i.status) && i.updatedAt < query.before)
+            .sort((a, b) => a.updatedAt - b.updatedAt || compare(a.id, b.id))
+            .slice(0, query.limit);
+        for (const instance of finished) {
+            this.rows.delete(instance.id);
+        }
+        const newest = this.lastSignalId();
+        const cursors = [...this.rows.values()].filter((row) => RUNNABLE.has(row.instance.status)).map((row) => row.instance.signalCursor);
+        const floor = Math.min(newest, ...cursors);
+        const prunable = new Set(this.signalLog
+            .filter((s) => s.id <= floor && s.id < newest && s.createdAt < query.before)
+            .slice(0, query.limit)
+            .map((s) => s.id));
+        const kept = this.signalLog.filter((s) => !prunable.has(s.id));
+        this.signalLog.splice(0, this.signalLog.length, ...kept);
+        const ended = [...this.windows]
+            .filter(([, window]) => window.windowEnd < query.before)
+            .sort(([a, x], [b, y]) => x.windowEnd - y.windowEnd || compare(a, b))
+            .slice(0, query.limit);
+        for (const [key] of ended) {
+            this.windows.delete(key);
+        }
+        return { instances: finished.length, signals: prunable.size, rateLimits: ended.length };
+    }
+    saveSchedule(save) {
+        return this.scheduleMethods.saveSchedule(save);
+    }
+    getSchedule(id) {
+        return this.scheduleMethods.getSchedule(id);
+    }
+    listSchedules(query) {
+        return this.scheduleMethods.listSchedules(query);
+    }
+    deleteSchedule(id, revision) {
+        return this.scheduleMethods.deleteSchedule(id, revision);
+    }
+    claimSchedules(request) {
+        return this.scheduleMethods.claimSchedules(request);
+    }
+    writeSchedule(id, token, write) {
+        return this.scheduleMethods.writeSchedule(id, token, write);
+    }
+    async claim(request) {
+        const runs = new Set(request.workflows.map((w) => `${w.version}:${w.name}`));
+        const candidates = [...this.rows.values()]
+            .filter(({ instance: i }) => RUNNABLE.has(i.status) &&
+            i.wakeAt !== null &&
+            i.wakeAt <= request.now &&
+            (i.leaseUntil === null || i.leaseUntil < request.now) &&
+            runs.has(`${i.version}:${i.workflow}`))
+            .sort((a, b) => a.instance.priority - b.instance.priority ||
+            a.instance.wakeAt - b.instance.wakeAt ||
+            a.instance.createdAt - b.instance.createdAt ||
+            compare(a.instance.id, b.instance.id));
+        const due = this.pick(request, candidates);
+        this.recordWindows(request, due);
+        for (const row of due) {
+            const i = row.instance;
+            row.leaseToken = request.token;
+            i.leaseOwner = request.owner;
+            i.leaseUntil = request.leaseUntil;
+            i.runs++;
+            i.updatedAt = request.now;
+            if (i.status !== 'compensating') {
+                i.status = 'running';
+            }
+        }
+        return { instances: due.map((row) => copy(row.instance)), lastSignalId: this.lastSignalId() };
+    }
+    /**
+     * The staged pick of `WorkflowStore.claim()` under limits: candidates with no room at all are passed over first;
+     * then each concurrency key keeps its first candidates, as many as it has free slots; of those, each rate-limit
+     * key as many as its window has room for; of those, each workflow as many as both its free slots and its window
+     * allow; then the first `limit`.
+     */
+    pick(request, candidates) {
+        const limits = new Map((request.limits ?? []).map((limit) => [limit.workflow, limit]));
+        const rules = new Map((request.rateLimits ?? []).map((rule) => [rule.workflow, rule]));
+        const held = new Map();
+        for (const { instance: i } of this.rows.values()) {
+            if (limits.has(i.workflow) && i.leaseUntil !== null && i.leaseUntil >= request.now) {
+                for (const key of [slot(i.workflow), ...(i.concurrencyKey === null ? [] : [slot(i.workflow, i.concurrencyKey)])]) {
+                    held.set(key, (held.get(key) ?? 0) + 1);
+                }
+            }
+        }
+        const heldBy = (key) => held.get(key) ?? 0;
+        const roomIn = (key, max) => rateWindowRoom(this.windows.get(key), max, request.now);
+        const free = (i) => {
+            const limit = limits.get(i.workflow);
+            const rule = rules.get(i.workflow);
+            return {
+                total: limit?.limit != null ? limit.limit - heldBy(slot(i.workflow)) : Infinity,
+                key: limit?.perKey != null && i.concurrencyKey !== null ? limit.perKey - heldBy(slot(i.workflow, i.concurrencyKey)) : Infinity,
+                rate: rule?.limit ? roomIn(slot(i.workflow), rule.limit.max) : Infinity,
+                rateKey: rule?.perKey && i.rateLimitKey !== null ? roomIn(slot(i.workflow, i.rateLimitKey), rule.perKey.max) : Infinity,
+            };
+        };
+        const open = candidates.filter(({ instance: i }) => Object.values(free(i)).every((room) => room > 0));
+        const byKey = firsts(open, (i) => (Number.isFinite(free(i).key) ? slot(i.workflow, i.concurrencyKey) : null), (i) => free(i).key);
+        const byRateKey = firsts(byKey, (i) => (Number.isFinite(free(i).rateKey) ? slot(i.workflow, i.rateLimitKey) : null), (i) => free(i).rateKey);
+        const byWorkflow = firsts(byRateKey, (i) => (limits.has(i.workflow) || rules.has(i.workflow) ? i.workflow : null), (i) => Math.min(free(i).total, free(i).rate));
+        return byWorkflow.slice(0, request.limit);
+    }
+    /** Records the claims of `claimed` in their rate-limit windows, starting a window where the last one ended. */
+    recordWindows(request, claimed) {
+        const rules = new Map((request.rateLimits ?? []).map((rule) => [rule.workflow, rule]));
+        for (const { instance: i } of claimed) {
+            const rule = rules.get(i.workflow);
+            const windows = [
+                ...(rule?.limit ? [{ key: slot(i.workflow), duration: rule.limit.duration }] : []),
+                ...(rule?.perKey && i.rateLimitKey !== null ? [{ key: slot(i.workflow, i.rateLimitKey), duration: rule.perKey.duration }] : []),
+            ];
+            for (const { key, duration } of windows) {
+                this.windows.set(key, takeRateWindow(this.windows.get(key), duration, request.now));
+            }
+        }
+    }
+    async renew(id, token, leaseUntil) {
+        const row = this.leased(id, token);
+        if (!row) {
+            return null;
+        }
+        row.instance.leaseUntil = leaseUntil;
+        return { cancelRequested: row.instance.cancelRequested, terminateRequested: row.instance.terminateRequested };
+    }
+    async write(id, token, w) {
+        const row = this.leased(id, token);
+        if (!row) {
+            return false;
+        }
+        for (const entry of w.entries) {
+            row.journal.set(entry.name, copy(entry));
+        }
+        const i = row.instance;
+        if (w.status !== undefined) {
+            i.status = w.status;
+        }
+        if (w.output !== undefined) {
+            i.output = copy(w.output);
+        }
+        if (w.error !== undefined) {
+            i.error = copy(w.error);
+        }
+        if (w.customStatus !== undefined) {
+            i.customStatus = copy(w.customStatus);
+        }
+        if (w.signal) {
+            this.record(w.signal);
+        }
+        if (w.release) {
+            const { waits, signalCursor } = w.release;
+            row.waits = copy(waits);
+            row.leaseToken = null;
+            i.leaseUntil = null;
+            const missed = this.signalLog.some((s) => s.id > signalCursor && waits.some((wait) => wait.signal === s.name && wait.key === s.key));
+            i.wakeAt = missed || (i.cancelRequested && w.status === 'suspended') ? w.now : w.release.wakeAt;
+        }
+        if (w.status !== undefined || w.output !== undefined || w.error !== undefined || w.customStatus !== undefined || w.release) {
+            i.updatedAt = w.now;
+        }
+        return true;
+    }
+    leased(id, token) {
+        const row = this.rows.get(id);
+        return row && row.leaseToken !== null && row.leaseToken === token ? row : undefined;
+    }
+    lastSignalId() {
+        return this.signalLog.at(-1)?.id ?? 0;
+    }
+}
+InMemoryWorkflowStore.logger = new Logger('WorkflowsModule');
+function copy(value) {
+    return value === undefined ? value : structuredClone(value);
+}
+function compare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** A workflow's slot or window key, or one of its keys'. */
+function slot(workflow, key) {
+    return JSON.stringify(key === undefined ? [workflow] : [workflow, key]);
+}
+/** Of `rows` (in order), each partition's first ones, as many as `room` says; rows in no partition (`null`) all stay. */
+function firsts(rows, partition, room) {
+    const seen = new Map();
+    return rows.filter(({ instance }) => {
+        const key = partition(instance);
+        if (key === null) {
+            return true;
+        }
+        const n = (seen.get(key) ?? 0) + 1;
+        seen.set(key, n);
+        return n <= room(instance);
+    });
+}

package/dist/stores/index.d.ts

@@ -0,0 +1 @@
+export * from './in-memory-workflow.store.js';

package/dist/stores/index.js

@@ -0,0 +1 @@
+export * from './in-memory-workflow.store.js';

package/dist/testing/assertions.d.ts

@@ -0,0 +1,10 @@
+/** A random pause of up to 4 ms, to shuffle the calls a race starts together. */
+export declare const jitter: () => Promise<unknown>;
+export declare function show(value: unknown): string;
+export declare function equal(actual: unknown, expected: unknown, label: string): void;
+/** Every key of `pattern` matches, recursively (arrays by length and element); other keys are ignored. */
+export declare function expect(actual: unknown, pattern: unknown, label: string): void;
+export declare function absent(value: unknown, label: string, options?: {
+    orNull?: boolean;
+}): void;
+export declare function rejects(promise: Promise<unknown>, message: string): Promise<void>;

package/dist/testing/assertions.js

@@ -0,0 +1,72 @@
+import { isDeepStrictEqual } from 'node:util';
+/** A random pause of up to 4 ms, to shuffle the calls a race starts together. */
+export const jitter = () => new Promise((resolve) => setTimeout(resolve, Math.random() * 4));
+export function show(value) {
+    return JSON.stringify(value, (_key, v) => (v === undefined ? '<undefined>' : v)) ?? String(value);
+}
+export function equal(actual, expected, label) {
+    if (!isDeepStrictEqual(normalizeUndefined(actual), normalizeUndefined(expected))) {
+        throw new Error(`${label}: expected ${show(expected)}, got ${show(actual)}`);
+    }
+}
+/** Every key of `pattern` matches, recursively (arrays by length and element); other keys are ignored. */
+export function expect(actual, pattern, label) {
+    const mismatch = match(actual, pattern, '');
+    if (mismatch !== null) {
+        throw new Error(`${label}: ${mismatch}\n  expected ${show(pattern)}\n  got      ${show(actual)}`);
+    }
+}
+function match(actual, pattern, path) {
+    if (Array.isArray(pattern)) {
+        if (!Array.isArray(actual) || actual.length !== pattern.length) {
+            return `at ${path || 'the root'}: expected an array of ${pattern.length}`;
+        }
+        for (let i = 0; i < pattern.length; i++) {
+            const mismatch = match(actual[i], pattern[i], `${path}[${i}]`);
+            if (mismatch) {
+                return mismatch;
+            }
+        }
+        return null;
+    }
+    if (pattern !== null && typeof pattern === 'object') {
+        if (actual === null || typeof actual !== 'object') {
+            return `at ${path || 'the root'}: expected an object`;
+        }
+        for (const [key, value] of Object.entries(pattern)) {
+            const mismatch = match(actual[key], value, path ? `${path}.${key}` : key);
+            if (mismatch) {
+                return mismatch;
+            }
+        }
+        return null;
+    }
+    return Object.is(actual, pattern) ? null : `at ${path || 'the root'}: expected ${show(pattern)}, got ${show(actual)}`;
+}
+export function absent(value, label, options = {}) {
+    if (value !== undefined && !(options.orNull && value === null)) {
+        throw new Error(`${label}: expected undefined, got ${show(value)}`);
+    }
+}
+export async function rejects(promise, message) {
+    try {
+        await promise;
+    }
+    catch (error) {
+        if (String(error?.message ?? error).includes(message)) {
+            return;
+        }
+        throw error;
+    }
+    throw new Error(`expected a rejection with "${message}"`);
+}
+/** Drops `undefined` object fields, so `{ a: undefined }` equals `{}` (a store may omit them). */
+function normalizeUndefined(value) {
+    if (Array.isArray(value)) {
+        return value.map(normalizeUndefined);
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined).map(([k, v]) => [k, normalizeUndefined(v)]));
+    }
+    return value;
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,38 @@
+import type { WorkflowStore } from '../interfaces/workflow-store.interface.js';
+export { scheduleStoreContract, type ScheduleStoreContractCase, type ScheduleStoreContractOptions } from './schedule-store.contract.js';
+export interface WorkflowStoreContractOptions {
+    /**
+     * Also run the concurrency cases: many calls in flight at once, racing claims, signals,
+     * suspensions and cancels. 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;
+    /**
+     * Opens an application transaction and runs `work` in it, such as
+     * `(work) => db.transaction(work)`: the cases for `createInTransaction()` and
+     * `signalInTransaction()` run when it is set and the store has them.
+     */
+    transaction?: <T>(work: (transaction: unknown) => Promise<T>) => Promise<T>;
+    /** Called after each case with the store `createStore` returned (close it, drop its tables). */
+    dispose?: (store: WorkflowStore) => unknown;
+}
+export interface WorkflowStoreContractCase {
+    name: string;
+    /** Throws on failure. */
+    run(): Promise<void>;
+}
+/**
+ * The `WorkflowStore` contract as test cases, for any test runner:
+ *
+ * ```ts
+ * const cases = workflowStoreContract(async () => new DrizzleWorkflowStore(await freshDb(), new WorkflowStorage()), {
+ *   concurrent: true,
+ *   transaction: (work) => db.transaction(work),
+ * });
+ * for (const c of cases) it(c.name, c.run);
+ * ```
+ *
+ * `createStore` is called once per case and must return a store on empty tables.
+ */
+export declare function workflowStoreContract(createStore: () => WorkflowStore | Promise<WorkflowStore>, options?: WorkflowStoreContractOptions): WorkflowStoreContractCase[];