@nestjs/workflows 0.0.1

package/dist/core/time/duration.js

@@ -0,0 +1,30 @@
+const UNITS = {
+    ms: 1,
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 604_800_000,
+};
+/**
+ * A `Duration` in milliseconds (a string's rounded to a whole one). Throws a `TypeError` for a negative or
+ * non-finite number, or a string it can't read.
+ *
+ * ```ts
+ * parseDuration('15m'); // 900_000
+ * parseDuration(250); // 250
+ * ```
+ */
+export function parseDuration(duration) {
+    if (typeof duration === 'number') {
+        if (!Number.isFinite(duration) || duration < 0) {
+            throw new TypeError(`Invalid duration ${duration}. Use a non-negative number of milliseconds.`);
+        }
+        return duration;
+    }
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d|w)$/.exec(duration);
+    if (!match) {
+        throw new TypeError(`Invalid duration "${duration}". Use milliseconds or a string such as "15m" or "3d".`);
+    }
+    return Math.round(Number(match[1]) * UNITS[match[2]]);
+}

package/dist/core/time/index.d.ts

@@ -0,0 +1,2 @@
+export * from './clock.js';
+export * from './duration.js';

package/dist/core/time/index.js

@@ -0,0 +1,2 @@
+export * from './clock.js';
+export * from './duration.js';

package/dist/core/utils/canonical.util.d.ts

@@ -0,0 +1,2 @@
+/** JSON with sorted object keys, to compare inputs and payloads by value. */
+export declare function canonical(value: unknown): string;

package/dist/core/utils/canonical.util.js

@@ -0,0 +1,4 @@
+/** JSON with sorted object keys, to compare inputs and payloads by value. */
+export function canonical(value) {
+    return (JSON.stringify(value, (_key, v) => v && typeof v === 'object' && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) : v) ?? 'undefined');
+}

package/dist/core/utils/maybe.util.d.ts

@@ -0,0 +1,8 @@
+/** A value, or a promise of it: what a synchronous codec keeps synchronous. */
+export type Maybe<T> = T | Promise<T>;
+/**
+ * `next(value)`, at once when `value` isn't a promise: nothing is awaited before a synchronous codec's result. (Not
+ * named `then`: a module that exports a `then` is a thenable, which a dynamic import awaits.)
+ */
+export declare function andThen<T, R>(value: Maybe<T>, next: (value: T) => Maybe<R>): Maybe<R>;
+export declare function toPromise<T>(value: Maybe<T>): Promise<T>;

package/dist/core/utils/maybe.util.js

@@ -0,0 +1,14 @@
+/**
+ * `next(value)`, at once when `value` isn't a promise: nothing is awaited before a synchronous codec's result. (Not
+ * named `then`: a module that exports a `then` is a thenable, which a dynamic import awaits.)
+ */
+export function andThen(value, next) {
+    return thenable(value) ? Promise.resolve(value).then(next) : next(value);
+}
+export function toPromise(value) {
+    return Promise.resolve(value);
+}
+/** A promise, from this realm or not (a codec's library may bring its own). */
+function thenable(value) {
+    return typeof value?.then === 'function';
+}

package/dist/core/utils/payload-place.util.d.ts

@@ -0,0 +1,10 @@
+import type { PayloadContext } from '../interfaces/payload-codec.interface.js';
+/** The keys of workflows' payload contexts, in the order their authenticated data lists them. */
+export declare const WORKFLOW_PLACES: readonly ['instanceId', 'entry', 'signal', 'schedule'];
+/**
+ * Where a payload is, for errors: `entry "charge" of instance "order-1" (result)` for workflows' contexts, and the
+ * context's keys otherwise (`job "42", queue "emails" (data)`).
+ */
+export declare function describePlace(context: PayloadContext): string;
+/** The context's keys other than `field` and workflows' own, that hold a value, by name. */
+export declare function otherPlaces(context: PayloadContext): string[];

package/dist/core/utils/payload-place.util.js

@@ -0,0 +1,32 @@
+/** The keys of workflows' payload contexts, in the order their authenticated data lists them. */
+export const WORKFLOW_PLACES = ['instanceId', 'entry', 'signal', 'schedule'];
+/**
+ * Where a payload is, for errors: `entry "charge" of instance "order-1" (result)` for workflows' contexts, and the
+ * context's keys otherwise (`job "42", queue "emails" (data)`).
+ */
+export function describePlace(context) {
+    let where;
+    if (context.entry !== undefined) {
+        where = `entry "${context.entry}" of instance "${context.instanceId}"`;
+    }
+    else if (context.instanceId !== undefined) {
+        where = `instance "${context.instanceId}"`;
+    }
+    else if (context.signal !== undefined) {
+        where = `signal "${context.signal}"`;
+    }
+    else if (context.schedule !== undefined) {
+        where = `schedule "${context.schedule}"`;
+    }
+    else {
+        const keys = otherPlaces(context);
+        where = keys.length > 0 ? keys.map((key) => `${key} "${context[key]}"`).join(', ') : 'an unnamed place';
+    }
+    return `${where} (${context.field})`;
+}
+/** The context's keys other than `field` and workflows' own, that hold a value, by name. */
+export function otherPlaces(context) {
+    return Object.keys(context)
+        .filter((key) => key !== 'field' && !WORKFLOW_PLACES.includes(key) && context[key] !== undefined)
+        .sort();
+}

package/dist/core/workers/index.d.ts

@@ -0,0 +1 @@
+export * from './leased-worker.js';

package/dist/core/workers/index.js

@@ -0,0 +1 @@
+export * from './leased-worker.js';

package/dist/core/workers/leased-worker.d.ts

@@ -0,0 +1,86 @@
+import type { LeasedWorkerOptions } from '../interfaces/leased-worker-options.interface.js';
+/**
+ * A claim-execute loop under leases, any number of processes sharing a store: it claims due items (as many as it has
+ * free slots), executes them, renews each one's lease every `heartbeatInterval` (a third of the lease by default), and
+ * aborts an item's `signal` when a renewal finds its lease gone. It looks for work every `pollInterval`, and at once
+ * after `kick()` (a local write made something due) or when an item ends. `drain()` runs due items on demand, for
+ * tests and scripts.
+ *
+ * Shutdown is graceful: call `shutdown()` from `onModuleDestroy`. It stops claiming, waits for the claims in flight
+ * (what they claim starts, told to stop at once), aborts every running item's `signal`, and waits up to
+ * `shutdownTimeout` for them; the ones still running are then detached (no more renewals) and keep their lease until
+ * it expires, as their work may still be going on.
+ *
+ * ```ts
+ * @Injectable()
+ * export class JobWorker implements OnApplicationBootstrap, OnModuleDestroy {
+ *   private readonly worker = new LeasedWorker<Job>({
+ *     claim: (lease, limit) => this.store.claim(lease, limit),
+ *     renew: (job, until) => this.store.renew(job.id, job.token, until),
+ *     execute: (job, run) => this.run(job, run),
+ *   });
+ *
+ *   constructor(private readonly store: JobStore) {}
+ *
+ *   onApplicationBootstrap() {
+ *     this.worker.start();
+ *   }
+ *
+ *   onModuleDestroy() {
+ *     return this.worker.shutdown();
+ *   }
+ * }
+ * ```
+ */
+export declare class LeasedWorker<T> {
+    private readonly options;
+    /** The worker's id, shown as the lease owner. */
+    readonly owner: string;
+    /** The lease duration, in milliseconds. */
+    readonly leaseMs: number;
+    private readonly logger;
+    private readonly clock;
+    private readonly concurrency;
+    private readonly pollMs;
+    private readonly heartbeatMs;
+    private readonly shutdownMs;
+    private readonly produceMs;
+    private readonly runs;
+    /** Claims in flight: shutdown waits for them, so nothing they claim starts unobserved. */
+    private readonly claiming;
+    private stopped;
+    private stop;
+    private readonly stoppedPromise;
+    private wake?;
+    private kicked;
+    private loop?;
+    /** When the loop next calls `produce()` (`performance.now()`). */
+    private produceAt;
+    constructor(options: LeasedWorkerOptions<T>);
+    /** The items it executes now. */
+    get running(): T[];
+    /** Starts the polling loop (once). Without it, the worker only runs what `drain()` asks for. */
+    start(): void;
+    /** Look for work now instead of at the next poll (after a write in this process made something due). */
+    kick(): void;
+    /**
+     * Executes every due item, round after round (`produce()`, then a claim of `concurrency` items, awaited), until a
+     * round finds nothing: for tests (with a `ManualClock`), scripts, and workers a cron drives. Resolves to the
+     * number of items it executed. A claim or production that fails rejects it.
+     */
+    drain(options?: {
+        maxRounds?: number;
+    }): Promise<number>;
+    /**
+     * Stops for good: no more claims, the claims in flight awaited, every running item's `signal` aborted, and at most
+     * `shutdownTimeout` spent waiting for them before the rest are detached. Call it from `onModuleDestroy`.
+     */
+    shutdown(): Promise<void>;
+    private poll;
+    private idle;
+    /** Claims due items and starts executing them (before any caller sees them). */
+    private claim;
+    private launch;
+    private renew;
+    private report;
+}

package/dist/core/workers/leased-worker.js

@@ -0,0 +1,280 @@
+import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import { Logger } from '@nestjs/common';
+import { systemClock } from '../time/clock.js';
+import { parseDuration } from '../time/duration.js';
+/**
+ * A claim-execute loop under leases, any number of processes sharing a store: it claims due items (as many as it has
+ * free slots), executes them, renews each one's lease every `heartbeatInterval` (a third of the lease by default), and
+ * aborts an item's `signal` when a renewal finds its lease gone. It looks for work every `pollInterval`, and at once
+ * after `kick()` (a local write made something due) or when an item ends. `drain()` runs due items on demand, for
+ * tests and scripts.
+ *
+ * Shutdown is graceful: call `shutdown()` from `onModuleDestroy`. It stops claiming, waits for the claims in flight
+ * (what they claim starts, told to stop at once), aborts every running item's `signal`, and waits up to
+ * `shutdownTimeout` for them; the ones still running are then detached (no more renewals) and keep their lease until
+ * it expires, as their work may still be going on.
+ *
+ * ```ts
+ * @Injectable()
+ * export class JobWorker implements OnApplicationBootstrap, OnModuleDestroy {
+ *   private readonly worker = new LeasedWorker<Job>({
+ *     claim: (lease, limit) => this.store.claim(lease, limit),
+ *     renew: (job, until) => this.store.renew(job.id, job.token, until),
+ *     execute: (job, run) => this.run(job, run),
+ *   });
+ *
+ *   constructor(private readonly store: JobStore) {}
+ *
+ *   onApplicationBootstrap() {
+ *     this.worker.start();
+ *   }
+ *
+ *   onModuleDestroy() {
+ *     return this.worker.shutdown();
+ *   }
+ * }
+ * ```
+ */
+export class LeasedWorker {
+    constructor(options) {
+        this.options = options;
+        this.runs = new Set();
+        /** Claims in flight: shutdown waits for them, so nothing they claim starts unobserved. */
+        this.claiming = new Set();
+        this.stopped = false;
+        this.stoppedPromise = new Promise((resolve) => (this.stop = resolve));
+        this.kicked = false;
+        /** When the loop next calls `produce()` (`performance.now()`). */
+        this.produceAt = 0;
+        const name = options.name ?? 'worker';
+        this.logger = new Logger(name);
+        this.clock = options.clock ?? systemClock;
+        this.owner = options.owner ?? `${hostname()}:${process.pid}:${randomUUID().slice(0, 8)}`;
+        this.leaseMs = parseDuration(options.leaseDuration ?? '30s');
+        this.concurrency = options.concurrency ?? 10;
+        this.pollMs = parseDuration(options.pollInterval ?? '1s');
+        this.heartbeatMs = parseDuration(options.heartbeatInterval ?? Math.floor(this.leaseMs / 3));
+        this.shutdownMs = parseDuration(options.shutdownTimeout ?? '10s');
+        this.produceMs = parseDuration(options.produceInterval ?? 0);
+        if (!Number.isInteger(this.concurrency) || this.concurrency < 1) {
+            throw new TypeError(`${name}.concurrency (${this.concurrency}) must be a positive integer.`);
+        }
+        if (this.pollMs <= 0 || this.heartbeatMs <= 0) {
+            throw new TypeError(`${name}.pollInterval and ${name}.heartbeatInterval must be positive, such as "1s".`);
+        }
+        if (this.heartbeatMs >= this.leaseMs) {
+            throw new TypeError(`${name}.heartbeatInterval (${this.heartbeatMs}ms) must be shorter than ${name}.leaseDuration (${this.leaseMs}ms).`);
+        }
+    }
+    /** The items it executes now. */
+    get running() {
+        return [...this.runs].map((run) => run.item);
+    }
+    /** Starts the polling loop (once). Without it, the worker only runs what `drain()` asks for. */
+    start() {
+        if (!this.loop && !this.stopped) {
+            this.loop = this.poll();
+        }
+    }
+    /** Look for work now instead of at the next poll (after a write in this process made something due). */
+    kick() {
+        this.kicked = true;
+        this.wake?.();
+    }
+    /**
+     * Executes every due item, round after round (`produce()`, then a claim of `concurrency` items, awaited), until a
+     * round finds nothing: for tests (with a `ManualClock`), scripts, and workers a cron drives. Resolves to the
+     * number of items it executed. A claim or production that fails rejects it.
+     */
+    async drain(options = {}) {
+        let total = 0;
+        for (let round = 0; round < (options.maxRounds ?? 1_000) && !this.stopped; round++) {
+            const produced = this.options.produce ? await this.options.produce() : 0;
+            const executions = await this.claim(this.concurrency);
+            if (executions.length === 0 && produced === 0) {
+                break;
+            }
+            total += executions.length;
+            await Promise.race([Promise.all(executions), this.stoppedPromise]);
+        }
+        return total;
+    }
+    /**
+     * Stops for good: no more claims, the claims in flight awaited, every running item's `signal` aborted, and at most
+     * `shutdownTimeout` spent waiting for them before the rest are detached. Call it from `onModuleDestroy`.
+     */
+    async shutdown() {
+        if (this.stopped) {
+            return;
+        }
+        this.stopped = true;
+        this.stop();
+        this.wake?.();
+        // What a claim in flight claims starts now, told to stop at once, so it is handed back before the store closes.
+        await Promise.allSettled(this.claiming);
+        for (const run of this.runs) {
+            run.halt();
+        }
+        let timer;
+        await Promise.race([
+            Promise.allSettled([...this.runs].map((run) => run.done)),
+            new Promise((resolve) => (timer = setTimeout(resolve, this.shutdownMs))),
+        ]);
+        clearTimeout(timer);
+        for (const run of this.runs) {
+            run.detach();
+        }
+        await this.loop;
+    }
+    async poll() {
+        while (!this.stopped) {
+            if (this.options.produce && performance.now() >= this.produceAt) {
+                this.produceAt = performance.now() + this.produceMs;
+                try {
+                    await this.options.produce();
+                }
+                catch (error) {
+                    this.report(error, 'produce');
+                }
+            }
+            const free = this.concurrency - this.runs.size;
+            if (free > 0) {
+                try {
+                    const executions = await this.claim(free);
+                    for (const execution of executions) {
+                        void execution.finally(() => this.kick());
+                    }
+                }
+                catch (error) {
+                    this.report(error, 'claim');
+                }
+            }
+            await this.idle();
+        }
+    }
+    idle() {
+        if (this.kicked || this.stopped) {
+            this.kicked = false;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(timer);
+                this.wake = undefined;
+                resolve();
+            };
+            const timer = setTimeout(done, this.pollMs);
+            this.wake = () => {
+                this.kicked = false;
+                done();
+            };
+        });
+    }
+    /** Claims due items and starts executing them (before any caller sees them). */
+    async claim(limit) {
+        if (limit <= 0) {
+            return [];
+        }
+        const now = this.clock.now();
+        const lease = { owner: this.owner, token: randomUUID(), now, until: now + this.leaseMs };
+        const claim = this.options.claim(lease, limit);
+        this.claiming.add(claim);
+        try {
+            const items = await claim;
+            return items.map((item) => this.launch(item));
+        }
+        finally {
+            this.claiming.delete(claim);
+        }
+    }
+    launch(item) {
+        const run = new Run(item, () => this.renew(run));
+        this.runs.add(run);
+        if (this.stopped) {
+            run.halt();
+        }
+        run.heartbeat = setInterval(() => void run.renew(), this.heartbeatMs);
+        run.heartbeat.unref();
+        let executing;
+        try {
+            executing = this.options.execute(item, run);
+        }
+        catch (error) {
+            executing = Promise.reject(error);
+        }
+        run.done = executing
+            .catch((error) => this.report(error, 'execute'))
+            .finally(() => {
+            clearInterval(run.heartbeat);
+            this.runs.delete(run);
+        });
+        return run.done;
+    }
+    renew(run) {
+        return this.options.renew(run.item, this.clock.now() + this.leaseMs);
+    }
+    report(error, stage) {
+        if (this.options.onError) {
+            this.options.onError(error, stage);
+        }
+        else {
+            this.logger.error(`${stage === 'claim' ? 'Claiming' : stage === 'produce' ? 'Producing' : 'Executing'} failed; the worker carries on.`, error);
+        }
+    }
+}
+/** A claimed item's run: its signal, its heartbeat, and what became of its lease. */
+class Run {
+    constructor(item, renewer) {
+        this.item = item;
+        this.renewer = renewer;
+        this.controller = new AbortController();
+        this.lost = false;
+        this.isDetached = false;
+    }
+    get signal() {
+        return this.controller.signal;
+    }
+    get leaseLost() {
+        return this.lost;
+    }
+    get detached() {
+        return this.isDetached;
+    }
+    async renew() {
+        if (this.lost || this.isDetached) {
+            return !this.lost;
+        }
+        let held;
+        try {
+            held = await this.renewer();
+        }
+        catch {
+            // Transient: the next heartbeat tries again before the lease runs out.
+            return true;
+        }
+        if (!held) {
+            this.loseLease();
+        }
+        return held;
+    }
+    loseLease() {
+        if (this.lost) {
+            return;
+        }
+        this.lost = true;
+        clearInterval(this.heartbeat);
+        this.controller.abort(new Error('The lease was lost: another worker may run this item now.'));
+    }
+    /** The worker shuts down: its work should stop. */
+    halt() {
+        if (!this.controller.signal.aborted) {
+            this.controller.abort(new Error('The worker is shutting down.'));
+        }
+    }
+    /** The worker stopped waiting for it: no more renewals. */
+    detach() {
+        this.isDetached = true;
+        clearInterval(this.heartbeat);
+    }
+}

package/dist/cqrs/decorators/index.d.ts

@@ -0,0 +1,2 @@
+export * from './signal-on.decorator.js';
+export * from './start-on.decorator.js';

package/dist/cqrs/decorators/index.js

@@ -0,0 +1,2 @@
+export * from './signal-on.decorator.js';
+export * from './start-on.decorator.js';

package/dist/cqrs/decorators/signal-on.decorator.d.ts

@@ -0,0 +1,18 @@
+import type { Type } from '@nestjs/common';
+import type { SignalOnOptions } from '../interfaces/signal-on-options.interface.js';
+/**
+ * Sends `signal` whenever the application publishes `event` on the CQRS `EventBus`, through
+ * `WorkflowClient.signal()`: in the publisher's transaction when it passes `{ transaction }` as
+ * the dispatcher context, and before `publish()` resolves. Declare it on the workflow that
+ * waits for the signal. Needs `WorkflowsCqrsModule`.
+ *
+ * A signal reaches every instance waiting for it with the same key, whatever its workflow, so
+ * when several workflows (or versions) map one event to the same signal and key, it is sent once.
+ * With `id`, an event published again (a redelivery, a retried handler) stores no second signal.
+ *
+ * @example
+ * @Workflow('order-fulfilment')
+ * @SignalOn(OrderDeliveredEvent, { signal: shipmentDelivered, key: (event) => event.orderId, id: (event) => event.deliveryId })
+ * export class OrderFulfilmentWorkflow implements WorkflowRunner<Order, FulfilmentResult> {}
+ */
+export declare function SignalOn<E extends object, T>(event: Type<E>, options: SignalOnOptions<E, T>): ClassDecorator;

package/dist/cqrs/decorators/signal-on.decorator.js

@@ -0,0 +1,34 @@
+import { signalName } from '../../signals/workflow.signal.js';
+import { addEventRoute, assertEventClass, assertMapper } from '../utils/event-routes.util.js';
+/**
+ * Sends `signal` whenever the application publishes `event` on the CQRS `EventBus`, through
+ * `WorkflowClient.signal()`: in the publisher's transaction when it passes `{ transaction }` as
+ * the dispatcher context, and before `publish()` resolves. Declare it on the workflow that
+ * waits for the signal. Needs `WorkflowsCqrsModule`.
+ *
+ * A signal reaches every instance waiting for it with the same key, whatever its workflow, so
+ * when several workflows (or versions) map one event to the same signal and key, it is sent once.
+ * With `id`, an event published again (a redelivery, a retried handler) stores no second signal.
+ *
+ * @example
+ * @Workflow('order-fulfilment')
+ * @SignalOn(OrderDeliveredEvent, { signal: shipmentDelivered, key: (event) => event.orderId, id: (event) => event.deliveryId })
+ * export class OrderFulfilmentWorkflow implements WorkflowRunner<Order, FulfilmentResult> {}
+ */
+export function SignalOn(event, options) {
+    assertEventClass('SignalOn', event);
+    const signal = signalName(options?.signal);
+    assertMapper('SignalOn', event, 'key', options.key);
+    assertMapper('SignalOn', event, 'id', options.id);
+    assertMapper('SignalOn', event, 'payload', options.payload);
+    return (target) => {
+        addEventRoute(target, {
+            kind: 'signal',
+            event,
+            signal,
+            key: options.key,
+            id: options.id,
+            payload: options.payload,
+        });
+    };
+}

package/dist/cqrs/decorators/start-on.decorator.d.ts

@@ -0,0 +1,18 @@
+import type { Type } from '@nestjs/common';
+import type { WorkflowRunner } from '../../interfaces/workflow-runner.interface.js';
+import type { StartOnOptions } from '../interfaces/start-on-options.interface.js';
+/**
+ * Starts the decorated `@Workflow()` whenever the application publishes `event` on the CQRS
+ * `EventBus`, through `WorkflowClient.start()`: in the publisher's transaction when it passes
+ * `{ transaction }` as the dispatcher context, and before `publish()` resolves. `id` makes a
+ * repeated event find the instance the first one started. Needs `WorkflowsCqrsModule`.
+ *
+ * When several versions of a workflow are registered, the highest version's `@StartOn()`
+ * decorators decide what starts it.
+ *
+ * @example
+ * @Workflow('order-fulfilment')
+ * @StartOn(OrderPlacedEvent, { id: (event) => `order-${event.order.id}`, input: (event) => event.order })
+ * export class OrderFulfilmentWorkflow implements WorkflowRunner<Order, FulfilmentResult> {}
+ */
+export declare function StartOn<E extends object, I = E>(event: Type<E>, options: StartOnOptions<E, I>): <W extends Type<WorkflowRunner<I, unknown>>>(target: W) => void;

package/dist/cqrs/decorators/start-on.decorator.js

@@ -0,0 +1,49 @@
+import { isPriority, MAX_PRIORITY } from '../../core/limits/limits.js';
+import { addEventRoute, assertEventClass, assertMapper } from '../utils/event-routes.util.js';
+/**
+ * Starts the decorated `@Workflow()` whenever the application publishes `event` on the CQRS
+ * `EventBus`, through `WorkflowClient.start()`: in the publisher's transaction when it passes
+ * `{ transaction }` as the dispatcher context, and before `publish()` resolves. `id` makes a
+ * repeated event find the instance the first one started. Needs `WorkflowsCqrsModule`.
+ *
+ * When several versions of a workflow are registered, the highest version's `@StartOn()`
+ * decorators decide what starts it.
+ *
+ * @example
+ * @Workflow('order-fulfilment')
+ * @StartOn(OrderPlacedEvent, { id: (event) => `order-${event.order.id}`, input: (event) => event.order })
+ * export class OrderFulfilmentWorkflow implements WorkflowRunner<Order, FulfilmentResult> {}
+ */
+export function StartOn(event, options) {
+    assertEventClass('StartOn', event);
+    assertMapper('StartOn', event, 'id', options?.id, true);
+    assertMapper('StartOn', event, 'input', options.input);
+    assertPriority(event, options.priority);
+    assertKey(event, 'concurrencyKey', options.concurrencyKey);
+    assertKey(event, 'rateLimitKey', options.rateLimitKey);
+    return (target) => {
+        addEventRoute(target, {
+            kind: 'start',
+            event,
+            id: options.id,
+            input: options.input,
+            priority: options.priority,
+            concurrencyKey: options.concurrencyKey,
+            rateLimitKey: options.rateLimitKey,
+        });
+    };
+}
+function assertPriority(event, priority) {
+    if (priority === undefined || typeof priority === 'function') {
+        return;
+    }
+    if (!isPriority(priority)) {
+        throw new TypeError(`@StartOn(${event.name}): invalid priority ${JSON.stringify(priority)}. Use an integer from 1 (first) to ${MAX_PRIORITY}, or a function of the event.`);
+    }
+}
+function assertKey(event, option, key) {
+    if (key === undefined || typeof key === 'function' || (typeof key === 'string' && key.length > 0)) {
+        return;
+    }
+    throw new TypeError(`@StartOn(${event.name}): \`${option}\` must be a non-empty string, or a function of the event, such as (event) => event.warehouseId.`);
+}

package/dist/cqrs/index.d.ts

@@ -0,0 +1,3 @@
+export { WorkflowsCqrsModule } from './workflows-cqrs.module.js';
+export { SignalOn, StartOn } from './decorators/index.js';
+export type { SignalOnOptions, StartOnOptions, WorkflowDispatcherContext } from './interfaces/index.js';

package/dist/cqrs/index.js

@@ -0,0 +1,5 @@
+// The `@nestjs/workflows/cqrs` entry: the only files that import `@nestjs/cqrs`.
+// Module: wraps the EventBus publisher, so mapped events start and signal workflows
+export { WorkflowsCqrsModule } from './workflows-cqrs.module.js';
+// Mapping events to workflows, and the dispatcher context that carries your transaction
+export { SignalOn, StartOn } from './decorators/index.js';

package/dist/cqrs/interfaces/index.d.ts

@@ -0,0 +1,4 @@
+export * from './signal-on-options.interface.js';
+export * from './start-on-options.interface.js';
+export * from './workflow-dispatcher-context.interface.js';
+export * from './workflow-event-route.interface.js';

package/dist/cqrs/interfaces/index.js

@@ -0,0 +1,4 @@
+export * from './signal-on-options.interface.js';
+export * from './start-on-options.interface.js';
+export * from './workflow-dispatcher-context.interface.js';
+export * from './workflow-event-route.interface.js';