@cqrs-ddd/pipeline-rate-limit 0.5.0

package/README.md

@@ -0,0 +1,36 @@
+# @cqrs-ddd/pipeline-rate-limit
+
+Rate limiting for `@cqrs-ddd/pipeline`, on any limiter with a `consume()` method such as
+those of [rate-limiter-flexible](https://github.com/animir/node-rate-limiter-flexible)
+(memory, Redis, PostgreSQL). `createPartitionedRateLimitKeyFactory()` builds keys
+partitioned by tenant, principal and operation; `toHttpResponse()` from
+`@cqrs-ddd/pipeline-rate-limit/http` turns a refusal into a 429 answer with `Retry-After`.
+
+**Documentation:** [guide](https://aristoteliss.github.io/ddd-cqrs/packages/pipeline-rate-limit/) · [API reference](https://aristoteliss.github.io/ddd-cqrs/api/cqrs-ddd/pipeline-rate-limit/) · [all packages](https://aristoteliss.github.io/ddd-cqrs/)
+
+## Installation
+
+```bash
+pnpm add @cqrs-ddd/pipeline-rate-limit @cqrs-ddd/pipeline rate-limiter-flexible
+```
+
+Requires Node.js 22.12 or later. Published as an ES module; a CommonJS application loads
+it with `require()`.
+
+## Example
+
+```ts
+const pipeline = createPipeline({
+  behaviors: [new RateLimitBehavior(new RateLimiterMemory({ points: 10, duration: 60 }))],
+});
+
+export const search = pipeline.wrap(
+  { name: 'search', kind: 'query' },
+  rateLimit({ keyFactory: createPartitionedRateLimitKeyFactory(currentUserId) }),
+)(async (term: string) => catalog.search(term));
+```
+
+## License
+
+Dual-licensed under **AGPLv3** and a **Commercial License**. See `LICENSE` and
+`COMMERCIAL_LICENSE.txt`.

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

@@ -0,0 +1,13 @@
+import { MissingPartitionError } from '@cqrs-ddd/pipeline';
+/** Which dimension of the bucket key could not be resolved. */
+export type RateLimitPartitionDimension = 'tenant' | 'caller';
+/**
+ * Raised before the limiter is consumed when a dimension required by the
+ * configured key factory cannot be resolved; omitting the segment instead would
+ * put every unresolved caller into one shared bucket.
+ */
+export declare class MissingRateLimitPartitionError extends MissingPartitionError<RateLimitPartitionDimension> {
+    readonly name = "MissingRateLimitPartitionError";
+    constructor(requestName: string, dimension: RateLimitPartitionDimension, 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,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,+DAA+D;AAC/D,MAAM,MAAM,2BAA2B,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9D;;;;GAIG;AACH,qBAAa,8BAA+B,SAAQ,qBAAqB,CAAC,2BAA2B,CAAC;IACpG,SAAkB,IAAI,oCAAoC;IAE1D,YACE,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,2BAA2B,EACtC,MAAM,EAAE,MAAM,EAGf;CACF"}

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

@@ -0,0 +1,14 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { MissingPartitionError } from '@cqrs-ddd/pipeline';
+/**
+ * Raised before the limiter is consumed when a dimension required by the
+ * configured key factory cannot be resolved; omitting the segment instead would
+ * put every unresolved caller into one shared bucket.
+ */
+export class MissingRateLimitPartitionError extends MissingPartitionError {
+    name = 'MissingRateLimitPartitionError';
+    constructor(requestName, dimension, remedy) {
+        super('Rate-limit', requestName, dimension, 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,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAK3D;;;;GAIG;AACH,MAAM,OAAO,8BAA+B,SAAQ,qBAAkD;IAClF,IAAI,GAAG,gCAAgC,CAAC;IAE1D,YACE,WAAmB,EACnB,SAAsC,EACtC,MAAc;QAEd,KAAK,CAAC,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IACtD,CAAC;CACF"}

package/dist/errors/rate-limit-exceeded.error.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Thrown by {@link RateLimitBehavior} when a request exceeds its allotted
+ * points for the current window.
+ *
+ * Map it to HTTP `429 Too Many Requests` with {@link RateLimitExceededFilter},
+ * which also emits a `Retry-After` header from {@link retryAfterSeconds}.
+ */
+export declare class RateLimitExceededError extends Error {
+    /** The rate-limit bucket key that was exhausted. */
+    readonly key: string;
+    /** The request that was throttled, e.g. `CreateUserCommand`. */
+    readonly requestName: string;
+    /** Milliseconds until the caller may retry. */
+    readonly msBeforeNext: number;
+    /** Seconds until the caller may retry (rounded up), for `Retry-After`. */
+    readonly retryAfterSeconds: number;
+    /** Points remaining in the window (typically `0` here). */
+    readonly remainingPoints: number;
+    /** Configured point capacity per window, when known. */
+    readonly limit?: number;
+    /**
+     * Points the rejected request asked for, when known. A request costing more
+     * than {@link limit} can never pass, whatever the wait.
+     */
+    readonly points?: number;
+    constructor(params: {
+        key: string;
+        requestName: string;
+        msBeforeNext: number;
+        remainingPoints: number;
+        limit?: number;
+        points?: number;
+    });
+}
+//# sourceMappingURL=rate-limit-exceeded.error.d.ts.map

package/dist/errors/rate-limit-exceeded.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit-exceeded.error.d.ts","sourceRoot":"","sources":["../../src/errors/rate-limit-exceeded.error.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,oDAAoD;IACpD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB,YAAY,MAAM,EAAE;QAClB,GAAG,EAAE,MAAM,CAAC;QACZ,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe,EAAE,MAAM,CAAC;QACxB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,EAiBA;CACF"}

package/dist/errors/rate-limit-exceeded.error.js

@@ -0,0 +1,41 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * Thrown by {@link RateLimitBehavior} when a request exceeds its allotted
+ * points for the current window.
+ *
+ * Map it to HTTP `429 Too Many Requests` with {@link RateLimitExceededFilter},
+ * which also emits a `Retry-After` header from {@link retryAfterSeconds}.
+ */
+export class RateLimitExceededError extends Error {
+    /** The rate-limit bucket key that was exhausted. */
+    key;
+    /** The request that was throttled, e.g. `CreateUserCommand`. */
+    requestName;
+    /** Milliseconds until the caller may retry. */
+    msBeforeNext;
+    /** Seconds until the caller may retry (rounded up), for `Retry-After`. */
+    retryAfterSeconds;
+    /** Points remaining in the window (typically `0` here). */
+    remainingPoints;
+    /** Configured point capacity per window, when known. */
+    limit;
+    /**
+     * Points the rejected request asked for, when known. A request costing more
+     * than {@link limit} can never pass, whatever the wait.
+     */
+    points;
+    constructor(params) {
+        const retryAfterSeconds = Math.max(1, Math.ceil(params.msBeforeNext / 1000));
+        super(`Rate limit exceeded for ${params.requestName} ` +
+            `(key: ${params.key}); retry after ${retryAfterSeconds}s`);
+        this.name = 'RateLimitExceededError';
+        this.key = params.key;
+        this.requestName = params.requestName;
+        this.msBeforeNext = params.msBeforeNext;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.remainingPoints = params.remainingPoints;
+        this.limit = params.limit;
+        this.points = params.points;
+    }
+}
+//# sourceMappingURL=rate-limit-exceeded.error.js.map

package/dist/errors/rate-limit-exceeded.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit-exceeded.error.js","sourceRoot":"","sources":["../../src/errors/rate-limit-exceeded.error.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE;;;;;;GAMG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,oDAAoD;IAC3C,GAAG,CAAS;IACrB,gEAAgE;IACvD,WAAW,CAAS;IAC7B,+CAA+C;IACtC,YAAY,CAAS;IAC9B,0EAA0E;IACjE,iBAAiB,CAAS;IACnC,2DAA2D;IAClD,eAAe,CAAS;IACjC,wDAAwD;IAC/C,KAAK,CAAU;IACxB;;;OAGG;IACM,MAAM,CAAU;IAEzB,YAAY,MAOX;QACC,MAAM,iBAAiB,GAAG,IAAI,CAAC,GAAG,CAChC,CAAC,EACD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,CACtC,CAAC;QACF,KAAK,CACH,2BAA2B,MAAM,CAAC,WAAW,GAAG;YAC9C,SAAS,MAAM,CAAC,GAAG,kBAAkB,iBAAiB,GAAG,CAC5D,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;QACtB,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QACtC,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;QACxC,IAAI,CAAC,iBAAiB,GAAG,iBAAiB,CAAC;QAC3C,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC;QAC9C,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC9B,CAAC;CACF"}

package/dist/helpers/build-attributes.d.ts

@@ -0,0 +1,47 @@
+import { type IPipelineContext } from '@cqrs-ddd/pipeline';
+/**
+ * The rate-limit decision of one execution as flat attributes:
+ * `rate_limit.remaining_points` once `RateLimitBehavior` consumed points and the
+ * limiter reported what remains, `{}` otherwise. The key is never included: it
+ * carries the tenant and the caller.
+ *
+ * The result is plain data and needs no telemetry package: put it on a span, a
+ * log line, an audit record or a metric label (bounded values only). The remaining points take as many values as the limiter has
+ * points; keep them out of metric labels unless that is bounded enough.
+ *
+ * @param context - The pipeline execution, read after `RateLimitBehavior` ran.
+ * @returns The attributes; empty when the behavior did not run.
+ *
+ * @example Span attributes
+ * With `AttributesBehavior` of `@cqrs-ddd/pipeline-opentelemetry`:
+ * ```ts
+ * createPipeline({
+ *   globalBehaviors: {
+ *     before: [TraceBehavior, [AttributesBehavior, { factories: [buildRateLimitAttributes] }]],
+ *   },
+ * });
+ * ```
+ *
+ * @example Audit metadata
+ * `audit()` is declared outside `rateLimit()`, so the record is built after its decision:
+ * ```ts
+ * @pipeline.wrap(
+ *   { kind: 'command' },
+ *   audit({ action: 'order.create', metadata: buildRateLimitAttributes }),
+ *   rateLimit({ keyFactory, points: 1 }),
+ * )
+ * ```
+ *
+ * @example A log line from a custom behavior, after the chain ran
+ * ```ts
+ * async handle(context: IPipelineContext, next: NextDelegate) {
+ *   try {
+ *     return await next();
+ *   } finally {
+ *     this.logger.log({ request: context.requestName, ...buildRateLimitAttributes(context) });
+ *   }
+ * }
+ * ```
+ */
+export declare function buildRateLimitAttributes(context: IPipelineContext): Record<string, number>;
+//# sourceMappingURL=build-attributes.d.ts.map

package/dist/helpers/build-attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-attributes.d.ts","sourceRoot":"","sources":["../../src/helpers/build-attributes.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,gBAAgB,GACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKxB"}

package/dist/helpers/build-attributes.js

@@ -0,0 +1,54 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { getPipelineItem } from '@cqrs-ddd/pipeline';
+import { RATE_LIMIT_ITEM_TOKEN } from '../rate-limit.behavior.js';
+/**
+ * The rate-limit decision of one execution as flat attributes:
+ * `rate_limit.remaining_points` once `RateLimitBehavior` consumed points and the
+ * limiter reported what remains, `{}` otherwise. The key is never included: it
+ * carries the tenant and the caller.
+ *
+ * The result is plain data and needs no telemetry package: put it on a span, a
+ * log line, an audit record or a metric label (bounded values only). The remaining points take as many values as the limiter has
+ * points; keep them out of metric labels unless that is bounded enough.
+ *
+ * @param context - The pipeline execution, read after `RateLimitBehavior` ran.
+ * @returns The attributes; empty when the behavior did not run.
+ *
+ * @example Span attributes
+ * With `AttributesBehavior` of `@cqrs-ddd/pipeline-opentelemetry`:
+ * ```ts
+ * createPipeline({
+ *   globalBehaviors: {
+ *     before: [TraceBehavior, [AttributesBehavior, { factories: [buildRateLimitAttributes] }]],
+ *   },
+ * });
+ * ```
+ *
+ * @example Audit metadata
+ * `audit()` is declared outside `rateLimit()`, so the record is built after its decision:
+ * ```ts
+ * @pipeline.wrap(
+ *   { kind: 'command' },
+ *   audit({ action: 'order.create', metadata: buildRateLimitAttributes }),
+ *   rateLimit({ keyFactory, points: 1 }),
+ * )
+ * ```
+ *
+ * @example A log line from a custom behavior, after the chain ran
+ * ```ts
+ * async handle(context: IPipelineContext, next: NextDelegate) {
+ *   try {
+ *     return await next();
+ *   } finally {
+ *     this.logger.log({ request: context.requestName, ...buildRateLimitAttributes(context) });
+ *   }
+ * }
+ * ```
+ */
+export function buildRateLimitAttributes(context) {
+    const result = getPipelineItem(context, RATE_LIMIT_ITEM_TOKEN);
+    return typeof result?.remainingPoints === 'number'
+        ? { 'rate_limit.remaining_points': result.remainingPoints }
+        : {};
+}
+//# sourceMappingURL=build-attributes.js.map

package/dist/helpers/build-attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-attributes.js","sourceRoot":"","sources":["../../src/helpers/build-attributes.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAE,eAAe,EAAyB,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAyB;IAEzB,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC;IAC/D,OAAO,OAAO,MAAM,EAAE,eAAe,KAAK,QAAQ;QAChD,CAAC,CAAC,EAAE,6BAA6B,EAAE,MAAM,CAAC,eAAe,EAAE;QAC3D,CAAC,CAAC,EAAE,CAAC;AACT,CAAC"}

package/dist/helpers/build-key.d.ts

@@ -0,0 +1,23 @@
+import { type IPipelineContext } from '@cqrs-ddd/pipeline';
+import type { RateLimitBehaviorOptions } from '../interfaces/rate-limit-options.interface.js';
+/**
+ * Resolve the rate-limit bucket key for a request.
+ *
+ * A `keyFactory` is required; a request-name-only bucket is shared by every
+ * caller in every tenant.
+ *
+ * Callers that genuinely want an application-wide operation bucket say so:
+ *
+ * ```ts
+ * { keyFactory: (ctx) => ctx.requestName }
+ * ```
+ *
+ * `options.keyPrefix` is prepended as `"<prefix>:<key>"` when provided, so
+ * environment and service prefixes stay orthogonal to the partitioning choice.
+ *
+ * @param context - The pipeline context of the current request.
+ * @param options - Effective behavior options.
+ * @throws {TypeError} When no `keyFactory` is configured.
+ */
+export declare function buildRateLimitKey(context: IPipelineContext, options?: RateLimitBehaviorOptions): string;
+//# sourceMappingURL=build-key.d.ts.map

package/dist/helpers/build-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-key.d.ts","sourceRoot":"","sources":["../../src/helpers/build-key.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+CAA+C,CAAC;AAE9F;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,wBAA6B,GACrC,MAAM,CAkBR"}

package/dist/helpers/build-key.js

@@ -0,0 +1,38 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { escapeKeySegment } from '@cqrs-ddd/safe-stringify';
+/**
+ * Resolve the rate-limit bucket key for a request.
+ *
+ * A `keyFactory` is required; a request-name-only bucket is shared by every
+ * caller in every tenant.
+ *
+ * Callers that genuinely want an application-wide operation bucket say so:
+ *
+ * ```ts
+ * { keyFactory: (ctx) => ctx.requestName }
+ * ```
+ *
+ * `options.keyPrefix` is prepended as `"<prefix>:<key>"` when provided, so
+ * environment and service prefixes stay orthogonal to the partitioning choice.
+ *
+ * @param context - The pipeline context of the current request.
+ * @param options - Effective behavior options.
+ * @throws {TypeError} When no `keyFactory` is configured.
+ */
+export function buildRateLimitKey(context, options = {}) {
+    if (!options.keyFactory) {
+        throw new TypeError(`RateLimitBehavior on ${context.handlerName} requires an explicit keyFactory. ` +
+            'A request-name-only bucket is shared by every caller in every tenant, so a ' +
+            'single client can exhaust it for all of them. Use ' +
+            'createPartitionedRateLimitKeyFactory(...) for per-caller limits, or pass ' +
+            'keyFactory: (ctx) => ctx.requestName to accept a global bucket deliberately.');
+    }
+    const base = options.keyFactory(context);
+    // Only the prefix is escaped. `base` is already a complete key — a partitioned
+    // factory has escaped its own segments — so re-escaping it here would mangle
+    // the documented "<prefix>:<key>" shape.
+    return options.keyPrefix
+        ? `${escapeKeySegment(options.keyPrefix)}:${base}`
+        : base;
+}
+//# sourceMappingURL=build-key.js.map

package/dist/helpers/build-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-key.js","sourceRoot":"","sources":["../../src/helpers/build-key.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAGtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAG5D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAyB,EACzB,OAAO,GAA6B,EAAE;IAEtC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QACxB,MAAM,IAAI,SAAS,CACjB,wBAAwB,OAAO,CAAC,WAAW,oCAAoC;YAC7E,6EAA6E;YAC7E,oDAAoD;YACpD,2EAA2E;YAC3E,8EAA8E,CACjF,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IACzC,+EAA+E;IAC/E,6EAA6E;IAC7E,yCAAyC;IACzC,OAAO,OAAO,CAAC,SAAS;QACtB,CAAC,CAAC,GAAG,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,IAAI,EAAE;QAClD,CAAC,CAAC,IAAI,CAAC;AACX,CAAC"}

package/dist/helpers/partitioned-key.d.ts

@@ -0,0 +1,65 @@
+import { type IPipelineContext, type TenantPartitionOptions } from '@cqrs-ddd/pipeline';
+import type { RateLimitKeyFactory } from '../interfaces/rate-limit-options.interface.js';
+/**
+ * Resolves the stable caller/partition identifier used by
+ * {@link createPartitionedRateLimitKeyFactory}.
+ *
+ * Typical values are an authenticated user ID, account ID, API-client ID, or a
+ * trusted transport identity copied into `context.items` by an earlier behavior.
+ */
+export type RateLimitPartitionFactory = (context: IPipelineContext) => string | undefined;
+/** Options for {@link createPartitionedRateLimitKeyFactory}. */
+export interface PartitionedRateLimitKeyOptions extends TenantPartitionOptions {
+    /**
+     * Behavior when the partition factory cannot resolve a non-empty identity.
+     *
+     * - `throw` — fail before consuming the limiter (recommended for per-caller
+     *   security limits because silently falling back could merge callers).
+     * - `request` — fall back to a bucket shared by every caller of this request
+     *   within the same tenant partition.
+     *
+     * @default 'throw'
+     */
+    onMissingPartition?: 'throw' | 'request';
+}
+/**
+ * Creates a {@link RateLimitKeyFactory} for per-caller limits.
+ *
+ * Segments are escaped and joined through the core key helper so tenant,
+ * caller/account identity, and request name remain distinct even when values
+ * contain separator characters.
+ *
+ * @param partitionFactory - Resolves the stable caller/account identity.
+ * @param options - Tenant and missing-partition policy.
+ * @returns A `RateLimitKeyFactory` suitable for `RateLimitBehaviorOptions.keyFactory`.
+ * @throws {MissingRateLimitPartitionError} When a required tenant or caller partition is absent.
+ *
+ * The produced key is `<tenantId>:<partition>:<requestName>` when tenant
+ * inclusion is enabled, `<partition>:<requestName>` otherwise.
+ * `RateLimitBehaviorOptions.keyPrefix` is still applied afterwards by
+ * `buildRateLimitKey()`, so environment/service prefixes remain orthogonal.
+ *
+ * @example Per authenticated user, tenant-aware and fail-closed by default
+ * ```ts
+ * const perUserKey = createPartitionedRateLimitKeyFactory((ctx) =>
+ *   ctx.items.get('currentUserId') as string | undefined,
+ * );
+ *
+ * class CreateOrderHandler {
+ *   @pipeline.wrap({ kind: 'command' }, [RateLimitBehavior, { keyFactory: perUserKey, keyPrefix: 'write-api' }])
+ *   async handle(command: CreateOrderCommand) {}
+ * }
+ * ```
+ *
+ * @example Single-tenant deployment — say so explicitly
+ * ```ts
+ * createPartitionedRateLimitKeyFactory(readUserId, { includeTenant: false });
+ * ```
+ *
+ * @example Account-wide bucket shared by every user in the account
+ * ```ts
+ * createPartitionedRateLimitKeyFactory(readAccountId, { includeTenant: true });
+ * ```
+ */
+export declare function createPartitionedRateLimitKeyFactory(partitionFactory: RateLimitPartitionFactory, options?: PartitionedRateLimitKeyOptions): RateLimitKeyFactory;
+//# sourceMappingURL=partitioned-key.d.ts.map

package/dist/helpers/partitioned-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"partitioned-key.d.ts","sourceRoot":"","sources":["../../src/helpers/partitioned-key.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAE5B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AAEzF;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GAAG,CACtC,OAAO,EAAE,gBAAgB,KACtB,MAAM,GAAG,SAAS,CAAC;AAExB,gEAAgE;AAChE,MAAM,WAAW,8BAA+B,SAAQ,sBAAsB;IAC5E;;;;;;;;;OASG;IACH,kBAAkB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,oCAAoC,CAClD,gBAAgB,EAAE,yBAAyB,EAC3C,OAAO,GAAE,8BAAmC,GAC3C,mBAAmB,CA4BrB"}

package/dist/helpers/partitioned-key.js

@@ -0,0 +1,61 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { tenantSegments, } from '@cqrs-ddd/pipeline';
+import { joinKeySegments } from '@cqrs-ddd/safe-stringify';
+import { MissingRateLimitPartitionError } from '../errors/missing-partition.error.js';
+/**
+ * Creates a {@link RateLimitKeyFactory} for per-caller limits.
+ *
+ * Segments are escaped and joined through the core key helper so tenant,
+ * caller/account identity, and request name remain distinct even when values
+ * contain separator characters.
+ *
+ * @param partitionFactory - Resolves the stable caller/account identity.
+ * @param options - Tenant and missing-partition policy.
+ * @returns A `RateLimitKeyFactory` suitable for `RateLimitBehaviorOptions.keyFactory`.
+ * @throws {MissingRateLimitPartitionError} When a required tenant or caller partition is absent.
+ *
+ * The produced key is `<tenantId>:<partition>:<requestName>` when tenant
+ * inclusion is enabled, `<partition>:<requestName>` otherwise.
+ * `RateLimitBehaviorOptions.keyPrefix` is still applied afterwards by
+ * `buildRateLimitKey()`, so environment/service prefixes remain orthogonal.
+ *
+ * @example Per authenticated user, tenant-aware and fail-closed by default
+ * ```ts
+ * const perUserKey = createPartitionedRateLimitKeyFactory((ctx) =>
+ *   ctx.items.get('currentUserId') as string | undefined,
+ * );
+ *
+ * class CreateOrderHandler {
+ *   @pipeline.wrap({ kind: 'command' }, [RateLimitBehavior, { keyFactory: perUserKey, keyPrefix: 'write-api' }])
+ *   async handle(command: CreateOrderCommand) {}
+ * }
+ * ```
+ *
+ * @example Single-tenant deployment — say so explicitly
+ * ```ts
+ * createPartitionedRateLimitKeyFactory(readUserId, { includeTenant: false });
+ * ```
+ *
+ * @example Account-wide bucket shared by every user in the account
+ * ```ts
+ * createPartitionedRateLimitKeyFactory(readAccountId, { includeTenant: true });
+ * ```
+ */
+export function createPartitionedRateLimitKeyFactory(partitionFactory, options = {}) {
+    const onMissingPartition = options.onMissingPartition ?? 'throw';
+    return (context) => {
+        const tenant = tenantSegments(context, options, MissingRateLimitPartitionError);
+        const resolved = partitionFactory(context);
+        const partition = typeof resolved === 'string' ? resolved.trim() : '';
+        if (!partition) {
+            if (onMissingPartition === 'throw') {
+                throw new MissingRateLimitPartitionError(context.requestName, 'caller', "Return a stable caller/account identifier, or configure onMissingPartition: 'request'.");
+            }
+            // Shared bucket, but still inside the tenant partition when one is used,
+            // so an anonymous caller in one tenant cannot exhaust another tenant's quota.
+            return joinKeySegments([...tenant, context.requestName]);
+        }
+        return joinKeySegments([...tenant, partition, context.requestName]);
+    };
+}
+//# sourceMappingURL=partitioned-key.js.map

package/dist/helpers/partitioned-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"partitioned-key.js","sourceRoot":"","sources":["../../src/helpers/partitioned-key.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAGL,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,8BAA8B,EAAE,MAAM,sCAAsC,CAAC;AA6BtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,UAAU,oCAAoC,CAClD,gBAA2C,EAC3C,OAAO,GAAmC,EAAE;IAE5C,MAAM,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,IAAI,OAAO,CAAC;IAEjE,OAAO,CAAC,OAAO,EAAE,EAAE;QACjB,MAAM,MAAM,GAAG,cAAc,CAC3B,OAAO,EACP,OAAO,EACP,8BAA8B,CAC/B,CAAC;QAEF,MAAM,QAAQ,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,SAAS,GAAG,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAEtE,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,IAAI,kBAAkB,KAAK,OAAO,EAAE,CAAC;gBACnC,MAAM,IAAI,8BAA8B,CACtC,OAAO,CAAC,WAAW,EACnB,QAAQ,EACR,wFAAwF,CACzF,CAAC;YACJ,CAAC;YACD,yEAAyE;YACzE,8EAA8E;YAC9E,OAAO,eAAe,CAAC,CAAC,GAAG,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;QAC3D,CAAC;QAED,OAAO,eAAe,CAAC,CAAC,GAAG,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IACtE,CAAC,CAAC;AACJ,CAAC"}

package/dist/helpers/rate-limit.intent.d.ts

@@ -0,0 +1,30 @@
+import type { PipelineBehaviorTuple } from '@cqrs-ddd/pipeline';
+import type { RateLimitBehaviorOptions } from '../interfaces/rate-limit-options.interface.js';
+import { RateLimitBehavior } from '../rate-limit.behavior.js';
+export type RateLimitIntentOptions = Omit<RateLimitBehaviorOptions, 'keyFactory'> & ({
+    keyFactory: NonNullable<RateLimitBehaviorOptions['keyFactory']>;
+    inheritModuleKey?: never;
+} | {
+    inheritModuleKey: true;
+    keyFactory?: never;
+});
+/**
+ * Returns a rate-limit behavior entry for `pipeline.wrap()` or `createPipeline({ globalBehaviors })`.
+ * @param options A key factory and rate-limit options, or `inheritModuleKey: true`
+ * when the behavior's constructor defaults supply the key factory. The inheritance marker is not
+ * forwarded to the behavior and does not validate module configuration.
+ * @returns The behavior class and options tuple.
+ * Use `createPartitionedRateLimitKeyFactory` for tenant/caller-specific limits.
+ * @example
+ * ```ts
+ * export const placeOrder = pipeline.wrap(
+ *   { name: 'placeOrder', kind: 'command' },
+ *   rateLimit({ keyFactory: perUserKey, points: 1 }),
+ * )(orders.place);
+ *
+ * // The key factory comes from the RateLimitBehavior constructor defaults.
+ * const entry = rateLimit({ inheritModuleKey: true, points: 2 });
+ * ```
+ */
+export declare function rateLimit(options: RateLimitIntentOptions): PipelineBehaviorTuple<RateLimitBehavior, RateLimitBehaviorOptions>;
+//# sourceMappingURL=rate-limit.intent.d.ts.map

package/dist/helpers/rate-limit.intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.intent.d.ts","sourceRoot":"","sources":["../../src/helpers/rate-limit.intent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+CAA+C,CAAC;AAC9F,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,MAAM,MAAM,sBAAsB,GAAG,IAAI,CACvC,wBAAwB,EACxB,YAAY,CACb,GACC,CACI;IACE,UAAU,EAAE,WAAW,CAAC,wBAAwB,CAAC,YAAY,CAAC,CAAC,CAAC;IAChE,gBAAgB,CAAC,EAAE,KAAK,CAAC;CAC1B,GACD;IAAE,gBAAgB,EAAE,IAAI,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,CACjD,CAAC;AAEJ;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,sBAAsB,GAC9B,qBAAqB,CAAC,iBAAiB,EAAE,wBAAwB,CAAC,CAGpE"}

package/dist/helpers/rate-limit.intent.js

@@ -0,0 +1,25 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { RateLimitBehavior } from '../rate-limit.behavior.js';
+/**
+ * Returns a rate-limit behavior entry for `pipeline.wrap()` or `createPipeline({ globalBehaviors })`.
+ * @param options A key factory and rate-limit options, or `inheritModuleKey: true`
+ * when the behavior's constructor defaults supply the key factory. The inheritance marker is not
+ * forwarded to the behavior and does not validate module configuration.
+ * @returns The behavior class and options tuple.
+ * Use `createPartitionedRateLimitKeyFactory` for tenant/caller-specific limits.
+ * @example
+ * ```ts
+ * export const placeOrder = pipeline.wrap(
+ *   { name: 'placeOrder', kind: 'command' },
+ *   rateLimit({ keyFactory: perUserKey, points: 1 }),
+ * )(orders.place);
+ *
+ * // The key factory comes from the RateLimitBehavior constructor defaults.
+ * const entry = rateLimit({ inheritModuleKey: true, points: 2 });
+ * ```
+ */
+export function rateLimit(options) {
+    const { inheritModuleKey: _inheritModuleKey, ...behaviorOptions } = options;
+    return [RateLimitBehavior, behaviorOptions];
+}
+//# sourceMappingURL=rate-limit.intent.js.map

package/dist/helpers/rate-limit.intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.intent.js","sourceRoot":"","sources":["../../src/helpers/rate-limit.intent.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAItE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAc9D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,SAAS,CACvB,OAA+B;IAE/B,MAAM,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,GAAG,eAAe,EAAE,GAAG,OAAO,CAAC;IAC5E,OAAO,CAAC,iBAAiB,EAAE,eAAe,CAAC,CAAC;AAC9C,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,22 @@
+import { RateLimitExceededError } from './errors/rate-limit-exceeded.error.js';
+/** An HTTP answer for an error: status, JSON body and headers. */
+export interface HttpResponse {
+    status: number;
+    body: Record<string, unknown>;
+    headers: Record<string, string>;
+}
+/**
+ * The HTTP answer for a {@link RateLimitExceededError}: `429 Too Many Requests` with a
+ * `Retry-After` header. Framework filters and Express handlers reply with it.
+ *
+ * @example
+ * ```ts
+ * app.use((error, _req, res, next) => {
+ *   if (!(error instanceof RateLimitExceededError)) return next(error);
+ *   const { status, body, headers } = toHttpResponse(error);
+ *   res.status(status).set(headers).json(body);
+ * });
+ * ```
+ */
+export declare function toHttpResponse(error: RateLimitExceededError): HttpResponse;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAE/E,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,sBAAsB,GAAG,YAAY,CAW1E"}

package/dist/http.js

@@ -0,0 +1,27 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * The HTTP answer for a {@link RateLimitExceededError}: `429 Too Many Requests` with a
+ * `Retry-After` header. Framework filters and Express handlers reply with it.
+ *
+ * @example
+ * ```ts
+ * app.use((error, _req, res, next) => {
+ *   if (!(error instanceof RateLimitExceededError)) return next(error);
+ *   const { status, body, headers } = toHttpResponse(error);
+ *   res.status(status).set(headers).json(body);
+ * });
+ * ```
+ */
+export function toHttpResponse(error) {
+    return {
+        status: 429,
+        body: {
+            statusCode: 429,
+            error: 'Too Many Requests',
+            message: error.message,
+            retryAfter: error.retryAfterSeconds,
+        },
+        headers: { 'Retry-After': String(error.retryAfterSeconds) },
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAWtE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAC,KAA6B;IAC1D,OAAO;QACL,MAAM,EAAE,GAAG;QACX,IAAI,EAAE;YACJ,UAAU,EAAE,GAAG;YACf,KAAK,EAAE,mBAAmB;YAC1B,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,UAAU,EAAE,KAAK,CAAC,iBAAiB;SACpC;QACD,OAAO,EAAE,EAAE,aAAa,EAAE,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,EAAE;KAC5D,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Rate limits for wrapped functions and methods: the behavior, key factories and `rateLimit()`. The HTTP mapping of its errors is the `@cqrs-ddd/pipeline-rate-limit/http` entry point.
+ *
+ * @module main
+ */
+export { MissingRateLimitPartitionError, type RateLimitPartitionDimension, } from './errors/missing-partition.error.js';
+export { RateLimitExceededError } from './errors/rate-limit-exceeded.error.js';
+export { buildRateLimitAttributes } from './helpers/build-attributes.js';
+export { buildRateLimitKey } from './helpers/build-key.js';
+export { createPartitionedRateLimitKeyFactory, type PartitionedRateLimitKeyOptions, type RateLimitPartitionFactory, } from './helpers/partitioned-key.js';
+export { type RateLimitIntentOptions, rateLimit, } from './helpers/rate-limit.intent.js';
+export type { RateLimitBehaviorOptions, RateLimitCostFactory, RateLimitKeyFactory, } from './interfaces/rate-limit-options.interface.js';
+export type { RateLimiterLike, RateLimiterResLike, } from './interfaces/rate-limiter.interface.js';
+export { RATE_LIMIT_ITEM, RATE_LIMIT_ITEM_TOKEN, RATE_LIMIT_KEY_ITEM, RATE_LIMIT_KEY_ITEM_TOKEN, RateLimitBehavior, } from './rate-limit.behavior.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,EACL,8BAA8B,EAC9B,KAAK,2BAA2B,GACjC,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EACL,oCAAoC,EACpC,KAAK,8BAA8B,EACnC,KAAK,yBAAyB,GAC/B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,KAAK,sBAAsB,EAC3B,SAAS,GACV,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,wBAAwB,EACxB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,8CAA8C,CAAC;AACtD,YAAY,EACV,eAAe,EACf,kBAAkB,GACnB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * Rate limits for wrapped functions and methods: the behavior, key factories and `rateLimit()`. The HTTP mapping of its errors is the `@cqrs-ddd/pipeline-rate-limit/http` entry point.
+ *
+ * @module main
+ */
+export { MissingRateLimitPartitionError, } from './errors/missing-partition.error.js';
+export { RateLimitExceededError } from './errors/rate-limit-exceeded.error.js';
+export { buildRateLimitAttributes } from './helpers/build-attributes.js';
+export { buildRateLimitKey } from './helpers/build-key.js';
+export { createPartitionedRateLimitKeyFactory, } from './helpers/partitioned-key.js';
+export { rateLimit, } from './helpers/rate-limit.intent.js';
+export { RATE_LIMIT_ITEM, RATE_LIMIT_ITEM_TOKEN, RATE_LIMIT_KEY_ITEM, RATE_LIMIT_KEY_ITEM_TOKEN, RateLimitBehavior, } from './rate-limit.behavior.js';
+//# sourceMappingURL=index.js.map