@nestjs/workflows 0.0.1

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

@@ -0,0 +1,468 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable, Logger, } from '@nestjs/common';
+import { systemClock } from '../core/time/clock.js';
+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 { resolveRetry } from '../core/retries/retry.js';
+import { resolveJournalLimits } from '../utils/journal-limits.util.js';
+import { normalize } from '../utils/normalize.util.js';
+import { assertSameInstance } from '../utils/new-instance.util.js';
+import { CHILD_ENDED_SIGNAL } from '../workflows.constants.js';
+import { uniqueEntries, WorkflowExecution, } from './workflow-execution.service.js';
+import { WorkflowEvents } from '../events/workflow-events.service.js';
+import { ENGINE_STORE, WorkflowStorage } from '../storage/workflow.storage.js';
+import { WorkflowRegistry } from './workflow-registry.service.js';
+import { WorkflowScheduler } from './workflow-scheduler.service.js';
+import { WORKFLOWS_MODULE_OPTIONS } from '../workflows.module-definition.js';
+/**
+ * Claims due instances under a lease, executes them and records the outcome.
+ * Any number of processes can run a worker against the same store. Inject it
+ * for `drain()`, which runs due instances on demand (tests, scripts).
+ */
+let WorkflowWorker = class WorkflowWorker {
+    constructor(storage, options, registry, events, scheduler) {
+        this.storage = storage;
+        this.registry = registry;
+        this.events = events;
+        this.scheduler = scheduler;
+        this.logger = new Logger('Workflows');
+        const worker = options.worker === false ? { enabled: false } : (options.worker ?? {});
+        this.clock = options.clock ?? systemClock;
+        this.enabled = worker.enabled ?? true;
+        this.leased = new LeasedWorker({
+            name: 'worker',
+            owner: worker.id,
+            concurrency: worker.concurrency,
+            pollInterval: worker.pollInterval,
+            leaseDuration: worker.leaseDuration,
+            heartbeatInterval: worker.heartbeatInterval,
+            shutdownTimeout: worker.shutdownTimeout,
+            clock: this.clock,
+            // Schedules have second precision: their occurrences are started at most once a second, however often it polls.
+            produceInterval: '1s',
+            produce: async () => this.produced(await this.scheduler.produce(this.id, this.leased.leaseMs)),
+            claim: (lease, limit) => this.claim(lease, limit),
+            renew: (claimed, until) => this.renew(claimed, until),
+            execute: (claimed, run) => this.execute(claimed, run),
+            onError: (error, stage) => this.logger.error(FAILED[stage], error),
+        });
+        this.id = this.leased.owner;
+        this.deps = {
+            get store() {
+                return storage[ENGINE_STORE];
+            },
+            resolve: (workflow, version) => registry.resolve(workflow, version),
+            createChild: async (child) => {
+                const { instance, created } = await storage[ENGINE_STORE].create(child);
+                if (created) {
+                    this.kick();
+                }
+                else {
+                    assertSameInstance(instance, child, { input: true, parent: true });
+                }
+                return instance;
+            },
+            clock: this.clock,
+            events,
+            defaultRetry: resolveRetry(options.retry),
+            journalLimits: resolveJournalLimits(options.journal),
+        };
+    }
+    onApplicationBootstrap() {
+        this.registry.keys(); // validate definitions at startup
+        if (this.enabled) {
+            this.leased.start();
+        }
+    }
+    /** Read at each use, never in the constructor: sources register while providers are created. */
+    get store() {
+        return this.storage[ENGINE_STORE];
+    }
+    async onModuleDestroy() {
+        await this.shutdown();
+    }
+    /** Stops the worker if `onModuleDestroy` didn't run (an application closed before it initialized). */
+    async onApplicationShutdown() {
+        await this.shutdown();
+    }
+    /** @internal Look for work now instead of at the next poll (after a local start or signal). */
+    kick() {
+        this.leased.kick();
+    }
+    /**
+     * @internal After an accepted `WorkflowClient.cancel()` or `terminate()` in this process: an
+     * execution of the instance running here stops at its next `ctx` call now,
+     * instead of when its next heartbeat reads the flag.
+     */
+    noticeCancel(id, terminate = false) {
+        for (const { exec } of this.leased.running) {
+            if (exec?.instance.id === id) {
+                exec.cancelRequested = true;
+                exec.terminateRequested ||= terminate;
+            }
+        }
+        this.kick();
+    }
+    /**
+     * Executes every due instance, repeatedly, until none is left that its workflow's concurrency and rate
+     * limits let start. Returns the number of executions. For tests (with a `ManualWorkflowClock` and
+     * `worker: false`), scripts and cron-driven workers.
+     */
+    drain(options = {}) {
+        return this.leased.drain(options);
+    }
+    /** After a production of the schedules' occurrences: cancels its executions of the instances it cancelled. */
+    produced(production) {
+        for (const id of production.cancelled) {
+            this.noticeCancel(id);
+        }
+        return production.started;
+    }
+    /**
+     * @internal Called on application shutdown. Stops claiming, asks running
+     * executions to stop (their steps see `signal.aborted`), and waits up to
+     * `shutdownTimeout`. Executions that stopped are handed back at once; the
+     * rest keep their lease until it expires, because their step may still be running.
+     */
+    shutdown() {
+        return this.leased.shutdown();
+    }
+    /** Leases due instances of the workflow versions this process runs, under their limits. */
+    async claim(lease, limit) {
+        const workflows = this.registry.versions();
+        if (workflows.length === 0) {
+            return [];
+        }
+        const { instances, lastSignalId } = await this.store.claim({
+            owner: lease.owner,
+            token: lease.token,
+            now: lease.now,
+            leaseUntil: lease.until,
+            limit,
+            workflows,
+            limits: this.registry.limits(),
+            rateLimits: this.registry.rateLimits(),
+        });
+        return instances.map((instance) => ({ instance: { ...instance, leaseToken: lease.token }, signalCursor: lastSignalId }));
+    }
+    /** Extends an instance's lease, and hands its execution the cancel and terminate requests the renewal read. */
+    async renew(claimed, until) {
+        const { instance, exec } = claimed;
+        const flags = await this.store.renew(instance.id, instance.leaseToken, until);
+        if (flags && exec) {
+            exec.cancelRequested ||= flags.cancelRequested;
+            exec.terminateRequested ||= flags.terminateRequested;
+        }
+        return flags !== null;
+    }
+    async execute(claimed, run) {
+        const { instance, signalCursor } = claimed;
+        const definition = this.registry.get(instance.workflow, instance.version);
+        try {
+            const details = await this.claimed(instance, signalCursor);
+            if (!details) {
+                return;
+            }
+            const replayOnly = instance.status === 'compensating' || instance.cancelRequested;
+            const exec = new WorkflowExecution(instance, details.journal ?? [], signalCursor, this.deps, run, replayOnly);
+            claimed.exec = exec;
+            // Nothing of it runs any more, not even its compensations.
+            if (instance.terminateRequested) {
+                return await this.terminate(exec, instance);
+            }
+            this.emit(instance, instance.runs === 1 ? { type: 'workflow-started' } : { type: 'workflow-resumed', run: instance.runs });
+            const outcome = await exec.run(async () => definition.instance.run(exec.context, instance.input));
+            await this.conclude(exec, instance, outcome);
+        }
+        catch (error) {
+            this.logger.error(`Executing "${instance.id}" (${instance.workflow}@${instance.version}) failed; it is retried when its lease expires.`, error);
+        }
+    }
+    /**
+     * The claimed instance with its journal, or `null` when that can't be read (a codec whose key is gone wrote part of
+     * the journal, as after a key rotation that was rolled back): then it is handed back, as a claim hands back an
+     * instance whose own payloads can't be read, instead of holding its lease and its concurrency slot until the lease
+     * expires, and going first at every claim after that.
+     */
+    async claimed(instance, signalCursor) {
+        let details;
+        try {
+            details = await this.store.get(instance.id, { journal: true });
+        }
+        catch (error) {
+            this.logger.error(`Instance "${instance.id}" can't be read, so it isn't run; it is claimed again later.`, error);
+            const lease = { now: this.clock.now(), leaseUntil: instance.leaseUntil, signalCursor };
+            // At worst its lease expires, as if its worker had died.
+            await this.storage[ENGINE_STORE].handBack(instance.id, instance.leaseToken, lease).catch(() => undefined);
+            return null;
+        }
+        if (!details) {
+            throw new Error(`The store has no instance "${instance.id}", which it just leased.`);
+        }
+        return details;
+    }
+    async conclude(exec, instance, outcome) {
+        if (await this.interrupted(exec, instance, outcome.ok)) {
+            return;
+        }
+        if (exec.fatal) {
+            return this.finish(exec, instance, 'failed', { error: serializeError(exec.fatal) });
+        }
+        if (instance.status === 'compensating') {
+            return this.compensate(exec, instance, instance.error ?? { name: 'Error', message: 'Unknown failure.' }, true);
+        }
+        if (instance.cancelRequested) {
+            return this.compensate(exec, instance, cancelled(instance.cancelReason), false);
+        }
+        // A cancel noticed during the run (a heartbeat, or cancel() in this process) stopped it.
+        // Checked before a suspension: a parked sleep, wait or retry backoff left next to it
+        // will never resume, so the instance compensates now instead of parking first and being
+        // woken again for that. The same goes for a run timeout.
+        if (!outcome.ok && isWorkflowInterrupt(outcome.error) && outcome.error.reason === 'cancel') {
+            const current = await this.store.get(instance.id);
+            if (current?.terminateRequested) {
+                return this.finish(exec, instance, 'cancelled', { error: terminated(current.cancelReason) });
+            }
+            return this.compensate(exec, instance, cancelled(current?.cancelReason ?? null), false);
+        }
+        if (!outcome.ok && isWorkflowInterrupt(outcome.error) && outcome.error.reason === 'timeout') {
+            return this.compensate(exec, instance, timedOut(instance), false);
+        }
+        if (exec.journalLimitError) {
+            return this.compensate(exec, instance, exec.journalLimitError, false);
+        }
+        if (exec.suspension) {
+            const { waits } = exec.suspension;
+            // Parked no later than the run timeout, so a sleep or wait past it can't outlive it.
+            const wakeAt = instance.deadline === null ? exec.suspension.wakeAt : Math.min(exec.suspension.wakeAt ?? instance.deadline, instance.deadline);
+            const ok = await this.write(exec, instance, {
+                entries: exec.drainBuffer(),
+                status: 'suspended',
+                release: this.release(exec, wakeAt, waits),
+            });
+            if (ok) {
+                this.emit(instance, { type: 'workflow-suspended', wakeAt, waits });
+            }
+            else {
+                this.leaseLostWarning(instance);
+            }
+            return;
+        }
+        if (outcome.ok) {
+            const missing = exec.unvisited();
+            if (missing.length) {
+                const error = new WorkflowNonDeterminismError(`Instance "${instance.id}" of workflow "${instance.workflow}@${instance.version}" does not match its journal: ` +
+                    `${missing.map((n) => `"${n}"`).join(', ')} ${missing.length === 1 ? 'was' : 'were'} recorded by an earlier run but never reached. ` +
+                    'Ship step removals as a new workflow version.');
+                return this.finish(exec, instance, 'failed', { error: serializeError(error) });
+            }
+            let output;
+            try {
+                output = normalize(outcome.value);
+            }
+            catch (error) {
+                return this.compensate(exec, instance, serializeError(error), false);
+            }
+            return this.finish(exec, instance, 'completed', { output });
+        }
+        return this.compensate(exec, instance, serializeError(outcome.error), false);
+    }
+    async compensate(exec, instance, reason, alreadyCompensating) {
+        if (!alreadyCompensating) {
+            const ok = await this.write(exec, instance, { entries: exec.drainBuffer(), status: 'compensating', error: reason });
+            if (!ok) {
+                return this.leaseLostWarning(instance);
+            }
+            this.emit(instance, { type: 'workflow-compensating', error: reason });
+        }
+        // Every execution that compensates closes them again: a crash can't leave one running.
+        await this.closeChildren(exec, instance, `its parent "${instance.id}" is compensating (${reason.name}: ${reason.message})`);
+        const result = await exec.compensate(reason);
+        switch (result.state) {
+            case 'done':
+                return this.finish(exec, instance, reason.name === 'WorkflowCancelledError' ? 'cancelled' : 'failed', {
+                    error: reason,
+                });
+            case 'failed':
+                return this.finish(exec, instance, 'compensation_failed', { error: { ...reason, compensation: result.error } });
+            case 'suspended': {
+                const ok = await this.write(exec, instance, {
+                    entries: exec.drainBuffer(),
+                    status: 'compensating',
+                    release: this.release(exec, result.wakeAt, []),
+                });
+                if (ok) {
+                    this.emit(instance, { type: 'workflow-suspended', wakeAt: result.wakeAt, waits: [] });
+                }
+                return;
+            }
+            case 'interrupted':
+                await this.interrupted(exec, instance, false);
+                return;
+            case 'terminated':
+                return this.terminate(exec, instance);
+        }
+    }
+    /**
+     * Applies each child's `parentClose` to the children of this instance that are still running:
+     * cancels or terminates them. At least once: it runs again after a crash, and a request that
+     * was already accepted is refused, changing nothing.
+     */
+    async closeChildren(exec, instance, reason) {
+        if (!exec.hasChildren()) {
+            return;
+        }
+        // Every child, oldest first: the list's order doesn't change while the statuses do.
+        for (let offset = 0;; offset += CHILDREN_PAGE) {
+            // Read as stored: closing a child needs no payload, and one no codec can read any more is closed too.
+            const children = await this.storage[ENGINE_STORE].inner.list({ parentId: instance.id, limit: CHILDREN_PAGE, offset });
+            for (const child of children) {
+                if (!RUNNABLE.includes(child.status) || child.parentClose === 'abandon' || child.parentClose === null) {
+                    continue;
+                }
+                const terminate = child.parentClose === 'terminate';
+                const reasonText = `${terminate ? 'Terminated' : 'Cancelled'}: ${reason}.`;
+                if (await this.store.requestCancel(child.id, { reason: reasonText, now: this.clock.now(), terminate })) {
+                    this.noticeCancel(child.id, terminate);
+                }
+            }
+            if (children.length < CHILDREN_PAGE) {
+                return;
+            }
+        }
+    }
+    /** Ends the instance as `cancelled` without running (more of) its compensations. */
+    async terminate(exec, instance) {
+        const current = await this.store.get(instance.id);
+        return this.finish(exec, instance, 'cancelled', { error: terminated(current?.cancelReason ?? instance.cancelReason) });
+    }
+    /**
+     * Handles executions that must not record an outcome. Returns true if
+     * handled. A run that finished cleanly during shutdown is still recorded;
+     * one that was cut short is handed back, and whatever it was doing is
+     * re-derived by the next execution.
+     */
+    async interrupted(exec, instance, finished) {
+        if (exec.leaseLost) {
+            this.leaseLostWarning(instance);
+            return true;
+        }
+        if (exec.storeError) {
+            this.logger.error(`Store failed while executing "${instance.id}"; it is retried when its lease expires.`, exec.storeError);
+            return true;
+        }
+        if (exec.detached) {
+            return true;
+        }
+        if (exec.shuttingDown && !finished) {
+            // Handed back: due at once, for another worker (or this one, after a restart).
+            await this.write(exec, instance, {
+                entries: [...exec.drainBuffer(), ...exec.rollbacks],
+                release: this.release(exec, this.clock.now(), []),
+            });
+            return true;
+        }
+        return false;
+    }
+    async finish(exec, instance, status, result) {
+        // Before the instance ends, so a crash in between closes them again on the next execution.
+        await this.closeChildren(exec, instance, `its parent "${instance.id}" ended as ${status}`);
+        const entries = exec.drainBuffer();
+        if (status !== 'completed') {
+            entries.push(...exec.abandoned().map((entry) => ({ ...entry, updatedAt: this.clock.now() })));
+        }
+        // A child tells its parent, in the same transaction: a parent never misses its child's end.
+        const ended = { status, output: result.output, error: result.error ?? null };
+        const ok = await this.write(exec, instance, {
+            entries,
+            status,
+            output: result.output,
+            error: result.error ?? null,
+            release: this.release(exec, null, []),
+            ...(instance.parentId === null
+                ? {}
+                : { signal: { name: CHILD_ENDED_SIGNAL, key: instance.id, dedupeId: instance.id, payload: ended, now: this.clock.now() } }),
+        });
+        if (!ok) {
+            return this.leaseLostWarning(instance);
+        }
+        if (status === 'completed') {
+            this.emit(instance, { type: 'workflow-completed', output: result.output });
+        }
+        else if (status === 'cancelled') {
+            this.emit(instance, { type: 'workflow-cancelled', error: result.error });
+        }
+        else if (status === 'failed') {
+            this.emit(instance, { type: 'workflow-failed', error: result.error });
+        }
+        else {
+            this.emit(instance, { type: 'workflow-compensation-failed', error: result.error });
+        }
+    }
+    /** A fenced write under the execution's lease, stamped with the clock, with the custom status if it changed. */
+    async write(exec, instance, write) {
+        const change = exec.statusChange();
+        const ok = await this.store.write(instance.id, instance.leaseToken, { ...write, ...change, entries: uniqueEntries(write.entries), now: this.clock.now() });
+        if (ok) {
+            exec.statusWritten(change);
+        }
+        return ok;
+    }
+    release(exec, wakeAt, waits) {
+        return { wakeAt, waits, signalCursor: exec.signalCursor };
+    }
+    leaseLostWarning(instance) {
+        this.logger.warn(`Lost the lease on "${instance.id}" (${instance.workflow}); another worker took over. Nothing from this execution after that point was recorded.`);
+    }
+    emit(instance, body) {
+        this.events.emit({
+            id: instance.id,
+            workflow: instance.workflow,
+            version: instance.version,
+            at: this.clock.now(),
+            ...body,
+        });
+    }
+};
+WorkflowWorker = __decorate([
+    Injectable(),
+    __param(1, Inject(WORKFLOWS_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [WorkflowStorage, Object, WorkflowRegistry,
+        WorkflowEvents,
+        WorkflowScheduler])
+], WorkflowWorker);
+export { WorkflowWorker };
+/** What the loop logs when a stage fails; it carries on. */
+const FAILED = {
+    claim: 'Claiming workflow instances failed.',
+    produce: "Starting the schedules' occurrences failed.",
+    execute: 'Executing a workflow instance failed.',
+};
+function cancelled(reason) {
+    return { name: 'WorkflowCancelledError', message: reason ?? 'Cancelled.' };
+}
+const RUNNABLE = ['pending', 'running', 'suspended', 'compensating'];
+const CHILDREN_PAGE = 500;
+function terminated(reason) {
+    return { name: 'WorkflowTerminatedError', message: reason ?? 'Terminated.' };
+}
+function timedOut(instance) {
+    return {
+        name: 'WorkflowTimeoutError',
+        message: `Instance "${instance.id}" of workflow "${instance.workflow}@${instance.version}" did not finish within its timeout ` +
+            `(its deadline was ${new Date(instance.deadline).toISOString()}).`,
+    };
+}

package/dist/signals/index.d.ts

@@ -0,0 +1 @@
+export * from './workflow.signal.js';

package/dist/signals/index.js

@@ -0,0 +1 @@
+export * from './workflow.signal.js';

package/dist/signals/workflow.signal.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A named signal with a payload type, shared by the code that sends it
+ * (`WorkflowClient.signal()`) and the workflows that wait for it
+ * (`ctx.waitForSignal()`). One constant for both ends means the name can't be
+ * misspelled on one side, and the payload is type-checked on both.
+ *
+ * @example
+ * export const shipmentDelivered = new WorkflowSignal<CarrierEvent>('shipment.delivered');
+ */
+export declare class WorkflowSignal<T = unknown> {
+    readonly name: string;
+    /** Type-only: the payload type. Never set at runtime. */
+    readonly payload?: T;
+    constructor(name: string);
+}
+export declare function assertSignalName(name: unknown): asserts name is string;
+export declare function signalName(signal: WorkflowSignal<unknown> | string): string;

package/dist/signals/workflow.signal.js

@@ -0,0 +1,28 @@
+/**
+ * A named signal with a payload type, shared by the code that sends it
+ * (`WorkflowClient.signal()`) and the workflows that wait for it
+ * (`ctx.waitForSignal()`). One constant for both ends means the name can't be
+ * misspelled on one side, and the payload is type-checked on both.
+ *
+ * @example
+ * export const shipmentDelivered = new WorkflowSignal<CarrierEvent>('shipment.delivered');
+ */
+export class WorkflowSignal {
+    constructor(name) {
+        this.name = name;
+        assertSignalName(name);
+    }
+}
+export function assertSignalName(name) {
+    if (typeof name !== 'string' || name.length === 0) {
+        throw new TypeError(`Invalid signal name ${JSON.stringify(name)}. Use a non-empty string such as "shipment.delivered".`);
+    }
+    if (name.startsWith('$')) {
+        throw new TypeError(`Invalid signal name "${name}": names starting with "$" are reserved for the engine's own signals.`);
+    }
+}
+export function signalName(signal) {
+    const name = typeof signal === 'string' ? signal : signal?.name;
+    assertSignalName(name);
+    return name;
+}

package/dist/sql/rate-windows.d.ts

@@ -0,0 +1,41 @@
+import type { WorkflowClaimRequest } from '../interfaces/workflow-store.interface.js';
+/** An instance a claim under rate limits picked and locked, in claim order. */
+export interface PickedInstance {
+    id: string;
+    workflow: string;
+    rateLimitKey: string | null;
+}
+/** A rate-limit window's row: its workflow's own (`key` ''), or a rate-limit key's. */
+export interface RateWindowRow {
+    workflow: string;
+    key: string;
+    windowEnd: number;
+    count: number;
+}
+/**
+ * The rate-limit windows of one claim (`WorkflowStore.claim()` under `rateLimits`), as the SQL stores take room in
+ * them: lock the rows of `windows` (inserted where missing, so there is always a row to lock), in that order, which is
+ * every claim's order; read them; then write back what `grant()` changed. The counts read under the locks are exact:
+ * a concurrent claim of the same window waits for this one.
+ */
+export declare class RateWindowClaim {
+    private readonly request;
+    private readonly picked;
+    /** The windows the picked instances take room in, each once, by workflow then key. */
+    readonly windows: ReadonlyArray<{
+        workflow: string;
+        key: string;
+    }>;
+    private readonly rules;
+    constructor(request: WorkflowClaimRequest, picked: readonly PickedInstance[]);
+    /**
+     * Of the picked instances (in claim order), those their windows have room for, and the windows whose rows change:
+     * a window that ended counts as none, and the first claim after it opens the next one, `duration` long. `locked`:
+     * the windows' rows as read under their locks.
+     */
+    grant(locked: readonly RateWindowRow[]): {
+        granted: string[];
+        changed: RateWindowRow[];
+    };
+    private windowsOf;
+}

package/dist/sql/rate-windows.js

@@ -0,0 +1,53 @@
+/**
+ * The rate-limit windows of one claim (`WorkflowStore.claim()` under `rateLimits`), as the SQL stores take room in
+ * them: lock the rows of `windows` (inserted where missing, so there is always a row to lock), in that order, which is
+ * every claim's order; read them; then write back what `grant()` changed. The counts read under the locks are exact:
+ * a concurrent claim of the same window waits for this one.
+ */
+export class RateWindowClaim {
+    constructor(request, picked) {
+        this.request = request;
+        this.picked = picked;
+        this.rules = new Map((request.rateLimits ?? []).map((rule) => [rule.workflow, rule]));
+        const named = new Map(picked.flatMap((instance) => this.windowsOf(instance)).map((window) => [nameOf(window), window]));
+        this.windows = [...named.values()]
+            .map(({ workflow, key }) => ({ workflow, key }))
+            .sort((a, b) => (a.workflow < b.workflow ? -1 : a.workflow > b.workflow ? 1 : a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    }
+    /**
+     * Of the picked instances (in claim order), those their windows have room for, and the windows whose rows change:
+     * a window that ended counts as none, and the first claim after it opens the next one, `duration` long. `locked`:
+     * the windows' rows as read under their locks.
+     */
+    grant(locked) {
+        const { now } = this.request;
+        const open = new Map(locked.map((row) => [nameOf(row), row.windowEnd > now ? { windowEnd: row.windowEnd, count: row.count } : null]));
+        const granted = [];
+        const changed = new Map();
+        for (const instance of this.picked) {
+            const windows = this.windowsOf(instance);
+            if (!windows.every((window) => (open.get(nameOf(window))?.count ?? 0) < window.max)) {
+                continue;
+            }
+            for (const window of windows) {
+                const name = nameOf(window);
+                const current = open.get(name) ?? { windowEnd: now + window.duration, count: 0 };
+                current.count++;
+                open.set(name, current);
+                changed.set(name, { workflow: window.workflow, key: window.key, ...current });
+            }
+            granted.push(instance.id);
+        }
+        return { granted, changed: [...changed.values()] };
+    }
+    windowsOf({ workflow, rateLimitKey }) {
+        const rule = this.rules.get(workflow);
+        return [
+            ...(rule?.limit ? [{ workflow, key: '', ...rule.limit }] : []),
+            ...(rule?.perKey && rateLimitKey !== null ? [{ workflow, key: rateLimitKey, ...rule.perKey }] : []),
+        ];
+    }
+}
+function nameOf(window) {
+    return JSON.stringify([window.workflow, window.key]);
+}

package/dist/sql/workflow-rows.d.ts

@@ -0,0 +1,16 @@
+import type { WorkflowInstance, WorkflowStatus } from '../interfaces/workflow-instance.interface.js';
+import type { WorkflowScheduleRecord } from '../interfaces/workflow-store.interface.js';
+/** A row as the SQL stores read it: every column cast to text (see the kit's `columns()`). */
+export type Row = Record<string, string | null>;
+/** The statuses a claim takes: an instance that hasn't finished. */
+export declare const RUNNABLE_STATUSES: readonly WorkflowStatus[];
+/** The statuses a cancel applies to (a terminate: `RUNNABLE_STATUSES`). */
+export declare const CANCELLABLE_STATUSES: readonly WorkflowStatus[];
+/** An instance's columns, as `toInstance()` reads them. */
+export declare const INSTANCE_COLUMNS: readonly string[];
+/** A schedule's columns, as `toSchedule()` reads them. */
+export declare const SCHEDULE_COLUMNS: readonly string[];
+/** The columns of a signal as `WorkflowStore.signals()` returns it. */
+export declare const SIGNAL_COLUMNS: readonly string[];
+export declare function toInstance(row: Row): WorkflowInstance;
+export declare function toSchedule(row: Row): WorkflowScheduleRecord;