@cqrs-ddd/pipeline 0.5.0

package/dist/create-pipeline.js

@@ -0,0 +1,193 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { LoggingBehavior } from './behaviors/logging.behavior.js';
+import { behaviorEntryType, normalizeBehaviorEntries, } from './helpers/behavior-entries.js';
+import { getBehaviorId } from './helpers/behavior-id.js';
+import { PipelineConfigurationError, } from './interfaces/pipeline-behavior-contract.interface.js';
+import { validateBehaviorContracts } from './services/pipeline-contracts.js';
+import { compilePipelinePlan, toGlobalConfigs, } from './services/pipeline-plan.js';
+import { createPipelineRunner, } from './services/pipeline-runner.js';
+const KINDS = ['command', 'query', 'event'];
+/**
+ * Brand by which a request tells a pipeline its kind, so a wrapped method needs no
+ * `kind` option; the request's class name then names the operation. `@cqrs-ddd/core`
+ * puts it on `BaseCommand`, `BaseQuery` and `DomainEvent`; any class can declare it.
+ *
+ * @example
+ * ```ts
+ * class GetPriceQuery {
+ *   get [REQUEST_KIND]() {
+ *     return 'query' as const;
+ *   }
+ *   constructor(readonly sku: string) {}
+ * }
+ * ```
+ */
+export const REQUEST_KIND = Symbol.for('@cqrs-ddd/request-kind');
+/**
+ * Creates a pipeline: behaviors that wrap plain functions and class methods with
+ * cross-cutting concerns, with no framework and no dependency-injection container.
+ *
+ * Global behaviors are constructed when the pipeline is created, so a behavior whose
+ * required dependency is missing fails here rather than at its first call.
+ *
+ * @throws TypeError on a malformed global entry or two instances of one behavior class.
+ * @example
+ * ```ts
+ * const pipeline = createPipeline({
+ *   behaviors: [new CacheBehavior(buildCache({}))],
+ *   globalBehaviors: { before: [logging({ requestResponseLogLevel: 'log' })] },
+ * });
+ *
+ * export const getPrice = pipeline.wrap(
+ *   { name: 'getPrice', kind: 'query' },
+ *   cache({ key }),
+ * )(async (sku: string) => prices.find(sku));
+ *
+ * class Prices {
+ *   @pipeline.wrap({ kind: 'query' }, cache({ key }))
+ *   async find(sku: string) {}
+ * }
+ * ```
+ */
+export function createPipeline(options = {}) {
+    const { globalBehaviors, sources = {}, diagnostics = 'strict', logger = console, } = options;
+    const instances = new Map();
+    for (const behavior of options.behaviors ?? []) {
+        const type = behavior.constructor;
+        const id = getBehaviorId(type);
+        if (instances.has(id)) {
+            throw new TypeError(`createPipeline: two instances of ${type.name}; pass one per behavior class.`);
+        }
+        instances.set(id, behavior);
+    }
+    const instanceOf = (type) => {
+        const id = getBehaviorId(type);
+        let instance = instances.get(id);
+        if (!instance) {
+            instance = id === LOGGING_ID ? new LoggingBehavior(logger) : new type();
+            instances.set(id, instance);
+        }
+        return instance;
+    };
+    for (const config of toGlobalConfigs(globalBehaviors)) {
+        for (const entry of [...(config.before ?? []), ...(config.after ?? [])]) {
+            instanceOf(behaviorEntryType(entry, 'createPipeline globalBehaviors'));
+        }
+    }
+    function compile(handlerName, requestKind, declared, skip) {
+        const plan = compilePipelinePlan({
+            handlerName,
+            requestKind,
+            handlerBehaviorTypes: declared.types,
+            handlerOptions: declared.options,
+            skippedBehaviorTypes: skip
+                ? normalizeBehaviorEntries(skip, 'pipeline.wrap skip', false).types
+                : undefined,
+            globalBehaviors,
+        });
+        const behaviors = plan.behaviorTypes.map(instanceOf);
+        if (diagnostics !== 'off') {
+            const found = [];
+            validateBehaviorContracts({
+                ...plan,
+                handlerType: Object,
+                handlerName,
+                requestKind,
+                resolvedBehaviors: new Map(behaviors.map((b, i) => [i, b])),
+                diagnostics: found,
+            });
+            if (found.length > 0 && diagnostics === 'strict') {
+                throw new PipelineConfigurationError(found);
+            }
+            for (const d of found) {
+                logger.warn(`[Pipeline Diagnostic] '${d.handlerName}' with behavior '${d.behaviorName}': ${d.message}. Fix: ${d.fix}`);
+            }
+        }
+        return { plan, behaviors };
+    }
+    function wrap(...input) {
+        const [first] = input;
+        const hasOptions = typeof first === 'object' && first !== null && !Array.isArray(first);
+        const wrapOptions = (hasOptions ? first : {});
+        const entries = (hasOptions ? input.slice(1) : input);
+        if (wrapOptions.kind !== undefined && !KINDS.includes(wrapOptions.kind)) {
+            throw new TypeError(`pipeline.wrap: kind must be 'command', 'query' or 'event', received ${String(wrapOptions.kind)}.`);
+        }
+        const declared = normalizeBehaviorEntries(entries, 'pipeline.wrap');
+        function bind(fn, methodKey) {
+            const label = wrapOptions.name ?? methodKey;
+            if (label === undefined) {
+                throw new TypeError('pipeline.wrap: a plain function needs a `name`, which keys and logs use to tell operations apart.');
+            }
+            const handlerType = { [label]: class {
+                } }[label];
+            const runners = new Map();
+            const runnerFor = (kind) => {
+                let runner = runners.get(kind);
+                if (!runner) {
+                    const { plan, behaviors } = compile(label, kind, declared, wrapOptions.skip);
+                    const behaviorOptions = plan.mergedOptions.size > 0 ? plan.mergedOptions : undefined;
+                    runner = createPipelineRunner(fn, (request, self) => {
+                        const handlerName = wrapOptions.name ?? `${ownerName(self)}.${label}`;
+                        return {
+                            handlerType,
+                            handlerName,
+                            requestKind: kind,
+                            behaviorOptions,
+                            requestName: wrapOptions.name ??
+                                (brandOf(request) ? undefined : handlerName),
+                        };
+                    }, behaviors, plan.hasPipeline, sources);
+                    runners.set(kind, runner);
+                }
+                return runner;
+            };
+            if (wrapOptions.kind)
+                runnerFor(wrapOptions.kind);
+            return async function (...args) {
+                const request = args.length === 1 ? args[0] : args;
+                const kind = wrapOptions.kind ?? brandOf(request);
+                if (!kind) {
+                    throw new TypeError(`${label}: declare its kind with pipeline.wrap({ kind }), or pass a request that carries REQUEST_KIND.`);
+                }
+                return runnerFor(kind)(this, request, args);
+            };
+        }
+        return function apply(target, key, descriptor) {
+            if (key === undefined && typeof target === 'function') {
+                return bind(target);
+            }
+            if (isDecoratorContext(key)) {
+                if (key.kind !== 'method') {
+                    throw new TypeError(`pipeline.wrap decorates methods, not a ${key.kind}.`);
+                }
+                return bind(target, String(key.name));
+            }
+            const property = descriptor;
+            if (typeof property?.value === 'function') {
+                property.value = bind(property.value, String(key));
+                return property;
+            }
+            throw new TypeError('pipeline.wrap(...) applies to a function or a method.');
+        };
+    }
+    return { wrap };
+}
+const LOGGING_ID = getBehaviorId(LoggingBehavior);
+function brandOf(request) {
+    if (typeof request !== 'object' || request === null)
+        return undefined;
+    const kind = request[REQUEST_KIND];
+    return KINDS.includes(kind)
+        ? kind
+        : undefined;
+}
+function ownerName(self) {
+    if (typeof self === 'function')
+        return self.name;
+    return self?.constructor?.name ?? 'anonymous';
+}
+function isDecoratorContext(value) {
+    return typeof value === 'object' && value !== null && 'kind' in value;
+}
+//# sourceMappingURL=create-pipeline.js.map

package/dist/create-pipeline.js.map

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

package/dist/entries.d.ts

@@ -0,0 +1,13 @@
+import type { IPipelineBehavior } from './interfaces/pipeline.behavior.interface.js';
+import type { Constructor } from './types.js';
+/**
+ * A tuple of a pipeline behavior class and its options.
+ */
+export type PipelineBehaviorTuple<TBehavior extends IPipelineBehavior = IPipelineBehavior, TOptions extends object = object> = [Constructor<TBehavior>, TOptions];
+/**
+ * A pipeline behavior entry can be either:
+ * - A behavior class: `LoggingBehavior`
+ * - A tuple of behavior class and options: `[AuditBehavior, { action: 'user.create', severity: 'high' }]`
+ */
+export type PipelineBehaviorEntry<TBehavior extends IPipelineBehavior = IPipelineBehavior, TOptions extends object = object> = Constructor<TBehavior> | PipelineBehaviorTuple<TBehavior, TOptions>;
+//# sourceMappingURL=entries.d.ts.map

package/dist/entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../src/entries.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;GAEG;AACH,MAAM,MAAM,qBAAqB,CAC/B,SAAS,SAAS,iBAAiB,GAAG,iBAAiB,EACvD,QAAQ,SAAS,MAAM,GAAG,MAAM,IAC9B,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,CAAC;AAEvC;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,CAC/B,SAAS,SAAS,iBAAiB,GAAG,iBAAiB,EACvD,QAAQ,SAAS,MAAM,GAAG,MAAM,IAC9B,WAAW,CAAC,SAAS,CAAC,GAAG,qBAAqB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC"}

package/dist/entries.js

@@ -0,0 +1,3 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+export {};
+//# sourceMappingURL=entries.js.map

package/dist/entries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entries.js","sourceRoot":"","sources":["../src/entries.ts"],"names":[],"mappings":"AAAA,sEAAsE"}

package/dist/errors/missing-partition.error.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Raised when a partitioned key (cache, idempotency, rate limit) needs a
+ * dimension, such as the tenant or the principal, that could not be resolved.
+ * Omitting it instead would merge isolation domains: callers whose identity
+ * is unknown would share one key.
+ *
+ * Each package subclasses it with its own name and dimensions, such as
+ * `MissingCachePartitionError`.
+ *
+ * @example
+ * ```ts
+ * export class MissingCachePartitionError extends MissingPartitionError<'tenant' | 'principal'> {
+ *   override readonly name = 'MissingCachePartitionError';
+ *
+ *   constructor(requestName: string, dimension: 'tenant' | 'principal', remedy: string) {
+ *     super('Cache', requestName, dimension, remedy);
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class MissingPartitionError<TDimension extends string = string> extends Error {
+    readonly requestName: string;
+    readonly dimension: TDimension;
+    readonly remedy: string;
+    protected constructor(keyKind: string, requestName: string, dimension: TDimension, remedy: string);
+}
+//# sourceMappingURL=missing-partition.error.d.ts.map

package/dist/errors/missing-partition.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-partition.error.d.ts","sourceRoot":"","sources":["../../src/errors/missing-partition.error.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,8BAAsB,qBAAqB,CACzC,UAAU,SAAS,MAAM,GAAG,MAAM,CAClC,SAAQ,KAAK;aAGK,WAAW,EAAE,MAAM;aACnB,SAAS,EAAE,UAAU;aACrB,MAAM,EAAE,MAAM;IAJhC,SAAS,aACP,OAAO,EAAE,MAAM,EACC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,UAAU,EACrB,MAAM,EAAE,MAAM,EAK/B;CACF"}

package/dist/errors/missing-partition.error.js

@@ -0,0 +1,33 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * Raised when a partitioned key (cache, idempotency, rate limit) needs a
+ * dimension, such as the tenant or the principal, that could not be resolved.
+ * Omitting it instead would merge isolation domains: callers whose identity
+ * is unknown would share one key.
+ *
+ * Each package subclasses it with its own name and dimensions, such as
+ * `MissingCachePartitionError`.
+ *
+ * @example
+ * ```ts
+ * export class MissingCachePartitionError extends MissingPartitionError<'tenant' | 'principal'> {
+ *   override readonly name = 'MissingCachePartitionError';
+ *
+ *   constructor(requestName: string, dimension: 'tenant' | 'principal', remedy: string) {
+ *     super('Cache', requestName, dimension, remedy);
+ *   }
+ * }
+ * ```
+ */
+export class MissingPartitionError extends Error {
+    requestName;
+    dimension;
+    remedy;
+    constructor(keyKind, requestName, dimension, remedy) {
+        super(`${keyKind} key for ${requestName} requires a ${dimension} partition, which could not be resolved. ${remedy}`);
+        this.requestName = requestName;
+        this.dimension = dimension;
+        this.remedy = remedy;
+    }
+}
+//# sourceMappingURL=missing-partition.error.js.map

package/dist/errors/missing-partition.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-partition.error.js","sourceRoot":"","sources":["../../src/errors/missing-partition.error.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAgB,qBAEpB,SAAQ,KAAK;IAGK,WAAW;IACX,SAAS;IACT,MAAM;IAJxB,YACE,OAAe,EACC,WAAmB,EACnB,SAAqB,EACrB,MAAc;QAE9B,KAAK,CACH,GAAG,OAAO,YAAY,WAAW,eAAe,SAAS,4CAA4C,MAAM,EAAE,CAC9G,CAAC;2BANc,WAAW;yBACX,SAAS;sBACT,MAAM;IAKxB,CAAC;CACF"}

package/dist/errors/missing-pipeline-item.error.d.ts

@@ -0,0 +1,8 @@
+/** A required context item is absent or contains undefined. */
+export declare class MissingPipelineItemError extends Error {
+    readonly itemName: string;
+    readonly requestName: string;
+    readonly handlerName: string;
+    constructor(itemName: string, requestName: string, handlerName: string, customMessage?: string);
+}
+//# sourceMappingURL=missing-pipeline-item.error.d.ts.map

package/dist/errors/missing-pipeline-item.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-pipeline-item.error.d.ts","sourceRoot":"","sources":["../../src/errors/missing-pipeline-item.error.ts"],"names":[],"mappings":"AAEA,+DAA+D;AAC/D,qBAAa,wBAAyB,SAAQ,KAAK;IAE/C,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM;IAH9B,YACW,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EAC5B,aAAa,CAAC,EAAE,MAAM,EAOvB;CACF"}

package/dist/errors/missing-pipeline-item.error.js

@@ -0,0 +1,16 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/** A required context item is absent or contains undefined. */
+export class MissingPipelineItemError extends Error {
+    itemName;
+    requestName;
+    handlerName;
+    constructor(itemName, requestName, handlerName, customMessage) {
+        super(`Missing pipeline item "${itemName}" for request "${requestName}" in handler "${handlerName}". Populate the item before reading it with requirePipelineItem.` +
+            (customMessage ? ` ${customMessage}` : ''));
+        this.itemName = itemName;
+        this.requestName = requestName;
+        this.handlerName = handlerName;
+        this.name = MissingPipelineItemError.name;
+    }
+}
+//# sourceMappingURL=missing-pipeline-item.error.js.map

package/dist/errors/missing-pipeline-item.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-pipeline-item.error.js","sourceRoot":"","sources":["../../src/errors/missing-pipeline-item.error.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,+DAA+D;AAC/D,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAEtC,QAAQ;IACR,WAAW;IACX,WAAW;IAHtB,YACW,QAAgB,EAChB,WAAmB,EACnB,WAAmB,EAC5B,aAAsB;QAEtB,KAAK,CACH,0BAA0B,QAAQ,kBAAkB,WAAW,iBAAiB,WAAW,kEAAkE;YAC3J,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAC7C,CAAC;wBARO,QAAQ;2BACR,WAAW;2BACX,WAAW;QAOpB,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC,IAAI,CAAC;IAC5C,CAAC;CACF"}

package/dist/handler-pipeline.d.ts

@@ -0,0 +1,62 @@
+import type { PipelineBehaviorEntry } from './entries.js';
+import type { BehaviorId } from './helpers/behavior-id.js';
+import type { IPipelineBehavior } from './interfaces/pipeline.behavior.interface.js';
+import type { Constructor } from './types.js';
+/** A class, of a request or of a handler, whatever its constructor takes. */
+export type AnyClass = abstract new (...args: any[]) => unknown;
+/**
+ * A class decorator for the standard and the `experimentalDecorators` mode: it receives
+ * the class, and a context only in the standard mode.
+ */
+export type DualClassDecorator = (target: AnyClass, context?: ClassDecoratorContext) => void;
+/** The pipeline a handler class declares with `@UsePipeline` and `@SkipPipeline`. */
+export interface HandlerPipeline {
+    readonly types: Constructor<IPipelineBehavior>[];
+    readonly options: Map<BehaviorId, Record<string, unknown>>;
+    readonly skipped: Constructor<IPipelineBehavior>[];
+}
+/**
+ * Declares the behaviors that run around a handler, outermost first: behavior classes or
+ * `[Behavior, options]` tuples such as `cache({ key })`. The global behaviors wrap these;
+ * a behavior declared in both runs once, at its global position, with these options
+ * merged over the global ones. The handler runtime reads the declaration with
+ * {@link pipelineOf}.
+ *
+ * @throws TypeError on a malformed entry.
+ * @example
+ * ```ts
+ * @CommandHandler(CreateUserCommand)
+ * @UsePipeline(idempotent({ keyFactory }), audit({ action: 'user.create' }))
+ * class CreateUserHandler implements ICommandHandler<CreateUserCommand> {
+ *   async execute(command: CreateUserCommand) {}
+ * }
+ * ```
+ */
+export declare function UsePipeline(...entries: PipelineBehaviorEntry[]): DualClassDecorator;
+/**
+ * Opts a handler out of global behaviors. Repeated decorators add up.
+ *
+ * @throws TypeError when an argument is not a behavior class.
+ * @example
+ * ```ts
+ * @QueryHandler(HealthQuery)
+ * @SkipPipeline(LoggingBehavior, TraceBehavior)
+ * class HealthHandler implements IQueryHandler<HealthQuery> {
+ *   async execute() {
+ *     return 'ok';
+ *   }
+ * }
+ * ```
+ */
+export declare function SkipPipeline(...behaviors: Constructor<IPipelineBehavior>[]): DualClassDecorator;
+/**
+ * The pipeline a handler class declares; empty when it declares none. A subclass
+ * inherits its parent's declaration until it declares its own.
+ *
+ * @example
+ * ```ts
+ * pipelineOf(CreateUserHandler).types; // [IdempotencyBehavior, AuditBehavior]
+ * ```
+ */
+export declare function pipelineOf(handler: AnyClass): HandlerPipeline;
+//# sourceMappingURL=handler-pipeline.d.ts.map

package/dist/handler-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-pipeline.d.ts","sourceRoot":"","sources":["../src/handler-pipeline.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAK9C,6EAA6E;AAE7E,MAAM,MAAM,QAAQ,GAAG,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC;AAEhE;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,MAAM,EAAE,QAAQ,EAChB,OAAO,CAAC,EAAE,qBAAqB,KAC5B,IAAI,CAAC;AAEV,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,iBAAiB,CAAC,EAAE,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,iBAAiB,CAAC,EAAE,CAAC;CACpD;AAUD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CACzB,GAAG,OAAO,EAAE,qBAAqB,EAAE,GAClC,kBAAkB,CASpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,GAAG,SAAS,EAAE,WAAW,CAAC,iBAAiB,CAAC,EAAE,GAC7C,kBAAkB,CAepB;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,QAAQ,GAAG,eAAe,CAO7D"}

package/dist/handler-pipeline.js

@@ -0,0 +1,74 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { normalizeBehaviorEntries } from './helpers/behavior-entries.js';
+const PIPELINE = Symbol.for('@cqrs-ddd/pipeline:handler-pipeline');
+const SKIPPED = Symbol.for('@cqrs-ddd/pipeline:skipped');
+function define(target, key, value) {
+    Object.defineProperty(target, key, { value, configurable: true });
+}
+function read(target, key) {
+    return target[key];
+}
+/**
+ * Declares the behaviors that run around a handler, outermost first: behavior classes or
+ * `[Behavior, options]` tuples such as `cache({ key })`. The global behaviors wrap these;
+ * a behavior declared in both runs once, at its global position, with these options
+ * merged over the global ones. The handler runtime reads the declaration with
+ * {@link pipelineOf}.
+ *
+ * @throws TypeError on a malformed entry.
+ * @example
+ * ```ts
+ * @CommandHandler(CreateUserCommand)
+ * @UsePipeline(idempotent({ keyFactory }), audit({ action: 'user.create' }))
+ * class CreateUserHandler implements ICommandHandler<CreateUserCommand> {
+ *   async execute(command: CreateUserCommand) {}
+ * }
+ * ```
+ */
+export function UsePipeline(...entries) {
+    return (target, context) => {
+        const name = String(context?.name ?? target.name);
+        const { types, options } = normalizeBehaviorEntries(entries, `@UsePipeline on ${name}`);
+        define(target, PIPELINE, { types, options });
+    };
+}
+/**
+ * Opts a handler out of global behaviors. Repeated decorators add up.
+ *
+ * @throws TypeError when an argument is not a behavior class.
+ * @example
+ * ```ts
+ * @QueryHandler(HealthQuery)
+ * @SkipPipeline(LoggingBehavior, TraceBehavior)
+ * class HealthHandler implements IQueryHandler<HealthQuery> {
+ *   async execute() {
+ *     return 'ok';
+ *   }
+ * }
+ * ```
+ */
+export function SkipPipeline(...behaviors) {
+    return (target, context) => {
+        const name = String(context?.name ?? target.name);
+        const existing = read(target, SKIPPED) ?? [];
+        define(target, SKIPPED, normalizeBehaviorEntries([...existing, ...behaviors], `@SkipPipeline on ${name}`, false).types);
+    };
+}
+/**
+ * The pipeline a handler class declares; empty when it declares none. A subclass
+ * inherits its parent's declaration until it declares its own.
+ *
+ * @example
+ * ```ts
+ * pipelineOf(CreateUserHandler).types; // [IdempotencyBehavior, AuditBehavior]
+ * ```
+ */
+export function pipelineOf(handler) {
+    const declared = read(handler, PIPELINE);
+    return {
+        types: declared?.types ?? [],
+        options: declared?.options ?? new Map(),
+        skipped: read(handler, SKIPPED) ?? [],
+    };
+}
+//# sourceMappingURL=handler-pipeline.js.map

package/dist/handler-pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-pipeline.js","sourceRoot":"","sources":["../src/handler-pipeline.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAGtE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAKzE,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,qCAAqC,CAAC,CAAC;AACnE,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;AAsBzD,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;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,WAAW,CACzB,GAAG,OAAgC;IAEnC,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE;QACzB,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;QAClD,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,wBAAwB,CACjD,OAAO,EACP,mBAAmB,IAAI,EAAE,CAC1B,CAAC;QACF,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;IAC/C,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAG,SAA2C;IAE9C,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE;QACzB,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;QAClD,MAAM,QAAQ,GACZ,IAAI,CAAmC,MAAM,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;QAChE,MAAM,CACJ,MAAM,EACN,OAAO,EACP,wBAAwB,CACtB,CAAC,GAAG,QAAQ,EAAE,GAAG,SAAS,CAAC,EAC3B,oBAAoB,IAAI,EAAE,EAC1B,KAAK,CACN,CAAC,KAAK,CACR,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,OAAiB;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAmC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC3E,OAAO;QACL,KAAK,EAAE,QAAQ,EAAE,KAAK,IAAI,EAAE;QAC5B,OAAO,EAAE,QAAQ,EAAE,OAAO,IAAI,IAAI,GAAG,EAAE;QACvC,OAAO,EAAE,IAAI,CAAmC,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE;KACxE,CAAC;AACJ,CAAC"}

package/dist/helpers/behavior-entries.d.ts

@@ -0,0 +1,34 @@
+import type { IPipelineBehavior } from '../interfaces/pipeline.behavior.interface.js';
+import type { Constructor } from '../types.js';
+import { type BehaviorId } from './behavior-id.js';
+/** Validates a declaration before its plan is compiled. */
+export declare function behaviorEntryType(entry: unknown, location: string, allowTuple?: boolean): Constructor<IPipelineBehavior>;
+/**
+ * Accumulators shared across several calls, so one identity is deduplicated
+ * across every chain position and every matching global configuration.
+ */
+export interface BehaviorEntryAccumulators {
+    /** Identities already placed. The first occurrence fixes chain position. */
+    seen: Set<BehaviorId>;
+    /** Options by identity. A later tuple supplies the effective options. */
+    options: Map<BehaviorId, Record<string, unknown>>;
+}
+/**
+ * First identity fixes placement; the last tuple supplies options. Bare repeats
+ * preserve options.
+ *
+ * Pass `accumulators` to apply that rule across multiple entry lists — global
+ * `before` and `after` share one set so a behavior declared in both runs once,
+ * at its first position, without the bare repeat erasing tuple options.
+ *
+ * @param entries - Raw declarations, each a behavior class or `[Class, options]`.
+ * @param location - Human-readable declaration site, used in thrown messages.
+ * @param allowTuple - Whether `[Class, options]` is accepted (`@SkipPipeline` takes classes only).
+ * @param accumulators - Shared dedup state; a fresh pair is used when omitted.
+ * @returns Types to include, in first-seen order, plus the options map.
+ */
+export declare function normalizeBehaviorEntries(entries: readonly unknown[], location: string, allowTuple?: boolean, accumulators?: BehaviorEntryAccumulators): {
+    types: Constructor<IPipelineBehavior>[];
+    options: Map<BehaviorId, Record<string, unknown>>;
+};
+//# sourceMappingURL=behavior-entries.d.ts.map

package/dist/helpers/behavior-entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"behavior-entries.d.ts","sourceRoot":"","sources":["../../src/helpers/behavior-entries.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAC;AACtF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,KAAK,UAAU,EAAiB,MAAM,kBAAkB,CAAC;AAElE,2DAA2D;AAC3D,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,UAAU,UAAO,GAChB,WAAW,CAAC,iBAAiB,CAAC,CAuBhC;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,4EAA4E;IAC5E,IAAI,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IACtB,yEAAyE;IACzE,OAAO,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,SAAS,OAAO,EAAE,EAC3B,QAAQ,EAAE,MAAM,EAChB,UAAU,UAAO,EACjB,YAAY,CAAC,EAAE,yBAAyB,GACvC;IACD,KAAK,EAAE,WAAW,CAAC,iBAAiB,CAAC,EAAE,CAAC;IACxC,OAAO,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD,CAoBA"}

package/dist/helpers/behavior-entries.js

@@ -0,0 +1,50 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { getBehaviorId } from './behavior-id.js';
+/** Validates a declaration before its plan is compiled. */
+export function behaviorEntryType(entry, location, allowTuple = true) {
+    const tuple = Array.isArray(entry);
+    const candidate = tuple && allowTuple ? entry[0] : entry;
+    if (typeof candidate !== 'function' ||
+        !candidate.prototype ||
+        (tuple && entry.length !== 2)) {
+        throw new TypeError(`${location}: expected a behavior class${allowTuple ? ' or a [BehaviorClass, options] tuple' : ''}. Check for undefined references caused by circular imports.`);
+    }
+    if (tuple &&
+        (entry[1] === null ||
+            typeof entry[1] !== 'object' ||
+            Array.isArray(entry[1]))) {
+        throw new TypeError(`${location}: options for ${candidate.name} must be an object.`);
+    }
+    return candidate;
+}
+/**
+ * First identity fixes placement; the last tuple supplies options. Bare repeats
+ * preserve options.
+ *
+ * Pass `accumulators` to apply that rule across multiple entry lists — global
+ * `before` and `after` share one set so a behavior declared in both runs once,
+ * at its first position, without the bare repeat erasing tuple options.
+ *
+ * @param entries - Raw declarations, each a behavior class or `[Class, options]`.
+ * @param location - Human-readable declaration site, used in thrown messages.
+ * @param allowTuple - Whether `[Class, options]` is accepted (`@SkipPipeline` takes classes only).
+ * @param accumulators - Shared dedup state; a fresh pair is used when omitted.
+ * @returns Types to include, in first-seen order, plus the options map.
+ */
+export function normalizeBehaviorEntries(entries, location, allowTuple = true, accumulators) {
+    const types = [];
+    const options = accumulators?.options ?? new Map();
+    const seen = accumulators?.seen ?? new Set();
+    entries.forEach((entry, index) => {
+        const type = behaviorEntryType(entry, `${location}, entry ${index}`, allowTuple);
+        const id = getBehaviorId(type);
+        if (Array.isArray(entry))
+            options.set(id, entry[1]);
+        if (!seen.has(id)) {
+            seen.add(id);
+            types.push(type);
+        }
+    });
+    return { types, options };
+}
+//# sourceMappingURL=behavior-entries.js.map

package/dist/helpers/behavior-entries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"behavior-entries.js","sourceRoot":"","sources":["../../src/helpers/behavior-entries.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAItE,OAAO,EAAmB,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAElE,2DAA2D;AAC3D,MAAM,UAAU,iBAAiB,CAC/B,KAAc,EACd,QAAgB,EAChB,UAAU,GAAG,IAAI;IAEjB,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACnC,MAAM,SAAS,GAAG,KAAK,IAAI,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACzD,IACE,OAAO,SAAS,KAAK,UAAU;QAC/B,CAAC,SAAS,CAAC,SAAS;QACpB,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,EAC7B,CAAC;QACD,MAAM,IAAI,SAAS,CACjB,GAAG,QAAQ,8BAA8B,UAAU,CAAC,CAAC,CAAC,sCAAsC,CAAC,CAAC,CAAC,EAAE,8DAA8D,CAChK,CAAC;IACJ,CAAC;IACD,IACE,KAAK;QACL,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI;YAChB,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ;YAC5B,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAC1B,CAAC;QACD,MAAM,IAAI,SAAS,CACjB,GAAG,QAAQ,iBAAiB,SAAS,CAAC,IAAI,qBAAqB,CAChE,CAAC;IACJ,CAAC;IACD,OAAO,SAA2C,CAAC;AACrD,CAAC;AAaD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAA2B,EAC3B,QAAgB,EAChB,UAAU,GAAG,IAAI,EACjB,YAAwC;IAKxC,MAAM,KAAK,GAAqC,EAAE,CAAC;IACnD,MAAM,OAAO,GACX,YAAY,EAAE,OAAO,IAAI,IAAI,GAAG,EAAuC,CAAC;IAC1E,MAAM,IAAI,GAAG,YAAY,EAAE,IAAI,IAAI,IAAI,GAAG,EAAc,CAAC;IACzD,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QAC/B,MAAM,IAAI,GAAG,iBAAiB,CAC5B,KAAK,EACL,GAAG,QAAQ,WAAW,KAAK,EAAE,EAC7B,UAAU,CACX,CAAC;QACF,MAAM,EAAE,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YACtB,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAA4B,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAClB,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACb,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC5B,CAAC"}

package/dist/helpers/behavior-id.d.ts

@@ -0,0 +1,43 @@
+import type { IPipelineBehavior } from '../interfaces/pipeline.behavior.interface.js';
+import type { Constructor } from '../types.js';
+/**
+ * Optional static property on a behavior class that provides a stable,
+ * unique identity for deduplication when global and handler behaviors overlap.
+ *
+ * Use this to recognize one behavior across multiple loaded copies of its package:
+ *
+ * ```ts
+ * export class LoggingBehavior implements IPipelineBehavior {
+ *   static readonly [PIPELINE_BEHAVIOR_ID] = 'my-package:LoggingBehavior';
+ * }
+ * ```
+ *
+ * When absent, the constructor reference is used as the fallback identity.
+ */
+export declare const PIPELINE_BEHAVIOR_ID: unique symbol;
+/**
+ * Identity of a behavior for deduplication and option lookup.
+ *
+ * Either the constructor itself — the default, and exact — or the string a class
+ * opted into through {@link PIPELINE_BEHAVIOR_ID}.
+ */
+export type BehaviorId = string | Constructor<IPipelineBehavior>;
+/**
+ * Returns the identity used to deduplicate a behavior and resolve its options.
+ *
+ * By default the constructor reference is the identity. A behavior that must be
+ * recognized across multiple loaded copies of the same package can opt into a
+ * stable string identity through {@link PIPELINE_BEHAVIOR_ID}.
+ *
+ * @param cls - Behavior class whose identity should be resolved.
+ * @returns The constructor reference or the behavior's explicit stable id.
+ *
+ * @example Stable identity across duplicated package copies
+ * ```ts
+ * export class LoggingBehavior implements IPipelineBehavior {
+ *   static readonly [PIPELINE_BEHAVIOR_ID] = 'my-package:LoggingBehavior';
+ * }
+ * ```
+ */
+export declare function getBehaviorId(cls: Constructor<IPipelineBehavior>): BehaviorId;
+//# sourceMappingURL=behavior-id.d.ts.map

package/dist/helpers/behavior-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"behavior-id.d.ts","sourceRoot":"","sources":["../../src/helpers/behavior-id.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAC;AACtF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,eAEhC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,WAAW,CAAC,iBAAiB,CAAC,CAAC;AAEjE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,WAAW,CAAC,iBAAiB,CAAC,GAAG,UAAU,CAE7E"}