@nestjs/workflows 0.0.1

package/dist/cqrs/interfaces/signal-on-options.interface.d.ts

@@ -0,0 +1,22 @@
+import type { WorkflowSignal } from '../../signals/workflow.signal.js';
+/**
+ * How `@SignalOn()` turns an event into a `WorkflowClient.signal()` call. `payload` may be
+ * left out when the event itself has the signal's payload type.
+ */
+export type SignalOnOptions<E, T> = {
+    /** The signal the workflow waits for with `ctx.waitForSignal()`. */
+    signal: WorkflowSignal<T> | string;
+    /** The correlation key, such as the order id. Without one, only waits without a key match. */
+    key?: (event: E) => string;
+    /**
+     * The signal's deduplication id (`WorkflowClient.signal()`'s `id`), such as the id of the
+     * delivery the event reports: an event published again sends nothing new. Without one, the
+     * signal is sent each time the event is published, except from inside a workflow step,
+     * where the id derives from the step's `idempotencyKey`.
+     */
+    id?: (event: E) => string;
+} & ([E] extends [T] ? {
+    payload?: (event: E) => T;
+} : {
+    payload: (event: E) => T;
+});

package/dist/cqrs/interfaces/signal-on-options.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/cqrs/interfaces/start-on-options.interface.d.ts

@@ -0,0 +1,23 @@
+/** How `@StartOn()` turns an event into a `WorkflowClient.start()` call. */
+export interface StartOnOptions<E, I> {
+    /**
+     * The instance id, from the event's business key (`order-${event.order.id}`). An event
+     * published twice then finds the instance the first one started, instead of starting another.
+     */
+    id: (event: E) => string;
+    /** The workflow's input. Default: the event itself, as JSON (its own enumerable fields). */
+    input?: (event: E) => I;
+    /**
+     * The instance's priority, as `WorkflowClient.start()`'s: lower is claimed first, an integer from 1 to
+     * 2,097,151. A number, or a function of the event that returns one, or `undefined` for none. Default: none.
+     */
+    priority?: number | ((event: E) => number | undefined);
+    /**
+     * The key the workflow's per-key concurrency limit counts the instance under, instead of the one its
+     * `concurrency.key` computes from the input, as `start()`'s `concurrencyKey`: a string, or a function of the event
+     * that returns one, or `undefined` for the computed one. Needs a concurrency limit with a `key`.
+     */
+    concurrencyKey?: string | ((event: E) => string | undefined);
+    /** The same for the workflow's per-key rate limit, as `start()`'s `rateLimitKey`. Needs a rate limit with a `key`. */
+    rateLimitKey?: string | ((event: E) => string | undefined);
+}

package/dist/cqrs/interfaces/start-on-options.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/cqrs/interfaces/workflow-dispatcher-context.interface.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The dispatcher context `@nestjs/workflows/cqrs` reads from `eventBus.publish(event, context)`,
+ * `publishAll(events, context)` and, with `@nestjs/cqrs` 12.1 or later, an aggregate's
+ * `commit(context)`: `transaction` is your ORM's transaction (Drizzle's `tx`, a TypeORM
+ * `EntityManager`, a Prisma transaction client), so the workflows the events start and the
+ * signals they send commit with your writes, or not at all.
+ */
+export interface WorkflowDispatcherContext {
+    transaction: unknown;
+}

package/dist/cqrs/interfaces/workflow-dispatcher-context.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/cqrs/interfaces/workflow-event-route.interface.d.ts

@@ -0,0 +1,20 @@
+import type { Type } from '@nestjs/common';
+/** What `@StartOn()` and `@SignalOn()` record on a workflow class. */
+export type WorkflowEventRoute = WorkflowStartRoute | WorkflowSignalRoute;
+export interface WorkflowStartRoute {
+    kind: 'start';
+    event: Type<object>;
+    id: (event: object) => string;
+    input?: (event: object) => unknown;
+    priority?: number | ((event: object) => number | undefined);
+    concurrencyKey?: string | ((event: object) => string | undefined);
+    rateLimitKey?: string | ((event: object) => string | undefined);
+}
+export interface WorkflowSignalRoute {
+    kind: 'signal';
+    event: Type<object>;
+    signal: string;
+    key?: (event: object) => string;
+    id?: (event: object) => string;
+    payload?: (event: object) => unknown;
+}

package/dist/cqrs/interfaces/workflow-event-route.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/cqrs/utils/event-routes.util.d.ts

@@ -0,0 +1,7 @@
+import type { Type } from '@nestjs/common';
+import type { WorkflowEventRoute } from '../interfaces/workflow-event-route.interface.js';
+/** The class's own routes, in declaration order (decorators apply bottom-up). */
+export declare function eventRoutesOf(target: Function): WorkflowEventRoute[];
+export declare function addEventRoute(target: Function, route: WorkflowEventRoute): void;
+export declare function assertEventClass(decorator: string, event: unknown): asserts event is Type<object>;
+export declare function assertMapper(decorator: string, event: Type<object>, option: string, value: unknown, required?: boolean): void;

package/dist/cqrs/utils/event-routes.util.js

@@ -0,0 +1,22 @@
+import { WORKFLOW_EVENT_ROUTES_METADATA } from '../../workflows.constants.js';
+/** The class's own routes, in declaration order (decorators apply bottom-up). */
+export function eventRoutesOf(target) {
+    return Reflect.getOwnMetadata(WORKFLOW_EVENT_ROUTES_METADATA, target) ?? [];
+}
+export function addEventRoute(target, route) {
+    Reflect.defineMetadata(WORKFLOW_EVENT_ROUTES_METADATA, [route, ...eventRoutesOf(target)], target);
+}
+export function assertEventClass(decorator, event) {
+    if (typeof event !== 'function') {
+        throw new TypeError(`@${decorator}() takes the event class first, got ${event === null ? 'null' : typeof event}.`);
+    }
+}
+export function assertMapper(decorator, event, option, value, required = false) {
+    if (value === undefined && !required) {
+        return;
+    }
+    if (typeof value !== 'function') {
+        throw new TypeError(`@${decorator}(${event.name}): \`${option}\` must be a function of the event, such as (event) => event.orderId` +
+            `${required ? '' : ', or left out'}.`);
+    }
+}

package/dist/cqrs/workflow-event.publisher.d.ts

@@ -0,0 +1,52 @@
+import { type OnApplicationBootstrap, type OnModuleInit } from '@nestjs/common';
+import { EventBus, UnhandledExceptionBus, type AsyncContext, type IEvent, type IEventPublisher } from '@nestjs/cqrs';
+import { WorkflowClient } from '../services/workflow-client.service.js';
+import { WorkflowRegistry } from '../services/workflow-registry.service.js';
+import { WorkflowEventsExplorer } from './workflow-events.explorer.js';
+/**
+ * The CQRS `EventBus`'s publisher while `WorkflowsCqrsModule` is imported. It wraps the
+ * publisher that was set before it (the in-memory one that feeds `@EventsHandler()`s and
+ * sagas, or the one from `CqrsModule.forRoot({ eventPublisher })`): for an event that a
+ * workflow maps with `@StartOn()` or `@SignalOn()`, it first starts and signals the workflows,
+ * through the transaction in the dispatcher context when there is one, then hands the event to
+ * the wrapped publisher. Other events go straight through, synchronously, as before.
+ */
+export declare class WorkflowEventPublisher implements IEventPublisher, OnModuleInit, OnApplicationBootstrap {
+    private readonly eventBus;
+    private readonly unhandledExceptionBus;
+    private readonly workflowClient;
+    private readonly explorer;
+    private readonly logger;
+    private readonly inner;
+    private routes?;
+    /** Event classes an aggregate's commit() published, warned about once each. */
+    private readonly committedByAggregates;
+    constructor(eventBus: EventBus, unhandledExceptionBus: UnhandledExceptionBus, workflowClient: WorkflowClient, explorer: WorkflowEventsExplorer, registry: WorkflowRegistry);
+    onModuleInit(): void;
+    onApplicationBootstrap(): void;
+    publish<TEvent extends IEvent>(event: TEvent, dispatcherContext?: unknown, asyncContext?: AsyncContext): unknown;
+    publishAll<TEvent extends IEvent>(events: TEvent[], dispatcherContext?: unknown, asyncContext?: AsyncContext): unknown;
+    /**
+     * Starts and signals the workflows the events map to, then forwards the events. Nothing is
+     * forwarded when a write fails, so a retried publish reaches the handlers once.
+     */
+    private deliver;
+    private write;
+    /**
+     * Every start and signal, computed before any is written: a mapping function that throws
+     * leaves nothing half done. Per event, starts come first, then signals, each signal once.
+     */
+    private plan;
+    /**
+     * The one lossy path this publisher can recognize: an aggregate merged with `EventPublisher`
+     * passes itself as the dispatcher context when `commit()` is given none. (`@Publishable()`
+     * aggregates pass nothing, like any other untransacted publish, so they can't be told apart.)
+     * A warning, not an error: the start or signal still happens, only outside the transaction.
+     */
+    private warnAboutCommit;
+    private report;
+    private isRouted;
+    private targetsOf;
+    /** Built at `onModuleInit`, or at the first publish if another module's hook publishes earlier. */
+    private table;
+}

package/dist/cqrs/workflow-event.publisher.js

@@ -0,0 +1,257 @@
+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);
+};
+import { Injectable, Logger } from '@nestjs/common';
+import { EventBus, UnhandledExceptionBus } from '@nestjs/cqrs';
+import { WorkflowClient } from '../services/workflow-client.service.js';
+import { canonical } from '../core/utils/canonical.util.js';
+import { isPriority, MAX_PRIORITY } from '../core/limits/limits.js';
+import { normalize } from '../utils/normalize.util.js';
+import { ROUTE_EVENTS, WorkflowRegistry } from '../services/workflow-registry.service.js';
+import { WorkflowEventsExplorer } from './workflow-events.explorer.js';
+/**
+ * The CQRS `EventBus`'s publisher while `WorkflowsCqrsModule` is imported. It wraps the
+ * publisher that was set before it (the in-memory one that feeds `@EventsHandler()`s and
+ * sagas, or the one from `CqrsModule.forRoot({ eventPublisher })`): for an event that a
+ * workflow maps with `@StartOn()` or `@SignalOn()`, it first starts and signals the workflows,
+ * through the transaction in the dispatcher context when there is one, then hands the event to
+ * the wrapped publisher. Other events go straight through, synchronously, as before.
+ */
+let WorkflowEventPublisher = class WorkflowEventPublisher {
+    constructor(eventBus, unhandledExceptionBus, workflowClient, explorer, registry) {
+        this.eventBus = eventBus;
+        this.unhandledExceptionBus = unhandledExceptionBus;
+        this.workflowClient = workflowClient;
+        this.explorer = explorer;
+        this.logger = new Logger('WorkflowsCqrsModule');
+        /** Event classes an aggregate's commit() published, warned about once each. */
+        this.committedByAggregates = new Set();
+        // In the constructor, so no lifecycle hook can publish an event before it's installed.
+        this.inner = eventBus.publisher;
+        eventBus.publisher = this;
+        registry[ROUTE_EVENTS]();
+    }
+    onModuleInit() {
+        const routes = this.table();
+        // A process that publishes mapped events without registering their workflows starts and
+        // signals nothing, and would otherwise do so silently.
+        if (routes.size === 0) {
+            this.logger.warn('WorkflowsCqrsModule is imported, but no registered workflow maps an event with @StartOn() or @SignalOn(), so ' +
+                'events start and signal no workflow in this process. Register the workflow classes in every process that ' +
+                'publishes their events, with worker: false in WorkflowsModule.forRoot() if the process runs none.');
+            return;
+        }
+        const described = [...routes].map(([event, { starts, signals }]) => {
+            const actions = [
+                ...starts.map(({ name }) => `starts ${name}`),
+                ...new Set(signals.map(({ route }) => `signals ${route.signal}`)),
+            ];
+            return `${event.name} ${actions.join(', ')}`;
+        });
+        this.logger.log(`Events routed to workflows: ${described.join('; ')}`);
+    }
+    onApplicationBootstrap() {
+        if (this.eventBus.publisher !== this) {
+            throw new Error(`WorkflowsCqrsModule: EventBus.publisher was replaced (by ${this.eventBus.publisher?.constructor?.name ?? 'nothing'}) ` +
+                'after WorkflowsCqrsModule installed its publisher, so events would no longer start or signal workflows. ' +
+                'Set your publisher with CqrsModule.forRoot({ eventPublisher }) instead: WorkflowsCqrsModule wraps it.');
+        }
+    }
+    publish(event, dispatcherContext, asyncContext) {
+        if (!this.isRouted(event)) {
+            return this.inner.publish(event, dispatcherContext, asyncContext);
+        }
+        return this.deliver([event], dispatcherContext, () => this.inner.publish(event, dispatcherContext, asyncContext));
+    }
+    publishAll(events, dispatcherContext, asyncContext) {
+        const forward = (all) => this.inner.publishAll
+            ? this.inner.publishAll(all, dispatcherContext, asyncContext)
+            : all.map((event) => this.inner.publish(event, dispatcherContext, asyncContext));
+        if (!events?.some((event) => this.isRouted(event))) {
+            return forward(events ?? []);
+        }
+        // Copied before anything is awaited: an aggregate's commit() hands over its own array and
+        // empties it as soon as this returns, before the events are forwarded.
+        const all = [...events];
+        return this.deliver(all, dispatcherContext, async () => {
+            const result = forward(all);
+            return Array.isArray(result) ? Promise.all(result) : result;
+        });
+    }
+    /**
+     * Starts and signals the workflows the events map to, then forwards the events. Nothing is
+     * forwarded when a write fails, so a retried publish reaches the handlers once.
+     */
+    deliver(events, context, forward) {
+        const failure = {};
+        const delivered = this.write(events, transactionOf(context), failure).then(forward);
+        // An aggregate's commit() without a dispatcher context: before @nestjs/cqrs 12.1 it drops the
+        // promise this returns, and from 12.1 on nothing may await it either. Report its failures the
+        // way cqrs reports a failing event handler, rather than as an unhandled rejection. (Given a
+        // context, commit() passes it instead of the aggregate, and its caller awaits the result.)
+        if (isAggregate(context)) {
+            this.warnAboutCommit(events);
+            delivered.catch((exception) => this.report(failure.event ?? events[0], exception));
+        }
+        return delivered;
+    }
+    async write(events, transaction, failure) {
+        const writes = this.plan(events);
+        if (transaction === undefined) {
+            for (const write of writes) {
+                failure.event = write.event;
+                await write.run(undefined);
+            }
+            failure.event = undefined;
+            return;
+        }
+        // Issued back to back, not awaited in between: a driver whose transactions are synchronous
+        // must see every statement before the application's callback returns, and on the
+        // transaction's one connection they still run in this order.
+        const settled = await Promise.allSettled(writes.map((write) => write.run(transaction)));
+        const index = settled.findIndex((result) => result.status === 'rejected');
+        if (index !== -1) {
+            failure.event = writes[index].event;
+            throw settled[index].reason;
+        }
+    }
+    /**
+     * Every start and signal, computed before any is written: a mapping function that throws
+     * leaves nothing half done. Per event, starts come first, then signals, each signal once.
+     */
+    plan(events) {
+        const writes = [];
+        for (const event of events) {
+            const targets = this.targetsOf(event);
+            if (!targets) {
+                continue;
+            }
+            for (const { workflow, name, route } of targets.starts) {
+                const id = route.id(event);
+                const input = route.input ? route.input(event) : event;
+                const priority = startOption(event, name, 'priority', route.priority);
+                const concurrencyKey = startOption(event, name, 'concurrencyKey', route.concurrencyKey);
+                const rateLimitKey = startOption(event, name, 'rateLimitKey', route.rateLimitKey);
+                writes.push({
+                    event,
+                    run: (transaction) => this.workflowClient.start(workflow, input, { id, transaction, priority, concurrencyKey, rateLimitKey }),
+                });
+            }
+            // A signal reaches every instance waiting with its name and key, whatever the workflow:
+            // two declarations that agree are one signal, and two that disagree are a mistake.
+            const sent = new Map();
+            for (const { name, route } of targets.signals) {
+                const key = route.key ? route.key(event) : undefined;
+                assertString(event, name, 'key', key, 'Waits match keys exactly, so convert it (String(event.orderId)) on both sides.');
+                const id = route.id ? route.id(event) : undefined;
+                assertString(event, name, 'id', id, 'Derive it from the event, such as event.deliveryId.');
+                const payload = route.payload ? route.payload(event) : event;
+                const identity = JSON.stringify([route.signal, key ?? null]);
+                const json = canonical(normalize(payload) ?? null);
+                const earlier = sent.get(identity);
+                if (earlier) {
+                    if (earlier.payload !== json || earlier.id !== id) {
+                        throw new Error(`${event.constructor.name} maps to two different ${earlier.payload !== json ? 'payloads' : 'ids'} for the signal "${route.signal}"` +
+                            `${key === undefined ? '' : ` (key "${key}")`}: @SignalOn() on ${earlier.name} and on ${name}. ` +
+                            'A signal reaches every instance waiting for it: make the declarations agree, or keep one.');
+                    }
+                    continue;
+                }
+                sent.set(identity, { payload: json, id, name });
+                writes.push({ event, run: (transaction) => this.workflowClient.signal(route.signal, payload, { key, id, transaction }) });
+            }
+        }
+        return writes;
+    }
+    /**
+     * The one lossy path this publisher can recognize: an aggregate merged with `EventPublisher`
+     * passes itself as the dispatcher context when `commit()` is given none. (`@Publishable()`
+     * aggregates pass nothing, like any other untransacted publish, so they can't be told apart.)
+     * A warning, not an error: the start or signal still happens, only outside the transaction.
+     */
+    warnAboutCommit(events) {
+        for (const event of events) {
+            if (!this.isRouted(event) || this.committedByAggregates.has(event.constructor)) {
+                continue;
+            }
+            this.committedByAggregates.add(event.constructor);
+            this.logger.warn(`${event.constructor.name} starts or signals workflows, and an aggregate's commit() published it without ` +
+                'a transaction: the start or signal is written outside your transaction, so it outlives a rollback of your ' +
+                "writes, and a crash before it's written loses it. Pass your transaction and await the result: " +
+                'await aggregate.commit({ transaction }) (@nestjs/cqrs 12.1 or later). With older versions, publish the ' +
+                "aggregate's events with eventBus.publishAll(aggregate.getUncommittedEvents(), { transaction }), then call " +
+                'aggregate.uncommit(). (Logged once per event class.)');
+        }
+    }
+    report(event, exception) {
+        this.logger.error(`Publishing ${event.constructor.name} from an aggregate's commit() without a transaction failed. To handle ` +
+            'the failure in your command handler, and roll its transaction back, await aggregate.commit({ transaction }) ' +
+            "(@nestjs/cqrs 12.1 or later). With older versions, await eventBus.publishAll(aggregate.getUncommittedEvents(), " +
+            '{ transaction }), then call aggregate.uncommit().', exception instanceof Error ? exception.stack : String(exception));
+        this.unhandledExceptionBus.publish({ cause: event, exception });
+    }
+    isRouted(event) {
+        return this.targetsOf(event) !== undefined;
+    }
+    targetsOf(event) {
+        if (event === null || typeof event !== 'object') {
+            return undefined;
+        }
+        return this.table().get(event.constructor);
+    }
+    /** Built at `onModuleInit`, or at the first publish if another module's hook publishes earlier. */
+    table() {
+        return (this.routes ??= this.explorer.explore());
+    }
+};
+WorkflowEventPublisher = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [EventBus,
+        UnhandledExceptionBus,
+        WorkflowClient,
+        WorkflowEventsExplorer,
+        WorkflowRegistry])
+], WorkflowEventPublisher);
+export { WorkflowEventPublisher };
+/**
+ * A `@StartOn()` option for the event: the value it was given, or what its function returns, checked here, before
+ * anything is written, rather than by `start()` once earlier writes of the same publish have landed.
+ */
+function startOption(event, workflow, option, given) {
+    const value = typeof given === 'function' ? given(event) : given;
+    if (value === undefined) {
+        return undefined;
+    }
+    const where = `@StartOn(${event.constructor.name}) on ${workflow}: \`${option}\` returned`;
+    if (option === 'priority') {
+        if (!isPriority(value)) {
+            throw new TypeError(`${where} ${JSON.stringify(value)}. Return an integer from 1 (first) to ${MAX_PRIORITY}, or undefined for none.`);
+        }
+    }
+    else if (typeof value !== 'string' || value.length === 0) {
+        throw new TypeError(`${where} ${value === '' ? 'an empty string' : `${typeof value}, not a string`}. Return a non-empty string, or undefined for the computed one.`);
+    }
+    return value;
+}
+/** A key may be empty (it matches waits for ''), an id may not (WorkflowClient.signal() refuses it). */
+function assertString(event, workflow, option, value, advice) {
+    if (value !== undefined && (typeof value !== 'string' || (option === 'id' && value.length === 0))) {
+        throw new TypeError(`@SignalOn(${event.constructor.name}) on ${workflow}: \`${option}\` returned ${value === '' ? 'an empty string' : `${typeof value}, not a string`}. ${advice}`);
+    }
+}
+/** The dispatcher context's `transaction`. An aggregate (what `mergeObjectContext()` passes) never has one. */
+function transactionOf(context) {
+    if (context === null || typeof context !== 'object' || isAggregate(context)) {
+        return undefined;
+    }
+    return context.transaction;
+}
+function isAggregate(context) {
+    return typeof context?.getUncommittedEvents === 'function';
+}

package/dist/cqrs/workflow-events.explorer.d.ts

@@ -0,0 +1,27 @@
+import { type Type } from '@nestjs/common';
+import { DiscoveryService } from '@nestjs/core';
+import { WorkflowRegistry } from '../services/workflow-registry.service.js';
+import type { WorkflowSignalRoute, WorkflowStartRoute } from './interfaces/workflow-event-route.interface.js';
+/** What publishing one event class does. */
+export interface WorkflowEventTargets {
+    /** At most one per workflow name: the highest registered version's `@StartOn()`. */
+    starts: Array<{
+        workflow: Type<unknown>;
+        name: string;
+        route: WorkflowStartRoute;
+    }>;
+    /** From every registered version: an older version's instances still wait for their signals. */
+    signals: Array<{
+        workflow: Type<unknown>;
+        name: string;
+        route: WorkflowSignalRoute;
+    }>;
+}
+/** Reads `@StartOn()` and `@SignalOn()` from the registered workflows. */
+export declare class WorkflowEventsExplorer {
+    private readonly discovery;
+    private readonly registry;
+    constructor(discovery: DiscoveryService, registry: WorkflowRegistry);
+    explore(): Map<Function, WorkflowEventTargets>;
+    private rejectRoutesOutsideWorkflows;
+}

package/dist/cqrs/workflow-events.explorer.js

@@ -0,0 +1,92 @@
+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);
+};
+import { Injectable } from '@nestjs/common';
+import { DiscoveryService } from '@nestjs/core';
+import { WorkflowRegistry } from '../services/workflow-registry.service.js';
+import { WORKFLOW_METADATA } from '../workflows.constants.js';
+import { eventRoutesOf } from './utils/event-routes.util.js';
+/** Reads `@StartOn()` and `@SignalOn()` from the registered workflows. */
+let WorkflowEventsExplorer = class WorkflowEventsExplorer {
+    constructor(discovery, registry) {
+        this.discovery = discovery;
+        this.registry = registry;
+    }
+    explore() {
+        this.rejectRoutesOutsideWorkflows();
+        const table = new Map();
+        const targetsOf = (event) => {
+            let targets = table.get(event);
+            if (!targets) {
+                table.set(event, (targets = { starts: [], signals: [] }));
+            }
+            return targets;
+        };
+        for (const { name, version } of this.registry.versions()) {
+            const definition = this.registry.get(name, version);
+            const routes = eventRoutesOf(definition.type);
+            assertNoDuplicates(definition.type, routes);
+            // Like start(Class): an event starts the highest registered version, never an older one
+            // that is only kept registered to drain, and never twice.
+            const latest = this.registry.latest(name).version === version;
+            for (const route of routes) {
+                if (route.kind === 'signal') {
+                    targetsOf(route.event).signals.push({ workflow: definition.type, name, route });
+                }
+                else if (latest) {
+                    assertStartKeys(definition, route);
+                    targetsOf(route.event).starts.push({ workflow: definition.type, name, route });
+                }
+            }
+        }
+        return table;
+    }
+    rejectRoutesOutsideWorkflows() {
+        for (const wrapper of this.discovery.getProviders()) {
+            const type = (!wrapper.metatype || wrapper.inject ? wrapper.instance?.constructor : wrapper.metatype);
+            if (type && eventRoutesOf(type).length > 0 && !Reflect.getMetadata(WORKFLOW_METADATA, type)) {
+                throw new Error(`${type.name} has @StartOn() or @SignalOn() but no @Workflow(). Events start and signal workflows: ` +
+                    'put them on the @Workflow() class.');
+            }
+        }
+    }
+};
+WorkflowEventsExplorer = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [DiscoveryService,
+        WorkflowRegistry])
+], WorkflowEventsExplorer);
+export { WorkflowEventsExplorer };
+/** A key `@StartOn()` gives an instance would count for nothing, and fail every start, without a limit per key. */
+function assertStartKeys(definition, route) {
+    const limits = [
+        { option: 'concurrencyKey', perKey: definition.concurrency?.perKey, what: 'concurrency limit', declare: '{ concurrency: { limit, key } }' },
+        { option: 'rateLimitKey', perKey: definition.rateLimit?.perKey, what: 'rate limit', declare: '{ rateLimit: { max, duration, key } }' },
+    ];
+    for (const { option, perKey, what, declare } of limits) {
+        if (route[option] !== undefined && perKey == null) {
+            throw new Error(`${definition.type.name} has @StartOn(${route.event.name}) with a ${option}, but workflow "${definition.name}" has no ${what} per ` +
+                `key, so the key would count for nothing. Declare one with @Workflow(name, ${declare}).`);
+        }
+    }
+}
+function assertNoDuplicates(workflow, routes) {
+    // Per event class (not its name): two classes may share a name.
+    const seen = new Map();
+    for (const route of routes) {
+        const kinds = seen.get(route.event) ?? new Set();
+        const kind = route.kind === 'start' ? 'start' : `signal:${route.signal}`;
+        if (kinds.has(kind)) {
+            throw new Error(route.kind === 'start'
+                ? `${workflow.name} has @StartOn(${route.event.name}) twice. An event starts one instance of a workflow: keep one.`
+                : `${workflow.name} has @SignalOn(${route.event.name}) for the signal "${route.signal}" twice: keep one.`);
+        }
+        seen.set(route.event, kinds.add(kind));
+    }
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Makes CQRS events start and signal workflows. Import it next to `CqrsModule.forRoot()` and
+ * `WorkflowsModule.forRoot()` (both global): it wraps the `EventBus` publisher, so an event a
+ * workflow maps with `@StartOn()` or `@SignalOn()` starts or signals it before `publish()`
+ * resolves, in the transaction passed as the dispatcher context
+ * (`eventBus.publish(event, { transaction: tx })`), and then reaches the event handlers and
+ * sagas as before.
+ */
+export declare class WorkflowsCqrsModule {
+}

package/dist/cqrs/workflows-cqrs.module.js

@@ -0,0 +1,27 @@
+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;
+};
+import { Module } from '@nestjs/common';
+import { DiscoveryModule } from '@nestjs/core';
+import { WorkflowEventPublisher } from './workflow-event.publisher.js';
+import { WorkflowEventsExplorer } from './workflow-events.explorer.js';
+/**
+ * Makes CQRS events start and signal workflows. Import it next to `CqrsModule.forRoot()` and
+ * `WorkflowsModule.forRoot()` (both global): it wraps the `EventBus` publisher, so an event a
+ * workflow maps with `@StartOn()` or `@SignalOn()` starts or signals it before `publish()`
+ * resolves, in the transaction passed as the dispatcher context
+ * (`eventBus.publish(event, { transaction: tx })`), and then reaches the event handlers and
+ * sagas as before.
+ */
+let WorkflowsCqrsModule = class WorkflowsCqrsModule {
+};
+WorkflowsCqrsModule = __decorate([
+    Module({
+        imports: [DiscoveryModule],
+        providers: [WorkflowEventsExplorer, WorkflowEventPublisher],
+    })
+], WorkflowsCqrsModule);
+export { WorkflowsCqrsModule };

package/dist/decorators/index.d.ts

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

package/dist/decorators/index.js

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

package/dist/decorators/workflow.decorator.d.ts

@@ -0,0 +1,7 @@
+import type { WorkflowDecoratorOptions } from '../interfaces/workflow-decorator-options.interface.js';
+/**
+ * Marks an injectable class with a `run(ctx, input)` method as a durable
+ * workflow. Register it as a provider in any module; constructor injection
+ * works as usual. Workflows must be singletons (default scope).
+ */
+export declare function Workflow(name: string, options?: WorkflowDecoratorOptions): ClassDecorator;