@cqrs-ddd/cqrs 0.5.0

package/README.md

@@ -0,0 +1,39 @@
+# @cqrs-ddd/cqrs
+
+Command, query and event buses for TypeScript, with a pipeline of behaviors around each
+handler: `@CommandHandler`, `@QueryHandler` and `@EventsHandler` on handler classes,
+`@UsePipeline` and `@SkipPipeline` of `@cqrs-ddd/pipeline` for their behaviors, and
+`createCqrs()`, which builds the buses and registers handler instances. No framework and
+no container.
+
+**Documentation:** [guide](https://aristoteliss.github.io/ddd-cqrs/packages/cqrs/) · [API reference](https://aristoteliss.github.io/ddd-cqrs/api/cqrs-ddd/cqrs/) · [all packages](https://aristoteliss.github.io/ddd-cqrs/)
+
+## Installation
+
+```bash
+pnpm add @cqrs-ddd/cqrs @cqrs-ddd/pipeline
+```
+
+Requires Node.js 22.12 or later. The decorators work with TypeScript's standard decorators
+and with `experimentalDecorators`. Published as an ES module; a CommonJS application loads
+it with `require()`.
+
+## Example
+
+```ts
+@CommandHandler(CreateUserCommand)
+@UsePipeline(audit({ action: 'user.create' }))
+class CreateUserHandler implements ICommandHandler<CreateUserCommand> {
+  constructor(private readonly users: Users) {}
+  async execute(command: CreateUserCommand) {}
+}
+
+const cqrs = createCqrs({ behaviors: [new AuditBehavior(sink)] });
+cqrs.register(new CreateUserHandler(users));
+await cqrs.commandBus.execute(new CreateUserCommand('Ann'));
+```
+
+## License
+
+Dual-licensed under **AGPLv3** and a **Commercial License**. See `LICENSE` and
+`COMMERCIAL_LICENSE.txt`.

package/dist/command.bus.d.ts

@@ -0,0 +1,35 @@
+import type { RequestType } from './decorators.js';
+import { type Dispatch } from './dispatch.js';
+import type { ICommand } from './interfaces.js';
+/**
+ * Sends a command to its one handler, through the handler's pipeline. `createCqrs()`
+ * builds it.
+ *
+ * @example
+ * ```ts
+ * const { commandBus } = createCqrs();
+ * const id = await commandBus.execute<CreateUserCommand, string>(new CreateUserCommand('ann'));
+ * ```
+ */
+export declare class CommandBus<C extends ICommand = ICommand> {
+    private readonly handlers;
+    /**
+     * @param handlers - Maps each command class to the function that runs its handler. The
+     *   bus reads it at every call, so it can be filled after the bus is created, as
+     *   handlers that inject the bus require.
+     */
+    constructor(handlers: ReadonlyMap<RequestType, Dispatch>);
+    /**
+     * Runs the handler of the command's class, or of its nearest parent class that has
+     * one, and resolves with what the handler returns, typed as `R`.
+     *
+     * @throws CommandHandlerNotFoundException (as a rejection) when no class in the
+     *   command's chain has a handler.
+     * @example
+     * ```ts
+     * await commandBus.execute(new CreateUserCommand('ann'));
+     * ```
+     */
+    execute<T extends C, R = unknown>(command: T): Promise<R>;
+}
+//# sourceMappingURL=command.bus.d.ts.map

package/dist/command.bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.bus.d.ts","sourceRoot":"","sources":["../src/command.bus.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,KAAK,QAAQ,EAAW,MAAM,eAAe,CAAC;AAEvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;;;;;GASG;AACH,qBAAa,UAAU,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ;IAMvC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IALrC;;;;OAIG;IACH,YAA6B,QAAQ,EAAE,WAAW,CAAC,WAAW,EAAE,QAAQ,CAAC,EAAI;IAE7E;;;;;;;;;;OAUG;IACG,OAAO,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAK9D;CACF"}

package/dist/command.bus.js

@@ -0,0 +1,43 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { nearest } from './dispatch.js';
+import { CommandHandlerNotFoundException } from './errors.js';
+/**
+ * Sends a command to its one handler, through the handler's pipeline. `createCqrs()`
+ * builds it.
+ *
+ * @example
+ * ```ts
+ * const { commandBus } = createCqrs();
+ * const id = await commandBus.execute<CreateUserCommand, string>(new CreateUserCommand('ann'));
+ * ```
+ */
+export class CommandBus {
+    handlers;
+    /**
+     * @param handlers - Maps each command class to the function that runs its handler. The
+     *   bus reads it at every call, so it can be filled after the bus is created, as
+     *   handlers that inject the bus require.
+     */
+    constructor(handlers) {
+        this.handlers = handlers;
+    }
+    /**
+     * Runs the handler of the command's class, or of its nearest parent class that has
+     * one, and resolves with what the handler returns, typed as `R`.
+     *
+     * @throws CommandHandlerNotFoundException (as a rejection) when no class in the
+     *   command's chain has a handler.
+     * @example
+     * ```ts
+     * await commandBus.execute(new CreateUserCommand('ann'));
+     * ```
+     */
+    async execute(command) {
+        const type = command.constructor;
+        const run = nearest(this.handlers, type);
+        if (!run)
+            throw new CommandHandlerNotFoundException(type.name);
+        return (await run(command));
+    }
+}
+//# sourceMappingURL=command.bus.js.map

package/dist/command.bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.bus.js","sourceRoot":"","sources":["../src/command.bus.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAGtE,OAAO,EAAiB,OAAO,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,+BAA+B,EAAE,MAAM,aAAa,CAAC;AAG9D;;;;;;;;;GASG;AACH,MAAM,OAAO,UAAU;IAMQ,QAAQ;IALrC;;;;OAIG;IACH,YAA6B,QAA4C;wBAA5C,QAAQ;IAAuC,CAAC;IAE7E;;;;;;;;;;OAUG;IACH,KAAK,CAAC,OAAO,CAA2B,OAAU;QAChD,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC;QACjC,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,+BAA+B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/D,OAAO,CAAC,MAAM,GAAG,CAAC,OAAO,CAAC,CAAM,CAAC;IACnC,CAAC;CACF"}

package/dist/create-cqrs.d.ts

@@ -0,0 +1,62 @@
+import type { IPipelineBehavior, PipelineLogger } from '@cqrs-ddd/pipeline';
+import { CommandBus } from './command.bus.js';
+import { EventBus } from './event.bus.js';
+import { QueryBus } from './query.bus.js';
+import { type RegistrationOptions } from './registry.js';
+import { UnhandledExceptionBus } from './unhandled-exception.bus.js';
+/** Options of {@link createCqrs}. */
+export interface CqrsOptions extends RegistrationOptions {
+    /**
+     * Instances of the behaviors that need dependencies, one per behavior class. A placed
+     * behavior without an instance is built with no arguments, `LoggingBehavior` on
+     * `logger`.
+     */
+    readonly behaviors?: readonly IPipelineBehavior[];
+    /** The logger of `LoggingBehavior`, of failed event handlers and of the startup lines. */
+    readonly logger?: PipelineLogger;
+    /**
+     * Throw a failed event handler's error as an uncaught exception instead of publishing it
+     * on the `UnhandledExceptionBus` and logging it.
+     * @default false
+     */
+    readonly rethrowUnhandled?: boolean;
+}
+/** The buses of {@link createCqrs}, and the handlers registered with them. */
+export interface Cqrs {
+    readonly commandBus: CommandBus;
+    readonly queryBus: QueryBus;
+    readonly eventBus: EventBus;
+    readonly unhandledExceptionBus: UnhandledExceptionBus;
+    /**
+     * Registers handler instances: classes decorated with `@CommandHandler`,
+     * `@QueryHandler` or `@EventsHandler`. Each handler's pipeline is compiled here, once.
+     *
+     * @throws TypeError on an undecorated handler, or a second command or query handler.
+     * @throws PipelineConfigurationError on a behavior contract violation, in `'strict'`
+     *   mode.
+     */
+    register(...handlers: object[]): void;
+    /** Waits for the event handlers still running; call it before closing what they use. */
+    close(): Promise<void>;
+}
+/**
+ * Creates the command, query and event buses with no container: the application builds
+ * its handlers with `new` and registers them. Global behaviors are built here, so one
+ * whose required dependency is missing fails at once.
+ *
+ * @throws TypeError on two instances of one behavior class.
+ * @example
+ * ```ts
+ * const cqrs = createCqrs({
+ *   behaviors: [new AuditBehavior(sink)],
+ *   globalBehaviors: { before: [LoggingBehavior] },
+ *   sources: { tenantId: tenantSource, correlationId: correlationSource },
+ * });
+ * cqrs.register(new CreateUserHandler(users, cqrs.eventBus), new GetUserHandler(users));
+ *
+ * const id = await cqrs.commandBus.execute(new CreateUserCommand('Ann'));
+ * await cqrs.close();
+ * ```
+ */
+export declare function createCqrs(options?: CqrsOptions): Cqrs;
+//# sourceMappingURL=create-cqrs.d.ts.map

package/dist/create-cqrs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-cqrs.d.ts","sourceRoot":"","sources":["../src/create-cqrs.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,iBAAiB,EACjB,cAAc,EACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAGL,KAAK,mBAAmB,EAEzB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE,qCAAqC;AACrC,MAAM,WAAW,WAAY,SAAQ,mBAAmB;IACtD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAClD,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED,8EAA8E;AAC9E,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,qBAAqB,EAAE,qBAAqB,CAAC;IACtD;;;;;;;OAOG;IACH,QAAQ,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACtC,wFAAwF;IACxF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,WAAgB,GAAG,IAAI,CAgC1D"}

package/dist/create-cqrs.js

@@ -0,0 +1,54 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { CommandBus } from './command.bus.js';
+import { commandOf, eventsOf, queryOf } from './decorators.js';
+import { EventBus } from './event.bus.js';
+import { QueryBus } from './query.bus.js';
+import { behaviorResolver, Handlers, registerHandlers, } from './registry.js';
+import { UnhandledExceptionBus } from './unhandled-exception.bus.js';
+/**
+ * Creates the command, query and event buses with no container: the application builds
+ * its handlers with `new` and registers them. Global behaviors are built here, so one
+ * whose required dependency is missing fails at once.
+ *
+ * @throws TypeError on two instances of one behavior class.
+ * @example
+ * ```ts
+ * const cqrs = createCqrs({
+ *   behaviors: [new AuditBehavior(sink)],
+ *   globalBehaviors: { before: [LoggingBehavior] },
+ *   sources: { tenantId: tenantSource, correlationId: correlationSource },
+ * });
+ * cqrs.register(new CreateUserHandler(users, cqrs.eventBus), new GetUserHandler(users));
+ *
+ * const id = await cqrs.commandBus.execute(new CreateUserCommand('Ann'));
+ * await cqrs.close();
+ * ```
+ */
+export function createCqrs(options = {}) {
+    const logger = options.logger ?? console;
+    const behavior = behaviorResolver(options.behaviors ?? [], options.globalBehaviors, logger);
+    const handlers = new Handlers();
+    const unhandledExceptionBus = new UnhandledExceptionBus();
+    const eventBus = new EventBus(handlers.events, unhandledExceptionBus, {
+        rethrowUnhandled: options.rethrowUnhandled,
+        logger,
+    });
+    return {
+        commandBus: new CommandBus(handlers.commands),
+        queryBus: new QueryBus(handlers.queries),
+        eventBus,
+        unhandledExceptionBus,
+        register(...instances) {
+            const entries = instances.map((instance) => {
+                const type = instance.constructor;
+                if (!commandOf(type) && !queryOf(type) && !eventsOf(type)) {
+                    throw new TypeError(`${type.name} has no @CommandHandler, @QueryHandler or @EventsHandler decorator.`);
+                }
+                return { type, resolve: () => instance };
+            });
+            registerHandlers(handlers, entries, behavior, options, logger);
+        },
+        close: () => eventBus.drain(),
+    };
+}
+//# sourceMappingURL=create-cqrs.js.map

package/dist/create-cqrs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-cqrs.js","sourceRoot":"","sources":["../src/create-cqrs.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAOtE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EACL,gBAAgB,EAChB,QAAQ,EAER,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAuCrE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,UAAU,CAAC,OAAO,GAAgB,EAAE;IAClD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC;IACzC,MAAM,QAAQ,GAAG,gBAAgB,CAC/B,OAAO,CAAC,SAAS,IAAI,EAAE,EACvB,OAAO,CAAC,eAAe,EACvB,MAAM,CACP,CAAC;IACF,MAAM,QAAQ,GAAG,IAAI,QAAQ,EAAE,CAAC;IAChC,MAAM,qBAAqB,GAAG,IAAI,qBAAqB,EAAE,CAAC;IAC1D,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,EAAE;QACpE,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;QAC1C,MAAM;KACP,CAAC,CAAC;IACH,OAAO;QACL,UAAU,EAAE,IAAI,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAC7C,QAAQ,EAAE,IAAI,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC;QACxC,QAAQ;QACR,qBAAqB;QACrB,QAAQ,CAAC,GAAG,SAAS;YACnB,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE;gBACzC,MAAM,IAAI,GAAG,QAAQ,CAAC,WAA0B,CAAC;gBACjD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC1D,MAAM,IAAI,SAAS,CACjB,GAAG,IAAI,CAAC,IAAI,qEAAqE,CAClF,CAAC;gBACJ,CAAC;gBACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC;YAC3C,CAAC,CAAC,CAAC;YACH,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QACjE,CAAC;QACD,KAAK,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE;KAC9B,CAAC;AACJ,CAAC"}

package/dist/decorators.d.ts

@@ -0,0 +1,73 @@
+import type { AnyClass, DualClassDecorator } from '@cqrs-ddd/pipeline';
+/** A request class: a command, a query or an event. */
+export type RequestType = AnyClass;
+/**
+ * Registers a class as the handler of one command class; the class implements
+ * `ICommandHandler`.
+ *
+ * @throws TypeError when `command` is not a class.
+ * @example
+ * ```ts
+ * @CommandHandler(CreateUserCommand)
+ * class CreateUserHandler implements ICommandHandler<CreateUserCommand> {
+ *   async execute(command: CreateUserCommand) {}
+ * }
+ * ```
+ */
+export declare function CommandHandler(command: RequestType): DualClassDecorator;
+/**
+ * Registers a class as the handler of one query class; the class implements
+ * `IQueryHandler`.
+ *
+ * @throws TypeError when `query` is not a class.
+ * @example
+ * ```ts
+ * @QueryHandler(GetUserQuery)
+ * class GetUserHandler implements IQueryHandler<GetUserQuery> {
+ *   async execute(query: GetUserQuery) {}
+ * }
+ * ```
+ */
+export declare function QueryHandler(query: RequestType): DualClassDecorator;
+/**
+ * Registers a class as a handler of one or more event classes; the class implements
+ * `IEventHandler`.
+ *
+ * @throws TypeError when no event class is given, or one is not a class.
+ * @example
+ * ```ts
+ * @EventsHandler(UserCreatedEvent, UserInvitedEvent)
+ * class SendWelcomeEmail implements IEventHandler<UserCreatedEvent | UserInvitedEvent> {
+ *   async handle(event: UserCreatedEvent | UserInvitedEvent) {}
+ * }
+ * ```
+ */
+export declare function EventsHandler(...events: RequestType[]): DualClassDecorator;
+/**
+ * The command class a handler class handles, if it is a command handler.
+ *
+ * @example
+ * ```ts
+ * commandOf(CreateUserHandler); // CreateUserCommand
+ * ```
+ */
+export declare function commandOf(handler: AnyClass): RequestType | undefined;
+/**
+ * The query class a handler class handles, if it is a query handler.
+ *
+ * @example
+ * ```ts
+ * queryOf(GetUserHandler); // GetUserQuery
+ * ```
+ */
+export declare function queryOf(handler: AnyClass): RequestType | undefined;
+/**
+ * The event classes a handler class handles, if it is an events handler.
+ *
+ * @example
+ * ```ts
+ * eventsOf(SendWelcomeEmail); // [UserCreatedEvent]
+ * ```
+ */
+export declare function eventsOf(handler: AnyClass): readonly RequestType[] | undefined;
+//# sourceMappingURL=decorators.d.ts.map

package/dist/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAMvE,uDAAuD;AACvD,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;AAkBnC;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,kBAAkB,CAGvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,kBAAkB,CAGnE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,GAAG,MAAM,EAAE,WAAW,EAAE,GAAG,kBAAkB,CAM1E;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAEpE;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAElE;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,QAAQ,GAChB,SAAS,WAAW,EAAE,GAAG,SAAS,CAEpC"}

package/dist/decorators.js

@@ -0,0 +1,104 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+const COMMAND_HANDLER = Symbol.for('@cqrs-ddd/cqrs:command-handler');
+const QUERY_HANDLER = Symbol.for('@cqrs-ddd/cqrs:query-handler');
+const EVENTS_HANDLER = Symbol.for('@cqrs-ddd/cqrs:events-handler');
+function define(target, key, value) {
+    Object.defineProperty(target, key, { value, configurable: true });
+}
+function read(target, key) {
+    return target[key];
+}
+function requireRequestType(value, decorator) {
+    if (typeof value !== 'function') {
+        throw new TypeError(`${decorator} takes a request class, received ${value === null ? 'null' : typeof value}.`);
+    }
+}
+/**
+ * Registers a class as the handler of one command class; the class implements
+ * `ICommandHandler`.
+ *
+ * @throws TypeError when `command` is not a class.
+ * @example
+ * ```ts
+ * @CommandHandler(CreateUserCommand)
+ * class CreateUserHandler implements ICommandHandler<CreateUserCommand> {
+ *   async execute(command: CreateUserCommand) {}
+ * }
+ * ```
+ */
+export function CommandHandler(command) {
+    requireRequestType(command, '@CommandHandler');
+    return (target) => define(target, COMMAND_HANDLER, command);
+}
+/**
+ * Registers a class as the handler of one query class; the class implements
+ * `IQueryHandler`.
+ *
+ * @throws TypeError when `query` is not a class.
+ * @example
+ * ```ts
+ * @QueryHandler(GetUserQuery)
+ * class GetUserHandler implements IQueryHandler<GetUserQuery> {
+ *   async execute(query: GetUserQuery) {}
+ * }
+ * ```
+ */
+export function QueryHandler(query) {
+    requireRequestType(query, '@QueryHandler');
+    return (target) => define(target, QUERY_HANDLER, query);
+}
+/**
+ * Registers a class as a handler of one or more event classes; the class implements
+ * `IEventHandler`.
+ *
+ * @throws TypeError when no event class is given, or one is not a class.
+ * @example
+ * ```ts
+ * @EventsHandler(UserCreatedEvent, UserInvitedEvent)
+ * class SendWelcomeEmail implements IEventHandler<UserCreatedEvent | UserInvitedEvent> {
+ *   async handle(event: UserCreatedEvent | UserInvitedEvent) {}
+ * }
+ * ```
+ */
+export function EventsHandler(...events) {
+    if (events.length === 0) {
+        throw new TypeError('@EventsHandler takes at least one event class.');
+    }
+    for (const event of events)
+        requireRequestType(event, '@EventsHandler');
+    return (target) => define(target, EVENTS_HANDLER, events);
+}
+/**
+ * The command class a handler class handles, if it is a command handler.
+ *
+ * @example
+ * ```ts
+ * commandOf(CreateUserHandler); // CreateUserCommand
+ * ```
+ */
+export function commandOf(handler) {
+    return read(handler, COMMAND_HANDLER);
+}
+/**
+ * The query class a handler class handles, if it is a query handler.
+ *
+ * @example
+ * ```ts
+ * queryOf(GetUserHandler); // GetUserQuery
+ * ```
+ */
+export function queryOf(handler) {
+    return read(handler, QUERY_HANDLER);
+}
+/**
+ * The event classes a handler class handles, if it is an events handler.
+ *
+ * @example
+ * ```ts
+ * eventsOf(SendWelcomeEmail); // [UserCreatedEvent]
+ * ```
+ */
+export function eventsOf(handler) {
+    return read(handler, EVENTS_HANDLER);
+}
+//# sourceMappingURL=decorators.js.map

package/dist/decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAItE,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC;AACrE,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;AACjE,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;AAKnE,SAAS,MAAM,CAAC,MAAgB,EAAE,GAAW,EAAE,KAAc;IAC3D,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;AACpE,CAAC;AAED,SAAS,IAAI,CAAI,MAAgB,EAAE,GAAW;IAC5C,OAAQ,MAAmD,CAAC,GAAG,CAAC,CAAC;AACnE,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc,EAAE,SAAiB;IAC3D,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CACjB,GAAG,SAAS,oCAAoC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,KAAK,GAAG,CAC1F,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAC,OAAoB;IACjD,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAC/C,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,KAAkB;IAC7C,kBAAkB,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;IAC3C,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,GAAG,MAAqB;IACpD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,SAAS,CAAC,gDAAgD,CAAC,CAAC;IACxE,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,MAAM;QAAE,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC;IACxE,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,OAAiB;IACzC,OAAO,IAAI,CAAc,OAAO,EAAE,eAAe,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CAAC,OAAiB;IACvC,OAAO,IAAI,CAAc,OAAO,EAAE,aAAa,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CACtB,OAAiB;IAEjB,OAAO,IAAI,CAAgB,OAAO,EAAE,cAAc,CAAC,CAAC;AACtD,CAAC"}

package/dist/dispatch.d.ts

@@ -0,0 +1,31 @@
+import { type Constructor, type ContextSources, type DeclaredKind, type GlobalBehaviorsOptions, type IPipelineBehavior, type PipelineBehaviorDiagnostic } from '@cqrs-ddd/pipeline';
+import type { RequestType } from './decorators.js';
+/** Runs one request through its handler and the handler's pipeline. */
+export type Dispatch = (request: unknown) => Promise<unknown>;
+/** What every handler's pipeline shares. */
+export interface PipelineSettings {
+    readonly globalBehaviors?: GlobalBehaviorsOptions | GlobalBehaviorsOptions[];
+    readonly sources?: ContextSources;
+    /** Returns the one instance of a behavior class. */
+    readonly behavior: (type: Constructor<IPipelineBehavior>) => IPipelineBehavior;
+    /** Receives contract violations; absent, contracts are not validated. */
+    readonly diagnostics?: PipelineBehaviorDiagnostic[];
+    /** Receives a line per handler that runs behaviors, naming them in order. */
+    readonly log?: (message: string) => void;
+}
+/**
+ * Compiles a handler class's pipeline once, from its decorators and the global behaviors,
+ * and returns the function the bus calls per request; `resolve` gives the instance that
+ * handles each request. The handler is named by its class.
+ *
+ * @throws InvalidCommandHandlerException, InvalidQueryHandlerException or
+ *   InvalidEventsHandlerException when the handler lacks `execute`, or `handle` for an
+ *   event.
+ * @throws Error when the handler both declares and skips one behavior.
+ */
+export declare function toDispatch(handlerType: Constructor, resolve: () => object, kind: DeclaredKind, settings: PipelineSettings): Dispatch;
+/**
+ * The entry of a request class or, failing that, of its nearest parent class.
+ */
+export declare function nearest<T>(entries: ReadonlyMap<RequestType, T>, type: object): T | undefined;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,cAAc,EAGnB,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,0BAA0B,EAGhC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAOnD,uEAAuE;AACvE,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE9D,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,eAAe,CAAC,EAAE,sBAAsB,GAAG,sBAAsB,EAAE,CAAC;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,CACjB,IAAI,EAAE,WAAW,CAAC,iBAAiB,CAAC,KACjC,iBAAiB,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,0BAA0B,EAAE,CAAC;IACpD,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C;AAQD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,MAAM,MAAM,EACrB,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,gBAAgB,GACzB,QAAQ,CA4CV;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,OAAO,EAAE,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC,EACpC,IAAI,EAAE,MAAM,GACX,CAAC,GAAG,SAAS,CAUf"}

package/dist/dispatch.js

@@ -0,0 +1,67 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { compilePipelinePlan, createPipelineRunner, pipelineOf, validateBehaviorContracts, } from '@cqrs-ddd/pipeline';
+import { InvalidCommandHandlerException, InvalidEventsHandlerException, InvalidQueryHandlerException, } from './errors.js';
+const INVALID = {
+    command: InvalidCommandHandlerException,
+    query: InvalidQueryHandlerException,
+    event: InvalidEventsHandlerException,
+};
+/**
+ * Compiles a handler class's pipeline once, from its decorators and the global behaviors,
+ * and returns the function the bus calls per request; `resolve` gives the instance that
+ * handles each request. The handler is named by its class.
+ *
+ * @throws InvalidCommandHandlerException, InvalidQueryHandlerException or
+ *   InvalidEventsHandlerException when the handler lacks `execute`, or `handle` for an
+ *   event.
+ * @throws Error when the handler both declares and skips one behavior.
+ */
+export function toDispatch(handlerType, resolve, kind, settings) {
+    const name = kind === 'event' ? 'handle' : 'execute';
+    const method = Reflect.get(handlerType.prototype, name);
+    if (typeof method !== 'function')
+        throw new INVALID[kind]();
+    const handlerName = handlerType.name;
+    const declared = pipelineOf(handlerType);
+    const plan = compilePipelinePlan({
+        handlerName,
+        requestKind: kind,
+        handlerBehaviorTypes: declared.types,
+        handlerOptions: declared.options,
+        skippedBehaviorTypes: declared.skipped,
+        globalBehaviors: settings.globalBehaviors,
+    });
+    const behaviors = plan.behaviorTypes.map(settings.behavior);
+    if (plan.hasPipeline) {
+        settings.log?.(`Wrapping ${handlerName}.${name}() [${kind}] with pipeline: [${plan.behaviorTypes.map((type) => type.name).join(' → ')}]`);
+    }
+    if (settings.diagnostics) {
+        validateBehaviorContracts({
+            ...plan,
+            handlerType,
+            handlerName,
+            requestKind: kind,
+            resolvedBehaviors: new Map(behaviors.map((b, i) => [i, b])),
+            diagnostics: settings.diagnostics,
+        });
+    }
+    const run = createPipelineRunner(method, {
+        handlerType,
+        handlerName,
+        requestKind: kind,
+        behaviorOptions: plan.mergedOptions.size > 0 ? plan.mergedOptions : undefined,
+    }, behaviors, plan.hasPipeline, settings.sources);
+    return (request) => run(resolve(), request);
+}
+/**
+ * The entry of a request class or, failing that, of its nearest parent class.
+ */
+export function nearest(entries, type) {
+    for (let current = type; current !== Function.prototype; current = Object.getPrototypeOf(current)) {
+        const entry = entries.get(current);
+        if (entry)
+            return entry;
+    }
+    return undefined;
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,26 @@
+/** Thrown by `CommandBus.execute()` when no handler is registered for the command's class. */
+export declare class CommandHandlerNotFoundException extends Error {
+    readonly name = "CommandHandlerNotFoundException";
+    constructor(commandName: string);
+}
+/** Thrown by `QueryBus.execute()` when no handler is registered for the query's class. */
+export declare class QueryHandlerNotFoundException extends Error {
+    readonly name = "QueryHandlerNotFoundException";
+    constructor(queryName: string);
+}
+/** Thrown at startup by a command handler without an `execute` method. */
+export declare class InvalidCommandHandlerException extends Error {
+    readonly name = "InvalidCommandHandlerException";
+    constructor();
+}
+/** Thrown at startup by a query handler without an `execute` method. */
+export declare class InvalidQueryHandlerException extends Error {
+    readonly name = "InvalidQueryHandlerException";
+    constructor();
+}
+/** Thrown at startup by an events handler without a `handle` method. */
+export declare class InvalidEventsHandlerException extends Error {
+    readonly name = "InvalidEventsHandlerException";
+    constructor();
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,8FAA8F;AAC9F,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,SAAkB,IAAI,qCAAqC;IAE3D,YAAY,WAAW,EAAE,MAAM,EAE9B;CACF;AAED,0FAA0F;AAC1F,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,SAAkB,IAAI,mCAAmC;IAEzD,YAAY,SAAS,EAAE,MAAM,EAE5B;CACF;AAED,0EAA0E;AAC1E,qBAAa,8BAA+B,SAAQ,KAAK;IACvD,SAAkB,IAAI,oCAAoC;IAE1D,cAIC;CACF;AAED,wEAAwE;AACxE,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,SAAkB,IAAI,kCAAkC;IAExD,cAIC;CACF;AAED,wEAAwE;AACxE,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,SAAkB,IAAI,mCAAmC;IAEzD,cAIC;CACF"}

package/dist/errors.js

@@ -0,0 +1,37 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/** Thrown by `CommandBus.execute()` when no handler is registered for the command's class. */
+export class CommandHandlerNotFoundException extends Error {
+    name = 'CommandHandlerNotFoundException';
+    constructor(commandName) {
+        super(`No handler found for the command: "${commandName}".`);
+    }
+}
+/** Thrown by `QueryBus.execute()` when no handler is registered for the query's class. */
+export class QueryHandlerNotFoundException extends Error {
+    name = 'QueryHandlerNotFoundException';
+    constructor(queryName) {
+        super(`No handler found for the query: "${queryName}"`);
+    }
+}
+/** Thrown at startup by a command handler without an `execute` method. */
+export class InvalidCommandHandlerException extends Error {
+    name = 'InvalidCommandHandlerException';
+    constructor() {
+        super(`An invalid command handler has been provided. Please ensure that the provided handler is a class annotated with @CommandHandler and contains an 'execute' method.`);
+    }
+}
+/** Thrown at startup by a query handler without an `execute` method. */
+export class InvalidQueryHandlerException extends Error {
+    name = 'InvalidQueryHandlerException';
+    constructor() {
+        super(`An invalid query handler has been provided. Please ensure that the provided handler is a class annotated with @QueryHandler and contains an 'execute' method.`);
+    }
+}
+/** Thrown at startup by an events handler without a `handle` method. */
+export class InvalidEventsHandlerException extends Error {
+    name = 'InvalidEventsHandlerException';
+    constructor() {
+        super(`An invalid events handler has been provided. Please ensure that the provided handler is a class annotated with @EventsHandler and contains a 'handle' method.`);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,8FAA8F;AAC9F,MAAM,OAAO,+BAAgC,SAAQ,KAAK;IACtC,IAAI,GAAG,iCAAiC,CAAC;IAE3D,YAAY,WAAmB;QAC7B,KAAK,CAAC,sCAAsC,WAAW,IAAI,CAAC,CAAC;IAC/D,CAAC;CACF;AAED,0FAA0F;AAC1F,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IACpC,IAAI,GAAG,+BAA+B,CAAC;IAEzD,YAAY,SAAiB;QAC3B,KAAK,CAAC,oCAAoC,SAAS,GAAG,CAAC,CAAC;IAC1D,CAAC;CACF;AAED,0EAA0E;AAC1E,MAAM,OAAO,8BAA+B,SAAQ,KAAK;IACrC,IAAI,GAAG,gCAAgC,CAAC;IAE1D;QACE,KAAK,CACH,mKAAmK,CACpK,CAAC;IACJ,CAAC;CACF;AAED,wEAAwE;AACxE,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IACnC,IAAI,GAAG,8BAA8B,CAAC;IAExD;QACE,KAAK,CACH,+JAA+J,CAChK,CAAC;IACJ,CAAC;CACF;AAED,wEAAwE;AACxE,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IACpC,IAAI,GAAG,+BAA+B,CAAC;IAEzD;QACE,KAAK,CACH,+JAA+J,CAChK,CAAC;IACJ,CAAC;CACF"}