stratal 0.0.27 → 0.1.0

package/dist/rate-limiter/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/rate-limiter/errors.ts","../../src/rate-limiter/limit.ts","../../src/rate-limiter/rate-limiter-registry.ts","../../src/rate-limiter/stores/rate-limiter-store.interface.ts","../../src/rate-limiter/stores/store-factory.ts","../../src/rate-limiter/rate-limiter.module.ts","../../src/rate-limiter/rate-limiter.tokens.ts","../../src/rate-limiter/throttle.middleware.ts","../../src/rate-limiter/decorators/rate-limit.decorator.ts","../../src/rate-limiter/stores/kv-store.ts","../../src/rate-limiter/stores/memory-store.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/rate-limiter/errors.ts","../../src/rate-limiter/limit.ts","../../src/rate-limiter/rate-limiter-registry.ts","../../src/rate-limiter/stores/rate-limiter-store.interface.ts","../../src/rate-limiter/stores/store-factory.ts","../../src/rate-limiter/rate-limiter.module.ts","../../src/rate-limiter/rate-limiter.tokens.ts","../../src/rate-limiter/throttle.middleware.ts","../../src/rate-limiter/decorators/rate-limit.decorator.ts","../../src/rate-limiter/stores/kv-store.ts","../../src/rate-limiter/stores/memory-store.ts"],"mappings":";;;;;;;;;;;;;;;;qBAYa,6BAA6B;WAEtB;IAAQ;IAAoB;IAAe;;EAD7D,YACkB;IAAQ;IAAoB;IAAe;;;qBAMlD,yBAAyB;;;;;;;UCdrB;EACf;EACA;EACA;EACA;;;;;;;;KAsBU,4BACV,KAAK,eACL,SAAS,qBACN,WAAW,QAAQ;;;;;;;;;;;;;;;;;;qBAmBX;WAMO;WACA;WACA;UAPV;UACA;UACA;UAED;SAMA,UAAU,cAAc;SAIxB,WAAW,iBAAiB,cAAc;SAI1C,UAAU,cAAc;SAIxB,WAAW,iBAAiB,cAAc;SAI1C,QAAQ,cAAc;SAItB,OAAO,cAAc;;SAKrB,QAAQ;;EAKf,GAAG;;;;;;EAUH,SAAS,SAAS;;;;;;;;;;;;;;;;;;;;;EAyBlB,WAAW;MAKP;MAIA,kBAAkB;MAIlB;;;;;;;;;KChIM,iBACV,KAAK,kBACF,QAAQ,UAAU,QAAQ,QAAQ;;;;;;;;;;;;;;;;;;;;qBAuC1B,4BAA4B;mBAIS;mBAH/B;EAEjB,YACgD,WAAW;;;;;;;cAW/C;;;;;;EASZ,IAAI,cAAc,UAAU;EAI5B,IAAI;;;;;;;;;EAYE,OAAO,cAAc,KAAK,eAAe,MAAM,OAAO,QAAQ;;;;;UAyEtD;;;;;;;;;;;;;;;;;;;;UAmCA;;;;;;UAqCN;UAUA;;;;;;;;;;;UCpPO;;EAEf;;EAEA;;;;;;;;;;;;;;UAee;;;;;EAKf,IAAI,aAAa,cAAc,QAAQ;;;;;;EAOvC,IAAI,aAAa,aAAa,OAAO,GAAG,qBAAqB;;;;EAK7D,OAAO,cAAc;;;;;;;;;;;;;KCpBX;EACN;EAAa,eAAe;;EAC5B;;EACA;IAAS,UAAU,YAAY;;;qBAOxB;mBAEyC;mBACE;mBACV;mBAEzB;EALnB,YACoD,KAAK,YACH,OAAO,cACjB,WAAW,WAEpC,UAAU;EAG7B,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBCIC,6BAA6B,cAAc;;;;;;SAM/C,QAAQ,SAAS,2BAA2B;;;;;SAa5C,aAAa,SAAS,mBAAmB,4BAA4B;;;;;;;;;EAqB5E,eAAe,aAAa;;;;;;;EAW5B,YAAY,SAAS;;;;qBCjGV;WACX;WACA;WACA;WACA;;;;;WAKA;;KAGU,2BAA2B,kCAAkC;;;;;;;;;;;;wBCSzD,yBAAyB,eAAe,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBCUpD,UAAU,eAAe,iBAAiB;;;;;;;;wBAmB1C,cAAc,gBAAgB;;;;;;;;;;;;;;;qBCnCjC,8BAA8B;mBACZ;EAA7B,YAA6B,OAAO;EAE9B,IAAI,GAAG,cAAc,QAAQ;EAI7B,IAAI,GAAG,aAAa,OAAO,GAAG,qBAAqB;EAOnD,OAAO,cAAc;;;;;;;;;;;;;qBCbhB,oCAAoC;mBAC9B;EAEjB,IAAI,GAAG,cAAc,QAAQ;EAU7B,IAAI,GAAG,aAAa,OAAO,GAAG,qBAAqB;EAKnD,OAAO,cAAc"}

package/dist/rate-limiter/index.mjs

@@ -1,84 +1,11 @@
-import { l as Singleton, n as CONTAINER_TOKEN, p as inject, r as DI_TOKENS } from "../di-D7qmrAir.mjs";
-import { n as __decorateParam, t as __decorate } from "../decorate-CuAoSZvs.mjs";
+import { l as Singleton, n as CONTAINER_TOKEN, p as inject, r as DI_TOKENS } from "../di-DQ3xbjgf.mjs";
+import { n as __decorateParam, t as __decorate } from "../decorate-C79yt3Wt.mjs";
 import { t as Macroable } from "../macroable-cvDTFZ_A.mjs";
-import { n as Module } from "../module.decorator-CYHY6pG5.mjs";
-import { c as RATE_LIMITER_TOKENS, l as RateLimiterError, s as createThrottleMiddleware, u as TooManyRequestsError } from "../module-registry-NxX5O0Qk.mjs";
-import "../module/index.mjs";
+import { n as Module } from "../module.decorator-CYbrOlX9.mjs";
+import { c as RATE_LIMITER_TOKENS, l as RateLimiterError, s as createThrottleMiddleware, u as TooManyRequestsError } from "../module-registry-lkQPDuQe.mjs";
 import { CACHE_TOKENS, CacheModule } from "../cache/index.mjs";
-import { n as getRateLimits, t as RateLimit } from "../rate-limit.decorator-Djs4oYDB.mjs";
-//#region src/rate-limiter/limit.ts
-/**
-* A single rate limit window.
-*
-* Build via the static factories (`perSecond`, `perMinute`, `perMinutes`,
-* `perHour`, `perDay`, `none`). Chain `.by(key)` to scope per-actor and
-* `.response(handler)` to override the default 429 response.
-*
-* Returned (singly or as an array) by limiter resolvers registered via
-* `RateLimiterRegistry.for()`.
-*
-* @example
-* ```typescript
-* Limit.perMinute(60).by(ctx.header('cf-connecting-ip') ?? 'global')
-* Limit.perHour(100).by(userId)
-* Limit.none()                                // bypass
-* ```
-*/
-var Limit = class Limit {
-	windowSeconds;
-	max;
-	disabled;
-	_key;
-	_customResponse;
-	constructor(windowSeconds, max, disabled = false) {
-		this.windowSeconds = windowSeconds;
-		this.max = max;
-		this.disabled = disabled;
-	}
-	static perSecond(max) {
-		return new Limit(1, max);
-	}
-	static perSeconds(seconds, max) {
-		return new Limit(seconds, max);
-	}
-	static perMinute(max) {
-		return new Limit(60, max);
-	}
-	static perMinutes(minutes, max) {
-		return new Limit(minutes * 60, max);
-	}
-	static perHour(max) {
-		return new Limit(3600, max);
-	}
-	static perDay(max) {
-		return new Limit(1440 * 60, max);
-	}
-	/** Bypass the limiter entirely for this request. */
-	static none() {
-		return new Limit(0, 0, true);
-	}
-	/** Scope this limit to a specific actor (user id, IP, tenant, etc.). */
-	by(key) {
-		this._key = String(key);
-		return this;
-	}
-	/**
-	* Override the default 429 response. The handler receives the standard
-	* `RateLimitHeaders` so it can spread them onto its own Response or omit
-	* them as it sees fit.
-	*/
-	response(handler) {
-		this._customResponse = handler;
-		return this;
-	}
-	get key() {
-		return this._key;
-	}
-	get customResponse() {
-		return this._customResponse;
-	}
-};
-//#endregion
+import { t as Limit } from "../limit-BE0HNAF6.mjs";
+import { n as getRateLimits, t as RateLimit } from "../rate-limit.decorator-PYQ9EYqs.mjs";
 //#region src/rate-limiter/rate-limiter-registry.ts
 let RateLimiterRegistry = class RateLimiterRegistry extends Macroable {
 	container;
@@ -124,8 +51,8 @@ let RateLimiterRegistry = class RateLimiterRegistry extends Macroable {
 		let mostRestrictive;
 		let exceeded;
 		for (const limit of active) {
-			const key = this.makeKey(name, limit.windowSeconds, limit.key);
-			const hit = await this.hit(key, limit.windowSeconds);
+			const key = this.makeKey(name, limit.windowSeconds, limit.key, limit.distinctValue !== void 0);
+			const hit = limit.distinctValue === void 0 ? await this.hit(key, limit.windowSeconds) : await this.hitDistinct(key, limit.windowSeconds, limit.distinctValue, limit.max);
 			if (hit.count > limit.max) {
 				if (!exceeded || hit.resetAt > exceeded.resetAt) exceeded = {
 					limit,
@@ -178,8 +105,65 @@ let RateLimiterRegistry = class RateLimiterRegistry extends Macroable {
 		await this.store.set(key, next, ttlSeconds);
 		return next;
 	}
-	makeKey(name, windowSeconds, by) {
-		return `rl:${name}:${windowSeconds}:${by ?? "*"}`;
+	/**
+	* A window that counts DISTINCT values rather than requests.
+	*
+	* Uses the same typed-KV store as {@link hit} — the store persists arbitrary values, so a
+	* cardinality window needs no store-interface change — but a key namespace of its own, since
+	* the two shapes are not interchangeable and a shared key would have each read the other's.
+	*
+	* A value already present is admitted WITHOUT a write, which both keeps the count stable and
+	* leaves the TTL alone: re-touching something already counted must not slide the window. The
+	* stored set therefore never exceeds `max`.
+	*
+	* The cap is a SOFT ceiling under an eventually-consistent store. This is a read-modify-write
+	* of the whole array, so N concurrent requests carrying N different values all read the same
+	* set and last-write-wins keeps one of them: a burst can overshoot `max`, and unlike a lost
+	* counter increment (which the next request re-adds) a lost set member is gone for the rest of
+	* the window. Intended for small caps — tens, not thousands; nothing bounds `max` itself, and
+	* the whole set is read and rewritten on every new value. A hard cap needs a
+	* strongly-consistent store, i.e. a Durable Object.
+	*/
+	async hitDistinct(key, windowSeconds, value, max) {
+		const now = Date.now();
+		const existing = await this.store.get(key);
+		if (existing && existing.resetAt > now) {
+			if (existing.values.includes(value)) return {
+				count: existing.values.length,
+				resetAt: existing.resetAt
+			};
+			if (existing.values.length >= max) return {
+				count: existing.values.length + 1,
+				resetAt: existing.resetAt
+			};
+			const values = [...existing.values, value];
+			const ttlSeconds = Math.max(1, Math.ceil((existing.resetAt - now) / 1e3));
+			await this.store.set(key, {
+				values,
+				resetAt: existing.resetAt
+			}, ttlSeconds);
+			return {
+				count: values.length,
+				resetAt: existing.resetAt
+			};
+		}
+		const resetAt = now + windowSeconds * 1e3;
+		await this.store.set(key, {
+			values: [value],
+			resetAt
+		}, Math.max(1, windowSeconds));
+		return {
+			count: 1,
+			resetAt
+		};
+	}
+	/**
+	* Distinct windows carry a `d:` segment: they store `StoredDistinct` where a plain window
+	* stores `StoredHit`, and one limiter name can legitimately declare both on the same window
+	* and actor. Sharing a key would have each branch read the other's shape and throw.
+	*/
+	makeKey(name, windowSeconds, by, distinct) {
+		return `rl:${name}:${distinct ? "d:" : ""}${windowSeconds}:${by ?? "*"}`;
 	}
 	makeHeaders(limit, remaining, resetAt) {
 		const retryAfter = Math.max(1, Math.ceil((resetAt - Date.now()) / 1e3));

package/dist/rate-limiter/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/rate-limiter/limit.ts","../../src/rate-limiter/rate-limiter-registry.ts","../../src/rate-limiter/stores/kv-store.ts","../../src/rate-limiter/stores/memory-store.ts","../../src/rate-limiter/stores/store-factory.ts","../../src/rate-limiter/rate-limiter.module.ts"],"sourcesContent":["import type { RouterContext } from '../router/router-context'\n\n/**\n * Standard rate-limit response headers passed to custom response handlers.\n * Keys are canonical HTTP header names; values are the stringified counts.\n */\nexport interface RateLimitHeaders {\n  'Retry-After': string\n  'X-RateLimit-Limit': string\n  'X-RateLimit-Remaining': string\n  'X-RateLimit-Reset': string\n}\n\n/**\n * Custom response handler invoked when a limit is exceeded and the user\n * supplied `.response()` on the {@link Limit}. Receives the request context\n * and the precomputed standard headers (which the handler can spread, drop,\n * or override).\n */\nexport type RateLimitResponseHandler = (\n  ctx: RouterContext,\n  headers: RateLimitHeaders,\n) => Response | Promise<Response>\n\n/**\n * A single rate limit window.\n *\n * Build via the static factories (`perSecond`, `perMinute`, `perMinutes`,\n * `perHour`, `perDay`, `none`). Chain `.by(key)` to scope per-actor and\n * `.response(handler)` to override the default 429 response.\n *\n * Returned (singly or as an array) by limiter resolvers registered via\n * `RateLimiterRegistry.for()`.\n *\n * @example\n * ```typescript\n * Limit.perMinute(60).by(ctx.header('cf-connecting-ip') ?? 'global')\n * Limit.perHour(100).by(userId)\n * Limit.none()                                // bypass\n * ```\n */\nexport class Limit {\n  private _key?: string\n  private _customResponse?: RateLimitResponseHandler\n\n  private constructor(\n    public readonly windowSeconds: number,\n    public readonly max: number,\n    public readonly disabled = false,\n  ) {}\n\n  static perSecond(max: number): Limit {\n    return new Limit(1, max)\n  }\n\n  static perSeconds(seconds: number, max: number): Limit {\n    return new Limit(seconds, max)\n  }\n\n  static perMinute(max: number): Limit {\n    return new Limit(60, max)\n  }\n\n  static perMinutes(minutes: number, max: number): Limit {\n    return new Limit(minutes * 60, max)\n  }\n\n  static perHour(max: number): Limit {\n    return new Limit(60 * 60, max)\n  }\n\n  static perDay(max: number): Limit {\n    return new Limit(24 * 60 * 60, max)\n  }\n\n  /** Bypass the limiter entirely for this request. */\n  static none(): Limit {\n    return new Limit(0, 0, true)\n  }\n\n  /** Scope this limit to a specific actor (user id, IP, tenant, etc.). */\n  by(key: string | number): this {\n    this._key = String(key)\n    return this\n  }\n\n  /**\n   * Override the default 429 response. The handler receives the standard\n   * `RateLimitHeaders` so it can spread them onto its own Response or omit\n   * them as it sees fit.\n   */\n  response(handler: RateLimitResponseHandler): this {\n    this._customResponse = handler\n    return this\n  }\n\n  get key(): string | undefined {\n    return this._key\n  }\n\n  get customResponse(): RateLimitResponseHandler | undefined {\n    return this._customResponse\n  }\n}\n","import { type Container, DI_TOKENS, inject } from '../di'\nimport { Singleton } from '../di/decorators'\nimport { Macroable } from '../macroable'\nimport type { Next } from '../router/middleware.interface'\nimport type { RouterContext } from '../router/router-context'\nimport { RateLimiterError, TooManyRequestsError } from './errors'\nimport type { Limit, RateLimitHeaders } from './limit'\nimport { RATE_LIMITER_TOKENS } from './rate-limiter.tokens'\nimport type { IRateLimiterStore, RateLimitHit } from './stores/rate-limiter-store.interface'\n\n/**\n * Resolver function registered via {@link RateLimiterRegistry.for}. Receives\n * the request context and returns the limit (or limits) that apply to this\n * request. Return `Limit.none()` to bypass for the current request.\n */\nexport type LimitResolver = (\n  ctx: RouterContext,\n) => Limit | Limit[] | Promise<Limit | Limit[]>\n\ninterface StoredHit {\n  count: number\n  resetAt: number\n}\n\n/**\n * Central registry of named rate limiters and the request-time enforcement\n * pipeline. Resolved as a singleton; consumed by `ThrottleMiddleware`.\n *\n * Register limiters in a module's `onInitialize` hook:\n * ```typescript\n * @Module({})\n * export class RateLimitsModule implements OnInitialize {\n *   onInitialize({ container }: ModuleContext): void {\n *     const limiter = container.resolve<RateLimiterRegistry>(RATE_LIMITER_TOKENS.Registry)\n *     limiter.for('api', (ctx) => Limit.perMinute(60).by(ctx.header('cf-connecting-ip') ?? '*'))\n *   }\n * }\n * ```\n *\n * Extensible via `Macroable`: adapter packages (e.g. `@stratal/framework/auth`)\n * can attach extra registration methods such as `forPath()` for better-auth\n * `customRules` interop.\n */\n// IMPORTANT: do not pass a token to @Singleton — that would self-register\n// the class globally at module-load time, making the Registry resolvable\n// even when the user never imported RateLimiterModule. We rely on\n// RateLimiterModule providers being the only binding source, so\n// `{ isOptional: true }` in ThrottleMiddleware correctly returns undefined\n// when the module is missing.\n@Singleton()\nexport class RateLimiterRegistry extends Macroable {\n  private readonly resolvers = new Map<string, LimitResolver>()\n\n  constructor(\n    @inject(DI_TOKENS.Container) private readonly container: Container,\n  ) {\n    super()\n  }\n\n  /**\n   * Resolve the store per access instead of capturing it at construction.\n   * The registry is a singleton built during module init; lazy resolution\n   * keeps later `RATE_LIMITER_TOKENS.Store` overrides (e.g. the testing\n   * harness disabling limits) effective.\n   */\n  private get store(): IRateLimiterStore {\n    return this.container.resolve<IRateLimiterStore>(RATE_LIMITER_TOKENS.Store)\n  }\n\n  /**\n   * Register a named limiter. Names must be unique; calling `for()` again\n   * with the same name overwrites the previous resolver (matches Laravel\n   * `RateLimiter::for` semantics — last definition wins).\n   */\n  for(name: string, resolver: LimitResolver): void {\n    this.resolvers.set(name, resolver)\n  }\n\n  has(name: string): boolean {\n    return this.resolvers.has(name)\n  }\n\n  /**\n   * Enforce the named limiter for the current request. Called by\n   * `ThrottleMiddleware` (the per-name class produced by\n   * `createThrottleMiddleware`). Resolves the limiter, increments the store\n   * for each non-bypassed limit, sets `X-RateLimit-*` headers on success, and\n   * either invokes the limit's custom `.response()` or throws\n   * {@link TooManyRequestsError} when a limit is exceeded.\n   */\n  async handle(name: string, ctx: RouterContext, next: Next): Promise<Response | void> {\n    const resolver = this.resolvers.get(name)\n    if (!resolver) {\n      throw new RateLimiterError(`Rate limiter \"${name}\" is not defined. Register it with limiter.for(\"${name}\", ...) in a module's onInitialize hook.`)\n    }\n\n    const resolved = await resolver(ctx)\n    const limits = Array.isArray(resolved) ? resolved : [resolved]\n    const active = limits.filter((l) => !l.disabled)\n\n    if (active.length === 0) {\n      return next()\n    }\n\n    let mostRestrictive: { limit: Limit; remaining: number; resetAt: number } | undefined\n    let exceeded: { limit: Limit; resetAt: number } | undefined\n\n    for (const limit of active) {\n      const key = this.makeKey(name, limit.windowSeconds, limit.key)\n      const hit = await this.hit(key, limit.windowSeconds)\n\n      if (hit.count > limit.max) {\n        if (!exceeded || hit.resetAt > exceeded.resetAt) {\n          exceeded = { limit, resetAt: hit.resetAt }\n        }\n        continue\n      }\n\n      const remaining = limit.max - hit.count\n      if (!mostRestrictive || remaining < mostRestrictive.remaining) {\n        mostRestrictive = { limit, remaining, resetAt: hit.resetAt }\n      }\n    }\n\n    if (exceeded) {\n      const headers = this.makeHeaders(exceeded.limit.max, 0, exceeded.resetAt)\n      if (exceeded.limit.customResponse) {\n        return exceeded.limit.customResponse(ctx, headers)\n      }\n      throw new TooManyRequestsError({\n        retryAfter: Number(headers['Retry-After']),\n        limit: exceeded.limit.max,\n        resetAt: exceeded.resetAt,\n      })\n    }\n\n    await next()\n\n    if (mostRestrictive) {\n      const headers = this.makeHeaders(\n        mostRestrictive.limit.max,\n        mostRestrictive.remaining,\n        mostRestrictive.resetAt,\n      )\n      // Hono populates ctx.c.res after next() — same pattern as logger.middleware.ts.\n      const downstream = ctx.c.res\n      downstream.headers.set('X-RateLimit-Limit', headers['X-RateLimit-Limit'])\n      downstream.headers.set('X-RateLimit-Remaining', headers['X-RateLimit-Remaining'])\n      downstream.headers.set('X-RateLimit-Reset', headers['X-RateLimit-Reset'])\n    }\n  }\n\n  /**\n   * Get-modify-set increment over the typed KV store. Not atomic across\n   * concurrent edge requests on KV — see `KvRateLimiterStore`'s caveat.\n   */\n  private async hit(key: string, windowSeconds: number): Promise<RateLimitHit> {\n    const now = Date.now()\n    const existing = await this.store.get<StoredHit>(key)\n\n    let next: StoredHit\n    if (!existing || existing.resetAt <= now) {\n      next = { count: 1, resetAt: now + windowSeconds * 1000 }\n    } else {\n      next = { count: existing.count + 1, resetAt: existing.resetAt }\n    }\n\n    const ttlSeconds = Math.max(1, Math.ceil((next.resetAt - now) / 1000))\n    await this.store.set(key, next, ttlSeconds)\n    return next\n  }\n\n  private makeKey(name: string, windowSeconds: number, by: string | undefined): string {\n    const actor = by ?? '*'\n    return `rl:${name}:${windowSeconds}:${actor}`\n  }\n\n  private makeHeaders(limit: number, remaining: number, resetAt: number): RateLimitHeaders {\n    const retryAfter = Math.max(1, Math.ceil((resetAt - Date.now()) / 1000))\n    return {\n      'Retry-After': String(retryAfter),\n      'X-RateLimit-Limit': String(limit),\n      'X-RateLimit-Remaining': String(Math.max(0, remaining)),\n      'X-RateLimit-Reset': String(Math.ceil(resetAt / 1000)),\n    }\n  }\n}\n","import type { CacheService } from '../../cache/services/cache.service'\nimport type { IRateLimiterStore } from './rate-limiter-store.interface'\n\n/**\n * Cloudflare KV-backed typed KV store.\n *\n * KV's minimum `expirationTtl` is 60 seconds; sub-60s windows are still\n * enforced by the registry's algorithm via the persisted `resetAt`, but\n * the key itself may live in KV longer than the logical window.\n *\n * KV has no native atomic increment, so concurrent writes from different\n * edge locations may undercount under high contention. That's an inherent\n * KV tradeoff — pick `{ useClass: MyDurableObjectStore }` for strict\n * accuracy across edges.\n */\nexport class KvRateLimiterStore implements IRateLimiterStore {\n  constructor(private readonly cache: CacheService) {}\n\n  async get<T>(key: string): Promise<T | null> {\n    return (await this.cache.get<T>(key, 'json')) ?? null\n  }\n\n  async set<T>(key: string, value: T, ttlSeconds: number): Promise<void> {\n    const ttl = Math.max(60, Math.ceil(ttlSeconds))\n    await this.cache.put(key, JSON.stringify(value), { expirationTtl: ttl })\n  }\n\n  async delete(key: string): Promise<void> {\n    await this.cache.delete(key)\n  }\n}\n","import type { IRateLimiterStore } from './rate-limiter-store.interface'\n\ninterface Entry {\n  value: unknown\n  expiresAt: number\n}\n\n/**\n * In-process Map-backed typed KV store.\n *\n * Suitable for tests and single-isolate scenarios. Not safe across\n * Cloudflare Worker isolates — entries reset whenever a fresh isolate\n * spins up. Use `KvRateLimiterStore` (or a custom Durable Object store)\n * for production. Expiry is lazy: stale entries are dropped on the next\n * `get`.\n */\nexport class InMemoryRateLimiterStore implements IRateLimiterStore {\n  private readonly entries = new Map<string, Entry>()\n\n  get<T>(key: string): Promise<T | null> {\n    const entry = this.entries.get(key)\n    if (!entry) return Promise.resolve(null)\n    if (entry.expiresAt <= Date.now()) {\n      this.entries.delete(key)\n      return Promise.resolve(null)\n    }\n    return Promise.resolve(entry.value as T)\n  }\n\n  set<T>(key: string, value: T, ttlSeconds: number): Promise<void> {\n    this.entries.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000 })\n    return Promise.resolve()\n  }\n\n  delete(key: string): Promise<void> {\n    this.entries.delete(key)\n    return Promise.resolve()\n  }\n}\n","import { inject } from '../../di'\nimport { CACHE_TOKENS } from '../../cache/cache.tokens'\nimport type { CacheService } from '../../cache/services/cache.service'\nimport { CONTAINER_TOKEN, type Container } from '../../di'\nimport { Singleton } from '../../di/decorators'\nimport { DI_TOKENS } from '../../di/tokens'\nimport type { StratalEnv } from '../../env'\nimport type { Constructor } from '../../types'\nimport { RateLimiterError } from '../errors'\nimport { RATE_LIMITER_TOKENS } from '../rate-limiter.tokens'\nimport { KvRateLimiterStore } from './kv-store'\nimport { InMemoryRateLimiterStore } from './memory-store'\nimport type { IRateLimiterStore } from './rate-limiter-store.interface'\n\n/**\n * Configuration for `RateLimiterModule.forRoot()`. Picks the backing store.\n *\n * - `'kv'`: Cloudflare KV. `binding` names the KVNamespace on `StratalEnv`.\n * - `'memory'`: in-process Map. Tests / single-isolate only.\n * - `{ useClass }`: any class implementing `IRateLimiterStore`. Resolved\n *   from the DI container (so the class can declare its own `@inject` deps,\n *   e.g. a Durable Object namespace from `StratalEnv`).\n */\nexport type RateLimiterModuleOptions =\n  | { store: 'kv'; binding: keyof StratalEnv }\n  | { store: 'memory' }\n  | { store: { useClass: Constructor<IRateLimiterStore> } }\n\n// IMPORTANT: see RateLimiterRegistry — no token on @Singleton so the\n// factory isn't globally bound at class-load time. Module providers are\n// the sole binding source, which keeps the \"module not imported\" detection\n// in ThrottleMiddleware working.\n@Singleton()\nexport class RateLimiterStoreFactory {\n  constructor(\n    @inject(DI_TOKENS.CloudflareEnv) private readonly env: StratalEnv,\n    @inject(CACHE_TOKENS.CacheService) private readonly cache: CacheService,\n    @inject(CONTAINER_TOKEN) private readonly container: Container,\n    @inject(RATE_LIMITER_TOKENS.Options, { isOptional: true })\n    private readonly options?: RateLimiterModuleOptions,\n  ) {}\n\n  create(): IRateLimiterStore {\n    if (!this.options) {\n      throw new RateLimiterError('RateLimiterModule is not configured. Call RateLimiterModule.forRoot({ store: ... }) to configure a backing store.')\n    }\n\n    const { store } = this.options\n\n    if (store === 'memory') {\n      return new InMemoryRateLimiterStore()\n    }\n\n    if (store === 'kv') {\n      const binding = this.env[this.options.binding] as KVNamespace | undefined\n      if (!binding) {\n        throw new RateLimiterError(`KV binding \"${String(this.options.binding)}\" is not available in the environment.`)\n      }\n      return new KvRateLimiterStore(this.cache.withBinding(binding))\n    }\n\n    return this.container.resolve<IRateLimiterStore>(store.useClass)\n  }\n}\n","import { CacheModule } from '../cache'\nimport type { ExceptionHandler } from '../errors/exception-handler'\nimport { Module } from '../module'\nimport type { AsyncModuleOptions, DynamicModule, ModuleContext, OnException, OnInitialize } from '../module/types'\nimport { TooManyRequestsError } from './errors'\nimport { RateLimiterRegistry } from './rate-limiter-registry'\nimport { RATE_LIMITER_TOKENS } from './rate-limiter.tokens'\nimport { RateLimiterStoreFactory, type RateLimiterModuleOptions } from './stores/store-factory'\nimport type { IRateLimiterStore } from './stores/rate-limiter-store.interface'\n\n/**\n * Rate limiter module — opt-in, NOT registered automatically by Application.\n *\n * Usage:\n * ```typescript\n * @Module({\n *   imports: [RateLimiterModule.forRoot({ store: 'kv', binding: 'RATE_LIMITS' })],\n * })\n * export class AppModule {}\n * ```\n *\n * Define limiters in any module's `onInitialize` hook by resolving\n * `RATE_LIMITER_TOKENS.Registry` from the container. Apply them with\n * `router.throttle('name')` or `@RateLimit('name')`.\n *\n * The module:\n *  - eagerly validates the store at app boot (`onInitialize` resolves the\n *    factory and calls `create()`); a missing `forRoot` surfaces\n *    `RateLimiterError` before any request is served.\n *  - registers a `respond()` callback on the `ExceptionHandler` (via\n *    `onException`) that injects `Retry-After` and `X-RateLimit-*` headers\n *    on every {@link TooManyRequestsError} response, regardless of whether\n *    the body was rendered as JSON, HTML, or via Inertia.\n */\n@Module({\n  imports: [CacheModule],\n  providers: [\n    { provide: RATE_LIMITER_TOKENS.Registry, useClass: RateLimiterRegistry },\n    { provide: RATE_LIMITER_TOKENS.StoreFactory, useClass: RateLimiterStoreFactory },\n    {\n      provide: RATE_LIMITER_TOKENS.Store,\n      useFactory: (factory: RateLimiterStoreFactory) => factory.create(),\n      inject: [RATE_LIMITER_TOKENS.StoreFactory],\n    },\n  ],\n})\nexport class RateLimiterModule implements OnInitialize, OnException {\n  /**\n   * Configure the rate limiter with a store choice.\n   *\n   * @param options - `{ store: 'kv', binding }` | `{ store: 'memory' }` | `{ store: { useClass } }`\n   */\n  static forRoot(options: RateLimiterModuleOptions): DynamicModule {\n    return {\n      module: RateLimiterModule,\n      providers: [\n        { provide: RATE_LIMITER_TOKENS.Options, useValue: options },\n      ],\n    }\n  }\n\n  /**\n   * Async configuration. Use when store options depend on other services\n   * (e.g. ConfigService).\n   */\n  static forRootAsync(options: AsyncModuleOptions<RateLimiterModuleOptions>): DynamicModule {\n    return {\n      module: RateLimiterModule,\n      providers: [\n        {\n          provide: RATE_LIMITER_TOKENS.Options,\n          useFactory: options.useFactory,\n          inject: options.inject,\n        },\n      ],\n    }\n  }\n\n  /**\n   * Eagerly resolve the store so a missing `forRoot()` fails at boot,\n   * not on the first throttled request. Also registers a per-app marker\n   * value so ThrottleMiddleware can distinguish \"module imported into this\n   * app\" from \"module class loaded somewhere in the process\" (the latter is\n   * indistinguishable at the DI layer because @Module's `registry()` call\n   * binds providers globally at decoration time).\n   */\n  onInitialize({ container }: ModuleContext): void {\n    container.resolve<IRateLimiterStore>(RATE_LIMITER_TOKENS.Store)\n    container.registerValue(RATE_LIMITER_TOKENS.ModuleMarker, { imported: true })\n  }\n\n  /**\n   * Inject `Retry-After` + `X-RateLimit-*` headers on every 429 response.\n   * The body itself is rendered by `ExceptionHandler.defaultRender` —\n   * content-negotiated, so HTML clients (browsers, Inertia) and JSON\n   * clients both get the right shape.\n   */\n  onException(handler: ExceptionHandler): void {\n    handler.dontReport([TooManyRequestsError])\n    handler.respond((response, error) => {\n      if (!(error instanceof TooManyRequestsError)) return response\n      response.headers.set('Retry-After', String(error.info.retryAfter))\n      response.headers.set('X-RateLimit-Limit', String(error.info.limit))\n      response.headers.set('X-RateLimit-Remaining', '0')\n      response.headers.set('X-RateLimit-Reset', String(Math.ceil(error.info.resetAt / 1000)))\n      return response\n    })\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/rate-limiter/rate-limiter-registry.ts","../../src/rate-limiter/stores/kv-store.ts","../../src/rate-limiter/stores/memory-store.ts","../../src/rate-limiter/stores/store-factory.ts","../../src/rate-limiter/rate-limiter.module.ts"],"sourcesContent":["import { type Container, DI_TOKENS, inject } from '../di'\nimport { Singleton } from '../di/decorators'\nimport { Macroable } from '../macroable'\nimport type { Next } from '../router/middleware.interface'\nimport type { RouterContext } from '../router/router-context'\nimport { RateLimiterError, TooManyRequestsError } from './errors'\nimport type { Limit, RateLimitHeaders } from './limit'\nimport { RATE_LIMITER_TOKENS } from './rate-limiter.tokens'\nimport type { IRateLimiterStore, RateLimitHit } from './stores/rate-limiter-store.interface'\n\n/**\n * Resolver function registered via {@link RateLimiterRegistry.for}. Receives\n * the request context and returns the limit (or limits) that apply to this\n * request. Return `Limit.none()` to bypass for the current request.\n */\nexport type LimitResolver = (\n  ctx: RouterContext,\n) => Limit | Limit[] | Promise<Limit | Limit[]>\n\ninterface StoredHit {\n  count: number\n  resetAt: number\n}\n\n/** What a distinct-value window stores, in place of `StoredHit`'s counter. */\ninterface StoredDistinct {\n  values: string[]\n  resetAt: number\n}\n\n/**\n * Central registry of named rate limiters and the request-time enforcement\n * pipeline. Resolved as a singleton; consumed by `ThrottleMiddleware`.\n *\n * Register limiters in a module's `onInitialize` hook:\n * ```typescript\n * @Module({})\n * export class RateLimitsModule implements OnInitialize {\n *   onInitialize({ container }: ModuleContext): void {\n *     const limiter = container.resolve<RateLimiterRegistry>(RATE_LIMITER_TOKENS.Registry)\n *     limiter.for('api', (ctx) => Limit.perMinute(60).by(ctx.header('cf-connecting-ip') ?? '*'))\n *   }\n * }\n * ```\n *\n * Extensible via `Macroable`: adapter packages (e.g. `@stratal/framework/auth`)\n * can attach extra registration methods such as `forPath()` for better-auth\n * `customRules` interop.\n */\n// IMPORTANT: do not pass a token to @Singleton — that would self-register\n// the class globally at module-load time, making the Registry resolvable\n// even when the user never imported RateLimiterModule. We rely on\n// RateLimiterModule providers being the only binding source, so\n// `{ isOptional: true }` in ThrottleMiddleware correctly returns undefined\n// when the module is missing.\n@Singleton()\nexport class RateLimiterRegistry extends Macroable {\n  private readonly resolvers = new Map<string, LimitResolver>()\n\n  constructor(\n    @inject(DI_TOKENS.Container) private readonly container: Container,\n  ) {\n    super()\n  }\n\n  /**\n   * Resolve the store per access instead of capturing it at construction.\n   * The registry is a singleton built during module init; lazy resolution\n   * keeps later `RATE_LIMITER_TOKENS.Store` overrides (e.g. the testing\n   * harness disabling limits) effective.\n   */\n  private get store(): IRateLimiterStore {\n    return this.container.resolve<IRateLimiterStore>(RATE_LIMITER_TOKENS.Store)\n  }\n\n  /**\n   * Register a named limiter. Names must be unique; calling `for()` again\n   * with the same name overwrites the previous resolver (matches Laravel\n   * `RateLimiter::for` semantics — last definition wins).\n   */\n  for(name: string, resolver: LimitResolver): void {\n    this.resolvers.set(name, resolver)\n  }\n\n  has(name: string): boolean {\n    return this.resolvers.has(name)\n  }\n\n  /**\n   * Enforce the named limiter for the current request. Called by\n   * `ThrottleMiddleware` (the per-name class produced by\n   * `createThrottleMiddleware`). Resolves the limiter, increments the store\n   * for each non-bypassed limit, sets `X-RateLimit-*` headers on success, and\n   * either invokes the limit's custom `.response()` or throws\n   * {@link TooManyRequestsError} when a limit is exceeded.\n   */\n  async handle(name: string, ctx: RouterContext, next: Next): Promise<Response | void> {\n    const resolver = this.resolvers.get(name)\n    if (!resolver) {\n      throw new RateLimiterError(`Rate limiter \"${name}\" is not defined. Register it with limiter.for(\"${name}\", ...) in a module's onInitialize hook.`)\n    }\n\n    const resolved = await resolver(ctx)\n    const limits = Array.isArray(resolved) ? resolved : [resolved]\n    const active = limits.filter((l) => !l.disabled)\n\n    if (active.length === 0) {\n      return next()\n    }\n\n    let mostRestrictive: { limit: Limit; remaining: number; resetAt: number } | undefined\n    let exceeded: { limit: Limit; resetAt: number } | undefined\n\n    for (const limit of active) {\n      const key = this.makeKey(name, limit.windowSeconds, limit.key, limit.distinctValue !== undefined)\n      const hit =\n        limit.distinctValue === undefined\n          ? await this.hit(key, limit.windowSeconds)\n          : await this.hitDistinct(key, limit.windowSeconds, limit.distinctValue, limit.max)\n\n      if (hit.count > limit.max) {\n        if (!exceeded || hit.resetAt > exceeded.resetAt) {\n          exceeded = { limit, resetAt: hit.resetAt }\n        }\n        continue\n      }\n\n      const remaining = limit.max - hit.count\n      if (!mostRestrictive || remaining < mostRestrictive.remaining) {\n        mostRestrictive = { limit, remaining, resetAt: hit.resetAt }\n      }\n    }\n\n    if (exceeded) {\n      const headers = this.makeHeaders(exceeded.limit.max, 0, exceeded.resetAt)\n      if (exceeded.limit.customResponse) {\n        return exceeded.limit.customResponse(ctx, headers)\n      }\n      throw new TooManyRequestsError({\n        retryAfter: Number(headers['Retry-After']),\n        limit: exceeded.limit.max,\n        resetAt: exceeded.resetAt,\n      })\n    }\n\n    await next()\n\n    if (mostRestrictive) {\n      const headers = this.makeHeaders(\n        mostRestrictive.limit.max,\n        mostRestrictive.remaining,\n        mostRestrictive.resetAt,\n      )\n      // Hono populates ctx.c.res after next() — same pattern as logger.middleware.ts.\n      //\n      // Stamped unconditionally: the cache decision is not on the response yet at this point in\n      // the unwind, so whether these may be kept is decided by\n      // `createNoStoreFallbackMiddleware`, which strips them from a shared-cacheable response.\n      const downstream = ctx.c.res\n      downstream.headers.set('X-RateLimit-Limit', headers['X-RateLimit-Limit'])\n      downstream.headers.set('X-RateLimit-Remaining', headers['X-RateLimit-Remaining'])\n      downstream.headers.set('X-RateLimit-Reset', headers['X-RateLimit-Reset'])\n    }\n  }\n\n  /**\n   * Get-modify-set increment over the typed KV store. Not atomic across\n   * concurrent edge requests on KV — see `KvRateLimiterStore`'s caveat.\n   */\n  private async hit(key: string, windowSeconds: number): Promise<RateLimitHit> {\n    const now = Date.now()\n    const existing = await this.store.get<StoredHit>(key)\n\n    let next: StoredHit\n    if (!existing || existing.resetAt <= now) {\n      next = { count: 1, resetAt: now + windowSeconds * 1000 }\n    } else {\n      next = { count: existing.count + 1, resetAt: existing.resetAt }\n    }\n\n    const ttlSeconds = Math.max(1, Math.ceil((next.resetAt - now) / 1000))\n    await this.store.set(key, next, ttlSeconds)\n    return next\n  }\n\n  /**\n   * A window that counts DISTINCT values rather than requests.\n   *\n   * Uses the same typed-KV store as {@link hit} — the store persists arbitrary values, so a\n   * cardinality window needs no store-interface change — but a key namespace of its own, since\n   * the two shapes are not interchangeable and a shared key would have each read the other's.\n   *\n   * A value already present is admitted WITHOUT a write, which both keeps the count stable and\n   * leaves the TTL alone: re-touching something already counted must not slide the window. The\n   * stored set therefore never exceeds `max`.\n   *\n   * The cap is a SOFT ceiling under an eventually-consistent store. This is a read-modify-write\n   * of the whole array, so N concurrent requests carrying N different values all read the same\n   * set and last-write-wins keeps one of them: a burst can overshoot `max`, and unlike a lost\n   * counter increment (which the next request re-adds) a lost set member is gone for the rest of\n   * the window. Intended for small caps — tens, not thousands; nothing bounds `max` itself, and\n   * the whole set is read and rewritten on every new value. A hard cap needs a\n   * strongly-consistent store, i.e. a Durable Object.\n   */\n  private async hitDistinct(\n    key: string,\n    windowSeconds: number,\n    value: string,\n    max: number,\n  ): Promise<RateLimitHit> {\n    const now = Date.now()\n    const existing = await this.store.get<StoredDistinct>(key)\n\n    if (existing && existing.resetAt > now) {\n      if (existing.values.includes(value)) {\n        return { count: existing.values.length, resetAt: existing.resetAt }\n      }\n\n      // A new value past the cap is refused WITHOUT being stored: persisting it would push the\n      // stored count past `max` for every later request, including ones for values already\n      // counted, which must stay admitted.\n      if (existing.values.length >= max) {\n        return { count: existing.values.length + 1, resetAt: existing.resetAt }\n      }\n\n      const values = [...existing.values, value]\n      const ttlSeconds = Math.max(1, Math.ceil((existing.resetAt - now) / 1000))\n      await this.store.set(key, { values, resetAt: existing.resetAt }, ttlSeconds)\n      return { count: values.length, resetAt: existing.resetAt }\n    }\n\n    const resetAt = now + windowSeconds * 1000\n    await this.store.set(key, { values: [value], resetAt }, Math.max(1, windowSeconds))\n    return { count: 1, resetAt }\n  }\n\n  /**\n   * Distinct windows carry a `d:` segment: they store `StoredDistinct` where a plain window\n   * stores `StoredHit`, and one limiter name can legitimately declare both on the same window\n   * and actor. Sharing a key would have each branch read the other's shape and throw.\n   */\n  private makeKey(\n    name: string,\n    windowSeconds: number,\n    by: string | undefined,\n    distinct: boolean,\n  ): string {\n    const actor = by ?? '*'\n    return `rl:${name}:${distinct ? 'd:' : ''}${windowSeconds}:${actor}`\n  }\n\n  private makeHeaders(limit: number, remaining: number, resetAt: number): RateLimitHeaders {\n    const retryAfter = Math.max(1, Math.ceil((resetAt - Date.now()) / 1000))\n    return {\n      'Retry-After': String(retryAfter),\n      'X-RateLimit-Limit': String(limit),\n      'X-RateLimit-Remaining': String(Math.max(0, remaining)),\n      'X-RateLimit-Reset': String(Math.ceil(resetAt / 1000)),\n    }\n  }\n}\n","import type { CacheService } from '../../cache/services/cache.service'\nimport type { IRateLimiterStore } from './rate-limiter-store.interface'\n\n/**\n * Cloudflare KV-backed typed KV store.\n *\n * KV's minimum `expirationTtl` is 60 seconds; sub-60s windows are still\n * enforced by the registry's algorithm via the persisted `resetAt`, but\n * the key itself may live in KV longer than the logical window.\n *\n * KV has no native atomic increment, so concurrent writes from different\n * edge locations may undercount under high contention. That's an inherent\n * KV tradeoff — pick `{ useClass: MyDurableObjectStore }` for strict\n * accuracy across edges.\n */\nexport class KvRateLimiterStore implements IRateLimiterStore {\n  constructor(private readonly cache: CacheService) {}\n\n  async get<T>(key: string): Promise<T | null> {\n    return (await this.cache.get<T>(key, 'json')) ?? null\n  }\n\n  async set<T>(key: string, value: T, ttlSeconds: number): Promise<void> {\n    const ttl = Math.max(60, Math.ceil(ttlSeconds))\n    // `CacheService.put` defers the KV write via `waitUntil`, so this no longer\n    // blocks the request on KV's central-store write latency.\n    await this.cache.put(key, JSON.stringify(value), { expirationTtl: ttl })\n  }\n\n  async delete(key: string): Promise<void> {\n    await this.cache.delete(key)\n  }\n}\n","import type { IRateLimiterStore } from './rate-limiter-store.interface'\n\ninterface Entry {\n  value: unknown\n  expiresAt: number\n}\n\n/**\n * In-process Map-backed typed KV store.\n *\n * Suitable for tests and single-isolate scenarios. Not safe across\n * Cloudflare Worker isolates — entries reset whenever a fresh isolate\n * spins up. Use `KvRateLimiterStore` (or a custom Durable Object store)\n * for production. Expiry is lazy: stale entries are dropped on the next\n * `get`.\n */\nexport class InMemoryRateLimiterStore implements IRateLimiterStore {\n  private readonly entries = new Map<string, Entry>()\n\n  get<T>(key: string): Promise<T | null> {\n    const entry = this.entries.get(key)\n    if (!entry) return Promise.resolve(null)\n    if (entry.expiresAt <= Date.now()) {\n      this.entries.delete(key)\n      return Promise.resolve(null)\n    }\n    return Promise.resolve(entry.value as T)\n  }\n\n  set<T>(key: string, value: T, ttlSeconds: number): Promise<void> {\n    this.entries.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000 })\n    return Promise.resolve()\n  }\n\n  delete(key: string): Promise<void> {\n    this.entries.delete(key)\n    return Promise.resolve()\n  }\n}\n","import { inject } from '../../di'\nimport { CACHE_TOKENS } from '../../cache/cache.tokens'\nimport type { CacheService } from '../../cache/services/cache.service'\nimport { CONTAINER_TOKEN, type Container } from '../../di'\nimport { Singleton } from '../../di/decorators'\nimport { DI_TOKENS } from '../../di/tokens'\nimport type { StratalEnv } from '../../env'\nimport type { Constructor } from '../../types'\nimport { RateLimiterError } from '../errors'\nimport { RATE_LIMITER_TOKENS } from '../rate-limiter.tokens'\nimport { KvRateLimiterStore } from './kv-store'\nimport { InMemoryRateLimiterStore } from './memory-store'\nimport type { IRateLimiterStore } from './rate-limiter-store.interface'\n\n/**\n * Configuration for `RateLimiterModule.forRoot()`. Picks the backing store.\n *\n * - `'kv'`: Cloudflare KV. `binding` names the KVNamespace on `StratalEnv`.\n * - `'memory'`: in-process Map. Tests / single-isolate only.\n * - `{ useClass }`: any class implementing `IRateLimiterStore`. Resolved\n *   from the DI container (so the class can declare its own `@inject` deps,\n *   e.g. a Durable Object namespace from `StratalEnv`).\n */\nexport type RateLimiterModuleOptions =\n  | { store: 'kv'; binding: keyof StratalEnv }\n  | { store: 'memory' }\n  | { store: { useClass: Constructor<IRateLimiterStore> } }\n\n// IMPORTANT: see RateLimiterRegistry — no token on @Singleton so the\n// factory isn't globally bound at class-load time. Module providers are\n// the sole binding source, which keeps the \"module not imported\" detection\n// in ThrottleMiddleware working.\n@Singleton()\nexport class RateLimiterStoreFactory {\n  constructor(\n    @inject(DI_TOKENS.CloudflareEnv) private readonly env: StratalEnv,\n    @inject(CACHE_TOKENS.CacheService) private readonly cache: CacheService,\n    @inject(CONTAINER_TOKEN) private readonly container: Container,\n    @inject(RATE_LIMITER_TOKENS.Options, { isOptional: true })\n    private readonly options?: RateLimiterModuleOptions,\n  ) {}\n\n  create(): IRateLimiterStore {\n    if (!this.options) {\n      throw new RateLimiterError('RateLimiterModule is not configured. Call RateLimiterModule.forRoot({ store: ... }) to configure a backing store.')\n    }\n\n    const { store } = this.options\n\n    if (store === 'memory') {\n      return new InMemoryRateLimiterStore()\n    }\n\n    if (store === 'kv') {\n      const binding = this.env[this.options.binding] as KVNamespace | undefined\n      if (!binding) {\n        throw new RateLimiterError(`KV binding \"${String(this.options.binding)}\" is not available in the environment.`)\n      }\n      return new KvRateLimiterStore(this.cache.withBinding(binding))\n    }\n\n    return this.container.resolve<IRateLimiterStore>(store.useClass)\n  }\n}\n","import { CacheModule } from '../cache'\nimport type { ExceptionHandler } from '../errors/exception-handler'\nimport { Module } from '../module'\nimport type { AsyncModuleOptions, DynamicModule, ModuleContext, OnException, OnInitialize } from '../module/types'\nimport { TooManyRequestsError } from './errors'\nimport { RateLimiterRegistry } from './rate-limiter-registry'\nimport { RATE_LIMITER_TOKENS } from './rate-limiter.tokens'\nimport { RateLimiterStoreFactory, type RateLimiterModuleOptions } from './stores/store-factory'\nimport type { IRateLimiterStore } from './stores/rate-limiter-store.interface'\n\n/**\n * Rate limiter module — opt-in, NOT registered automatically by Application.\n *\n * Usage:\n * ```typescript\n * @Module({\n *   imports: [RateLimiterModule.forRoot({ store: 'kv', binding: 'RATE_LIMITS' })],\n * })\n * export class AppModule {}\n * ```\n *\n * Define limiters in any module's `onInitialize` hook by resolving\n * `RATE_LIMITER_TOKENS.Registry` from the container. Apply them with\n * `router.throttle('name')` or `@RateLimit('name')`.\n *\n * The module:\n *  - eagerly validates the store at app boot (`onInitialize` resolves the\n *    factory and calls `create()`); a missing `forRoot` surfaces\n *    `RateLimiterError` before any request is served.\n *  - registers a `respond()` callback on the `ExceptionHandler` (via\n *    `onException`) that injects `Retry-After` and `X-RateLimit-*` headers\n *    on every {@link TooManyRequestsError} response, regardless of whether\n *    the body was rendered as JSON, HTML, or via Inertia.\n */\n@Module({\n  imports: [CacheModule],\n  providers: [\n    { provide: RATE_LIMITER_TOKENS.Registry, useClass: RateLimiterRegistry },\n    { provide: RATE_LIMITER_TOKENS.StoreFactory, useClass: RateLimiterStoreFactory },\n    {\n      provide: RATE_LIMITER_TOKENS.Store,\n      useFactory: (factory: RateLimiterStoreFactory) => factory.create(),\n      inject: [RATE_LIMITER_TOKENS.StoreFactory],\n    },\n  ],\n})\nexport class RateLimiterModule implements OnInitialize, OnException {\n  /**\n   * Configure the rate limiter with a store choice.\n   *\n   * @param options - `{ store: 'kv', binding }` | `{ store: 'memory' }` | `{ store: { useClass } }`\n   */\n  static forRoot(options: RateLimiterModuleOptions): DynamicModule {\n    return {\n      module: RateLimiterModule,\n      providers: [\n        { provide: RATE_LIMITER_TOKENS.Options, useValue: options },\n      ],\n    }\n  }\n\n  /**\n   * Async configuration. Use when store options depend on other services\n   * (e.g. ConfigService).\n   */\n  static forRootAsync(options: AsyncModuleOptions<RateLimiterModuleOptions>): DynamicModule {\n    return {\n      module: RateLimiterModule,\n      providers: [\n        {\n          provide: RATE_LIMITER_TOKENS.Options,\n          useFactory: options.useFactory,\n          inject: options.inject,\n        },\n      ],\n    }\n  }\n\n  /**\n   * Eagerly resolve the store so a missing `forRoot()` fails at boot,\n   * not on the first throttled request. Also registers a per-app marker\n   * value so ThrottleMiddleware can distinguish \"module imported into this\n   * app\" from \"module class loaded somewhere in the process\" (the latter is\n   * indistinguishable at the DI layer because @Module's `registry()` call\n   * binds providers globally at decoration time).\n   */\n  onInitialize({ container }: ModuleContext): void {\n    container.resolve<IRateLimiterStore>(RATE_LIMITER_TOKENS.Store)\n    container.registerValue(RATE_LIMITER_TOKENS.ModuleMarker, { imported: true })\n  }\n\n  /**\n   * Inject `Retry-After` + `X-RateLimit-*` headers on every 429 response.\n   * The body itself is rendered by `ExceptionHandler.defaultRender` —\n   * content-negotiated, so HTML clients (browsers, Inertia) and JSON\n   * clients both get the right shape.\n   */\n  onException(handler: ExceptionHandler): void {\n    handler.dontReport([TooManyRequestsError])\n    handler.respond((response, error) => {\n      if (!(error instanceof TooManyRequestsError)) return response\n      response.headers.set('Retry-After', String(error.info.retryAfter))\n      response.headers.set('X-RateLimit-Limit', String(error.info.limit))\n      response.headers.set('X-RateLimit-Remaining', '0')\n      response.headers.set('X-RateLimit-Reset', String(Math.ceil(error.info.resetAt / 1000)))\n      return response\n    })\n  }\n}\n"],"mappings":"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"}

package/dist/response-cache/index.d.mts

@@ -0,0 +1,326 @@
+import { Gr as PartitionResolver, Hr as CacheableOptions, Jn as AsyncModuleOptions, Jr as ResponseCacheGatewayOptions, Kr as PurgesCacheOptions, Ur as CachedEntrypointName, Wr as EntrypointNameFrom, Xn as DynamicModule, Yr as ResponseCacheModuleOptions, _r as WorkersCache, bn as GatewayRouteTable, hr as PurgeSpec, li as ApplicationError, qr as ResolvedCacheable, yn as GatewayRouteEntry } from "../index-B2WtEagR.mjs";
+//#region src/response-cache/decorators/cacheable.decorator.d.ts
+/**
+ * Mark a route's response as cacheable by Cloudflare Workers Caching.
+ *
+ * Only `GET` and `HEAD` are ever cached. Omitted fields fall back to the
+ * module's `defaults` block; an explicit value always wins.
+ *
+ * @example
+ * ```typescript
+ * @Get('/blog/:slug')
+ * @Cacheable({ ttl: 300, swr: 60, tags: ['post:{param.slug}'] })
+ * async show(ctx: RouterContext) { ... }
+ * ```
+ *
+ * Module defaults fill in whatever the route leaves out:
+ *
+ * @example
+ * ```typescript
+ * ResponseCacheModule.forRoot({ defaults: { ttl: 300, swr: 60 } })
+ *
+ * @Get('/pricing')
+ * @Cacheable()                       // ttl 300, swr 60
+ * async pricing(ctx: RouterContext) { ... }
+ * ```
+ *
+ * **A guarded route needs a `partitionBy`.** A guarded route's response differs
+ * per caller, so caching it under one shared entry would serve one user's
+ * response to another. `@Cacheable` on a route carrying `@UseGuards` is a boot
+ * error unless it declares a non-empty `partitionBy` (or inherits one from
+ * `defaults.partitionBy`) — and per-caller keying additionally requires
+ * `ResponseCacheModule.forRoot({ gateway: { entrypoint } })`, without which
+ * `partitionBy` itself is rejected at boot.
+ *
+ * @example
+ * ```typescript
+ * @Get('/dashboard')
+ * @UseGuards(AuthGuard)
+ * @Cacheable({ ttl: 60, partitionBy: ['user'] })
+ * async dashboard(ctx: RouterContext) { ... }
+ * ```
+ */
+export declare function Cacheable(options?: CacheableOptions): MethodDecorator;
+/** Read the `@Cacheable` options for a method. Returns `undefined` when absent. */
+export declare function getCacheable(target: object, methodName: string): CacheableOptions | undefined;
+//#endregion
+//#region src/response-cache/decorators/purges-cache.decorator.d.ts
+/**
+ * Invalidate cached responses after this route mutates data.
+ *
+ * Runs after the handler returns a 2xx or 3xx. `pathPrefixes` matches the
+ * request path only, so `['/blog']` also clears `/blog?page=2`.
+ *
+ * @example
+ * ```typescript
+ * @Post('/posts/:slug/publish')
+ * @PurgesCache({ tags: ['post:{param.slug}', 'category:{data.post.categoryId}'] })
+ * async publish(ctx: RouterContext) { ... }
+ * ```
+ */
+export declare function PurgesCache(options: PurgesCacheOptions): MethodDecorator;
+/** Read the `@PurgesCache` options for a method. Returns `undefined` when absent. */
+export declare function getPurgesCache(target: object, methodName: string): PurgesCacheOptions | undefined;
+//#endregion
+//#region src/response-cache/response-cache.module.d.ts
+/**
+ * Response caching on Cloudflare Workers Caching — opt-in, NOT registered
+ * automatically by `Application`.
+ *
+ * Requires `cache.enabled = true` in the Wrangler config, Wrangler >= 4.69.0,
+ * and `compatibility_date >= 2026-07-06`. Without that binding, a route
+ * decorated with `@PurgesCache` throws `CachePurgeError` **at request time**
+ * — after its mutation has already committed — rather than silently
+ * skipping the purge and leaving the cache stale. Fail-loud is deliberate
+ * here, but it does mean a `@PurgesCache` route deployed to an environment
+ * that forgot `cache.enabled` turns every successful mutation into a `500`;
+ * confirm the binding is present in every environment that uses it.
+ *
+ * `forRootAsync`'s `useFactory` **must be synchronous**, or resolve
+ * synchronously from the caller's perspective: route registration reads
+ * `defaults` before any async work this module kicks off could settle, so
+ * an async factory's `Promise` is read as the options object itself,
+ * silently discarding `defaults` (this is detected and throws at boot,
+ * rather than silently caching without the intended defaults).
+ *
+ * Per-caller caching needs the gateway: `partitionBy`, `partitions`, and
+ * `primers` all throw `ResponseCacheConfigError` at boot unless
+ * `gateway: { entrypoint }` names a cached entrypoint built with
+ * `cachedEntrypoint(stratal)` from `stratal/workers`. A route that declares a
+ * partition it cannot honour must fail loudly rather than cache per-user data
+ * publicly.
+ *
+ * ```typescript
+ * @Module({
+ *   imports: [ResponseCacheModule.forRoot({
+ *     defaults: { ttl: 300, swr: 60, vary: ['Accept-Language'] },
+ *   })],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * With per-caller partitioning:
+ *
+ * ```typescript
+ * // app.module.ts
+ * ResponseCacheModule.forRoot({
+ *   gateway: { entrypoint: 'Cached' },
+ *   partitions: { user: (ctx) => ctx.user().id },
+ * })
+ *
+ * // src/index.ts
+ * const stratal = new Stratal({ module: AppModule })
+ * export default stratal
+ * export const Cached = cachedEntrypoint(stratal)
+ * ```
+ */
+export declare class ResponseCacheModule {
+  static forRoot(options?: ResponseCacheModuleOptions): DynamicModule;
+  static forRootAsync(options: AsyncModuleOptions<ResponseCacheModuleOptions>): DynamicModule;
+}
+//#endregion
+//#region src/response-cache/response-cache.tokens.d.ts
+export declare const RESPONSE_CACHE_TOKENS: {
+  readonly Options: symbol;
+  readonly ResponseCacheService: symbol;
+  readonly CacheabilityService: symbol;
+  readonly PartitionResolverService: symbol;
+  readonly GatewayPrimerService: symbol;
+  readonly GatewayPrimers: symbol;
+  readonly GatewayRouteTable: symbol;
+};
+type ResponseCacheToken = (typeof RESPONSE_CACHE_TOKENS)[keyof typeof RESPONSE_CACHE_TOKENS];
+//#endregion
+//#region src/response-cache/errors/response-cache.error.d.ts
+/** A rendered `Cache-Tag` value Cloudflare would silently drop. */
+export declare class InvalidCacheTagError extends ApplicationError {
+  constructor(tag: string, reason: string);
+}
+/** A purge failed after its mutation already committed. */
+export declare class CachePurgeError extends ApplicationError {
+  constructor(detail: string, cause?: unknown);
+}
+/** Misconfiguration detected at boot. */
+export declare class ResponseCacheConfigError extends ApplicationError {
+  constructor(detail: string);
+}
+//#endregion
+//#region src/response-cache/resolve-cacheable.d.ts
+/** Where a `@Cacheable` was declared, for error messages and the guard rule. */
+interface CacheableContext {
+  controller: string;
+  method: string;
+  /** True when the route or its controller has guards attached. */
+  guarded: boolean;
+  /**
+   * The `:param` names this route's own path declares, in order — used to
+   * validate `{param.*}` cache tags against a route that can never populate
+   * them. `undefined` (rather than `[]`) means "not known to the caller",
+   * which skips that validation entirely instead of treating every
+   * `{param.*}` tag as unresolvable; only the real HTTP registration path
+   * (`RouteRegistrationService`) can supply it, so unit tests exercising
+   * `bindRouteCache` directly are free to omit it.
+   */
+  routeParams?: string[];
+  /**
+   * True when `ResponseCacheModule.forRoot({ gateway: { entrypoint } })` names
+   * a cached entrypoint — the only configuration under which a partition can
+   * actually be placed in the cache key. Governs both the `partitionBy` throw
+   * in `bindRouteCache` and the guarded-route message below.
+   */
+  gatewayConfigured?: boolean;
+}
+//#endregion
+//#region src/response-cache/boot-check.d.ts
+/**
+ * Why this entrypoint cannot cache, or `undefined` when it can.
+ *
+ * A Worker cannot read its own Wrangler configuration, but the presence of
+ * `ctx.cache` tells us whether Workers Caching is enabled for this entrypoint.
+ *
+ * Reported rather than thrown, and the distinction is the whole point. The
+ * hazard is a route stamping `public, max-age=…` while nothing stores the
+ * response: a claim the app makes and no layer honours. Refusing to make that
+ * claim removes the hazard — the response falls through to
+ * `createNoStoreFallbackMiddleware` and is stamped `private, no-store`, which
+ * is both true and visible in the response itself. Failing the request
+ * removes it too, but takes down every route in the isolate to do it,
+ * including the ones that never asked to be cached.
+ *
+ * The answer belongs to an entrypoint rather than to the app, because a
+ * gateway topology runs two of them — one with `cache.enabled` false by
+ * design, one with it true — inside a single isolate.
+ */
+export declare function cachingUnavailableReason(cacheableRouteCount: number, cache: WorkersCache | undefined): string | undefined;
+/**
+ * Validate the configured entrypoint name itself.
+ *
+ * Split from the reachability check in `resolveCachedEntrypoint` because this
+ * part needs no runtime: a name that is empty, or names the gateway itself, is
+ * wrong on inspection and should never reach a first request.
+ */
+export declare function assertValidGatewayEntrypoint(options: ResponseCacheModuleOptions): void;
+//#endregion
+//#region src/response-cache/services/route-cache-binding.d.ts
+/** What one route needs at request time, resolved once at registration. */
+interface RouteCacheBinding {
+  cacheable?: ResolvedCacheable;
+  purges?: PurgesCacheOptions;
+}
+/**
+ * Fold a route's decorators and the module defaults into the config the request
+ * path uses. Runs once per route at registration, never per request.
+ *
+ * Returns `undefined` when the route declares neither decorator, so the hot path
+ * can skip all cache work with a single truthiness check.
+ *
+ * @throws {ResponseCacheConfigError} On a non-empty `partitionBy` when no
+ *   `gateway.entrypoint` is configured. Placing a partition in the cache key
+ *   requires the gateway to forward the read to a cached entrypoint over
+ *   `ctx.exports`. Accepting the option and ignoring it would give every
+ *   visitor a single shared entry for a route the author explicitly marked
+ *   per-user.
+ * @throws {ResponseCacheConfigError} On a `{body.*}` tag in either decorator's
+ *   `tags` — see `assertNoBodyScopeTags`.
+ * @throws {ResponseCacheConfigError} On a `{param.X}` tag whose `X` is not a
+ *   `:param` in this route's own path (when `context.routeParams` is
+ *   supplied) — see `assertParamTagsResolvable`.
+ * @throws {ResponseCacheConfigError} On a `{`/`}` in `@PurgesCache`'s
+ *   `pathPrefixes` — see `assertNoTemplatedPathPrefixes`.
+ */
+export declare function bindRouteCache(cacheable: CacheableOptions | undefined, purges: PurgesCacheOptions | undefined, defaults: Omit<CacheableOptions, 'tags'>, context: CacheableContext): RouteCacheBinding | undefined;
+//#endregion
+//#region src/response-cache/gateway-mode.d.ts
+/**
+ * Mark an execution context as running in gateway mode.
+ *
+ * Called by `Stratal.fetch` (the default export — the eyeball entrypoint) and
+ * by `@stratal/testing`, which drives `HonoApp#fetch` directly. Deliberately
+ * **not** called by `cachedEntrypoint`, which is what stops the cached
+ * entrypoint from dispatching back into itself.
+ *
+ * Returns the same object it was given, so it can be used inline.
+ */
+export declare function markGatewayMode<T extends object>(ctx: T): T;
+/** Whether this execution context was marked by {@link markGatewayMode}. */
+export declare function isGatewayMode(ctx: unknown): boolean;
+//#endregion
+//#region src/response-cache/gateway-binding.d.ts
+/**
+ * The two things the gateway asks of the cached entrypoint.
+ *
+ * `ctx.exports.<Name>` is typed as `Cloudflare.Exports[Name]`, which resolves
+ * to `{}` unless the consumer has generated `Cloudflare.GlobalProps` with
+ * `wrangler types`. The framework can't require that, and can't name the
+ * consumer's export at compile time either — the name arrives as a string in
+ * `gateway.entrypoint` — so the stub is described structurally here and the
+ * lookup is checked at runtime by `resolveCachedEntrypoint`.
+ */
+interface CachedEntrypointStub {
+  /** The loopback `fetch`, routed through the cached entrypoint's cache. */
+  fetch(request: Request): Promise<Response>;
+  /**
+   * The RPC purge. Purges are scoped to the entrypoint that issues them, and
+   * mutations run inline in the *gateway*, whose cache is disabled — so a
+   * purge issued there would target an empty cache and silently do nothing.
+   * See `cachedEntrypoint`.
+   */
+  purge(spec: PurgeSpec): Promise<{
+    success: boolean;
+  } | void>;
+}
+/**
+ * A loopback binding: callable to bind `ctx.props` for the invocation, and
+ * directly usable when no props are needed.
+ *
+ * `LoopbackServiceStub<T>` in `@cloudflare/workers-types` is
+ * `Fetcher<T> & ((opts: { props?: Props }) => Fetcher<T>)` — the callable form
+ * is the documented way to choose the callee's `ctx.props`, and `ctx.props` is
+ * what places a partition in the cache key.
+ */
+type CachedEntrypointBinding = CachedEntrypointStub & ((options: {
+  props?: Record<string, string>;
+}) => CachedEntrypointStub);
+/**
+ * Look up the configured cached entrypoint on `ctx.exports`, failing loudly if
+ * it isn't there.
+ *
+ * A typo in `gateway: { entrypoint: 'Cachd' }`, a missing `export const
+ * Cached = ...`, or a missing `enable_ctx_exports` compatibility flag would
+ * otherwise all present identically: every partitioned route quietly runs
+ * inline in the gateway forever, never caching, with no signal anywhere. The
+ * whole point of `partitionBy` refusing to boot without a gateway is that a
+ * declared partition is either honoured or it is an error — so this is an
+ * error too.
+ *
+ * @throws {ResponseCacheConfigError} `ctx.exports` is unavailable, or carries
+ *   no export under `name`.
+ */
+export declare function resolveCachedEntrypoint(ctx: unknown, name: string): CachedEntrypointBinding;
+/**
+ * A `WorkersCache` that purges through the cached entrypoint over RPC.
+ *
+ * Handed to `ResponseCacheService.purge()` in place of the gateway's own
+ * `ctx.cache` whenever a gateway is configured and this request is running as
+ * the gateway. See `cachedEntrypoint` for why that redirection is required
+ * rather than merely tidy.
+ */
+export declare function createLoopbackPurgeTarget(ctx: unknown, name: string): {
+  purge: (spec: PurgeSpec) => Promise<void | {
+    success: boolean;
+  }>;
+};
+//#endregion
+//#region src/response-cache/cached-entrypoint.d.ts
+/**
+ * Whether the gateway should forward this request into the cached entrypoint.
+ *
+ * Anything that returns `false` runs inline in the gateway and never reaches
+ * the cached entrypoint at all — which is what keeps RFC 9111 heuristic
+ * freshness (a `200` with no `Cache-Control` cached for two hours) away from
+ * un-annotated routes.
+ */
+export declare function shouldLoopback(method: string, cacheable: CacheableOptions | undefined): boolean;
+//#endregion
+export { type CacheableContext, type CacheableOptions, type CachedEntrypointBinding, type CachedEntrypointName, type CachedEntrypointStub, type EntrypointNameFrom, type GatewayRouteEntry, GatewayRouteTable, type PartitionResolver, type PurgeSpec, type PurgesCacheOptions, type ResolvedCacheable, type ResponseCacheGatewayOptions, type ResponseCacheModuleOptions, type ResponseCacheToken, type RouteCacheBinding, type WorkersCache };
+//# sourceMappingURL=index.d.mts.map

package/dist/response-cache/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/response-cache/decorators/cacheable.decorator.ts","../../src/response-cache/decorators/purges-cache.decorator.ts","../../src/response-cache/response-cache.module.ts","../../src/response-cache/response-cache.tokens.ts","../../src/response-cache/errors/response-cache.error.ts","../../src/response-cache/resolve-cacheable.ts","../../src/response-cache/boot-check.ts","../../src/response-cache/services/route-cache-binding.ts","../../src/response-cache/gateway-mode.ts","../../src/response-cache/gateway-binding.ts","../../src/response-cache/cached-entrypoint.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA8CgB,UAAU,UAAS,mBAAwB;;wBAO3C,aAAa,gBAAgB,qBAAqB;;;;;;;;;;;;;;;;wBCjClD,YAAY,SAAS,qBAAqB;;wBAqB1C,eAAe,gBAAgB,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBC0BvD;SACJ,QAAQ,UAAS,6BAAkC;SASnD,aAAa,SAAS,mBAAmB,8BAA8B;;;;qBC7EnE;WACX;WACA;WACA;WACA;WACA;WACA;WACA;;KAGU,6BACF,oCAAoC;;;;qBCRjC,6BAA6B;EACxC,YAAY,aAAa;;;qBAMd,wBAAwB;EACnC,YAAY,gBAAgB;;;qBAMjB,iCAAiC;EAC5C,YAAY;;;;;UCdG;EACf;EACA;;EAEA;;;;;;;;;;EAUA;;;;;;;EAOA;;;;;;;;;;;;;;;;;;;;;;;wBCFc,yBACd,6BACA,OAAO;;;;;;;;wBAgCO,6BAA6B,SAAS;;;;UCpDrC;EACf,YAAY;EACZ,SAAS;;;;;;;;;;;;;;;;;;;;;;;wBA+KK,eACd,WAAW,8BACX,QAAQ,gCACR,UAAU,KAAK,2BACf,SAAS,mBACR;;;;;;;;;;;;;wBClJa,gBAAgB,kBAAkB,KAAK,IAAI;;wBAM3C,cAAc;;;;;;;;;;;;;UClCb;;EAEf,MAAM,SAAS,UAAU,QAAQ;;;;;;;EAOjC,MAAM,MAAM,YAAY;IAAU;;;;;;;;;;;;KAYxB,0BAA0B,yBAClC;EAAW,QAAQ;MAA6B;;;;;;;;;;;;;;;;wBAiBpC,wBAAwB,cAAc,eAAe;;;;;;;;;wBA+CrD,0BAA0B,cAAc;EAKpD,QAAK,MAAe,cAAS;IAlFY;;;;;;;;;;;;;wBCT7B,eAAe,gBAAgB,WAAW"}