stratal 0.0.21 → 0.0.23

package/dist/cache/index.d.mts

@@ -1,6 +1,10 @@
-import { d as ApplicationError } from "../index-ByOyTmqf.mjs";
-import { t as CacheService } from "../cache.service-DsnKuNyO.mjs";
+import { Dr as ApplicationError } from "../index-B_JoEl3V.mjs";
+import { t as CacheService } from "../cache.service-uElmBtdS.mjs";
+import { t as TieredCacheService } from "../tiered-cache.service-Dv3BhxxE.mjs";
 
+//#region src/cache/cache.error.d.ts
+declare class CacheError extends ApplicationError {}
+//#endregion
 //#region src/cache/cache.module.d.ts
 /**
  * Cache Module
@@ -18,51 +22,9 @@ declare class CacheModule {}
 //#region src/cache/cache.tokens.d.ts
 declare const CACHE_TOKENS: {
   readonly CacheService: symbol;
+  readonly TieredCacheService: symbol;
 };
 type CacheToken = (typeof CACHE_TOKENS)[keyof typeof CACHE_TOKENS];
 //#endregion
-//#region src/cache/errors/cache-get.error.d.ts
-/**
- * Error thrown when a cache get operation fails
- *
- * Raw error details are logged via LoggerService for security.
- * Only the key is included in the user-facing error message.
- */
-declare class CacheGetError extends ApplicationError {
-  constructor(key: string);
-}
-//#endregion
-//#region src/cache/errors/cache-put.error.d.ts
-/**
- * Error thrown when a cache put operation fails
- *
- * Raw error details are logged via LoggerService for security.
- * Only the key is included in the user-facing error message.
- */
-declare class CachePutError extends ApplicationError {
-  constructor(key: string);
-}
-//#endregion
-//#region src/cache/errors/cache-delete.error.d.ts
-/**
- * Error thrown when a cache delete operation fails
- *
- * Raw error details are logged via LoggerService for security.
- * Only the key is included in the user-facing error message.
- */
-declare class CacheDeleteError extends ApplicationError {
-  constructor(key: string);
-}
-//#endregion
-//#region src/cache/errors/cache-list.error.d.ts
-/**
- * Error thrown when a cache list operation fails
- *
- * Raw error details are logged via LoggerService for security.
- */
-declare class CacheListError extends ApplicationError {
-  constructor();
-}
-//#endregion
-export { CACHE_TOKENS, CacheDeleteError, CacheGetError, CacheListError, CacheModule, CachePutError, CacheService, CacheToken };
+export { CACHE_TOKENS, CacheError, CacheModule, CacheService, CacheToken, TieredCacheService };
 //# sourceMappingURL=index.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/cache/cache.module.ts","../../src/cache/cache.tokens.ts","../../src/cache/errors/cache-get.error.ts","../../src/cache/errors/cache-put.error.ts","../../src/cache/errors/cache-delete.error.ts","../../src/cache/errors/cache-list.error.ts"],"mappings":";;;;;;;;AAgBA;;;;;;;cAMa,WAAA;;;cCtBA,YAAA;EAAA,SAEH,YAAA;AAAA;AAAA,KAEE,UAAA,WAAqB,YAAA,eAA2B,YAAA;;;;;;ADY5D;;;cEPa,aAAA,SAAsB,gBAAA;cACrB,GAAA;AAAA;;;;;;AFMd;;;cGPa,aAAA,SAAsB,gBAAA;cACrB,GAAA;AAAA;;;;;;AHMd;;;cIPa,gBAAA,SAAyB,gBAAA;cACxB,GAAA;AAAA;;;;;;AJMd;;cKRa,cAAA,SAAuB,gBAAA;EAAA,WAAA,CAAA;AAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/cache/cache.error.ts","../../src/cache/cache.module.ts","../../src/cache/cache.tokens.ts"],"mappings":";;;;;cAEa,UAAA,SAAmB,gBAAgB;;;;;;;;AAAhD;;;;AAAgD;;cCsBnC,WAAA;;;cCxBA,YAAA;EAAA,SAGH,YAAA;EAAA,SAAA,kBAAA;AAAA;AAAA,KAEE,UAAA,WAAqB,YAAA,eAA2B,YAAY"}

package/dist/cache/index.mjs

@@ -1,57 +1,17 @@
-import { H as ApplicationError, k as ERROR_CODES } from "../errors-COW9-Mar.mjs";
-import { a as __decorate, f as DI_TOKENS, o as __decorateParam, p as Transient, s as __decorateMetadata, u as LOGGER_TOKENS } from "../logger-DlV7NtvD.mjs";
-import { k as Module } from "../module-BzLg57FK.mjs";
-import { t as CACHE_TOKENS } from "../cache.tokens-B7Rw1C9Q.mjs";
-import { inject } from "tsyringe";
-//#region src/cache/errors/cache-get.error.ts
-/**
-* Error thrown when a cache get operation fails
-*
-* Raw error details are logged via LoggerService for security.
-* Only the key is included in the user-facing error message.
-*/
-var CacheGetError = class extends ApplicationError {
-	constructor(key) {
-		super("errors.cache.getFailed", ERROR_CODES.SYSTEM.INFRASTRUCTURE_ERROR, { key });
-	}
-};
-//#endregion
-//#region src/cache/errors/cache-put.error.ts
-/**
-* Error thrown when a cache put operation fails
-*
-* Raw error details are logged via LoggerService for security.
-* Only the key is included in the user-facing error message.
-*/
-var CachePutError = class extends ApplicationError {
-	constructor(key) {
-		super("errors.cache.putFailed", ERROR_CODES.SYSTEM.INFRASTRUCTURE_ERROR, { key });
-	}
-};
-//#endregion
-//#region src/cache/errors/cache-delete.error.ts
-/**
-* Error thrown when a cache delete operation fails
-*
-* Raw error details are logged via LoggerService for security.
-* Only the key is included in the user-facing error message.
-*/
-var CacheDeleteError = class extends ApplicationError {
-	constructor(key) {
-		super("errors.cache.deleteFailed", ERROR_CODES.SYSTEM.INFRASTRUCTURE_ERROR, { key });
-	}
-};
+import { d as inject, r as DI_TOKENS, s as Singleton } from "../di-DseMn-z9.mjs";
+import { a as ApplicationError } from "../container-storage-BmOJ4_Na.mjs";
+import { n as __decorateParam, t as __decorate } from "../decorate-CuAoSZvs.mjs";
+import { LOGGER_TOKENS } from "../logger/index.mjs";
+import "../errors-mXYxG0XB.mjs";
+import { n as Module } from "../module.decorator-CYHY6pG5.mjs";
+import "../module/index.mjs";
+//#region src/cache/cache.error.ts
+var CacheError = class extends ApplicationError {};
 //#endregion
-//#region src/cache/errors/cache-list.error.ts
-/**
-* Error thrown when a cache list operation fails
-*
-* Raw error details are logged via LoggerService for security.
-*/
-var CacheListError = class extends ApplicationError {
-	constructor() {
-		super("errors.cache.listFailed", ERROR_CODES.SYSTEM.INFRASTRUCTURE_ERROR, {});
-	}
+//#region src/cache/cache.tokens.ts
+const CACHE_TOKENS = {
+	CacheService: Symbol.for("stratal:cache:service"),
+	TieredCacheService: Symbol.for("stratal:cache:tiered-service")
 };
 //#endregion
 //#region src/cache/services/cache.service.ts
@@ -65,47 +25,34 @@ let CacheService = _CacheService = class CacheService {
 		this.logger = logger;
 		this.kv = env.CACHE;
 	}
-	/**
-	* Set the KV namespace binding
-	*
-	* Used internally by `withBinding()` to configure different KV instances.
-	*
-	* @param kv - KV namespace to use
-	*/
-	setKV(kv) {
-		this.kv = kv;
+	/** The KV namespace this instance is bound to. */
+	get namespace() {
+		return this.kv;
 	}
 	/**
-	* Create a new CacheService instance with a different KV binding
-	*
-	* **Pattern:** Returns a new instance (immutable)
-	*
-	* **Best Practice:** Initialize specialized caches as class properties in constructor
-	*
-	* @example
-	* ```typescript
-	* class MyService {
-	*   private readonly uploadsCache: CacheService
-	*   private readonly systemCache: CacheService
-	*
-	*   constructor(
-	*     @inject(CACHE_TOKENS.CacheService) private readonly cache: CacheService,
-	*     @inject(DI_TOKENS.CloudflareEnv) private readonly env: Env
-	*   ) {
-	*     this.uploadsCache = this.cache.withBinding(this.env.UPLOADS_CACHE)
-	*     this.systemCache = this.cache.withBinding(this.env.SYSTEM_CONFIG_KV)
-	*   }
-	* }
-	* ```
+	* Create a new CacheService instance bound to a different KV namespace.
 	*
 	* @param kv - KV namespace to use
-	* @returns New CacheService instance with the specified binding
+	* @returns A new CacheService for the given binding
 	*/
 	withBinding(kv) {
 		const instance = new _CacheService(this.env, this.logger);
-		instance.setKV(kv);
+		instance.kv = kv;
 		return instance;
 	}
+	/**
+	* Create a new CacheService instance bound to a KV namespace by its binding
+	* name, resolved from the environment.
+	*
+	* @param name - KV namespace binding name (e.g. `'UPLOADS_CACHE'`)
+	* @returns A new CacheService for the given binding
+	* @throws {CacheError} If no binding with that name exists in the environment
+	*/
+	binding(name) {
+		const kv = this.env[name];
+		if (!kv) throw new CacheError(`KV binding "${name}" was not found in the environment`);
+		return this.withBinding(kv);
+	}
 	async get(key, typeOrOptions) {
 		try {
 			if (typeof typeOrOptions === "string") return await this.kv.get(key, typeOrOptions);
@@ -116,7 +63,7 @@ let CacheService = _CacheService = class CacheService {
 				key,
 				error
 			});
-			throw new CacheGetError(key);
+			throw new CacheError(`Failed to get cache key "${key}"`);
 		}
 	}
 	async getWithMetadata(key, typeOrOptions) {
@@ -129,7 +76,7 @@ let CacheService = _CacheService = class CacheService {
 				key,
 				error
 			});
-			throw new CacheGetError(key);
+			throw new CacheError(`Failed to get cache key "${key}"`);
 		}
 	}
 	/**
@@ -138,7 +85,7 @@ let CacheService = _CacheService = class CacheService {
 	* @param key - Cache key
 	* @param value - Value to store (string, ArrayBuffer, ArrayBufferView, or ReadableStream)
 	* @param options - Put options (expiration, expirationTtl, metadata)
-	* @throws {CachePutError} If operation fails
+	* @throws {CacheError} If operation fails
 	*
 	* @example
 	* ```typescript
@@ -160,14 +107,14 @@ let CacheService = _CacheService = class CacheService {
 				key,
 				error
 			});
-			throw new CachePutError(key);
+			throw new CacheError(`Failed to store cache key "${key}"`);
 		}
 	}
 	/**
 	* Delete a value from cache
 	*
 	* @param key - Cache key to delete
-	* @throws {CacheDeleteError} If operation fails
+	* @throws {CacheError} If operation fails
 	*/
 	async delete(key) {
 		try {
@@ -177,7 +124,7 @@ let CacheService = _CacheService = class CacheService {
 				key,
 				error
 			});
-			throw new CacheDeleteError(key);
+			throw new CacheError(`Failed to delete cache key "${key}"`);
 		}
 	}
 	/**
@@ -185,7 +132,7 @@ let CacheService = _CacheService = class CacheService {
 	*
 	* @param options - List options (limit, prefix, cursor)
 	* @returns List result with keys and pagination info
-	* @throws {CacheListError} If operation fails
+	* @throws {CacheError} If operation fails
 	*
 	* @example
 	* ```typescript
@@ -210,17 +157,104 @@ let CacheService = _CacheService = class CacheService {
 				options,
 				error
 			});
-			throw new CacheListError();
+			throw new CacheError("Failed to list cache keys");
 		}
 	}
 };
 CacheService = _CacheService = __decorate([
-	Transient(CACHE_TOKENS.CacheService),
+	Singleton(CACHE_TOKENS.CacheService),
 	__decorateParam(0, inject(DI_TOKENS.CloudflareEnv)),
-	__decorateParam(1, inject(LOGGER_TOKENS.LoggerService)),
-	__decorateMetadata("design:paramtypes", [Object, Object])
+	__decorateParam(1, inject(LOGGER_TOKENS.LoggerService))
 ], CacheService);
 //#endregion
+//#region src/cache/services/tiered-cache.service.ts
+var _TieredCacheService;
+/**
+* Max entries kept in the isolate-local L1 before the oldest is evicted (FIFO).
+* Bounds memory per isolate; KV remains the unbounded source of truth.
+*/
+const L1_MAX_ENTRIES = 1e3;
+let TieredCacheService = _TieredCacheService = class TieredCacheService {
+	cache;
+	/** Isolate-local L1 tier. Per-instance, so each binding has its own. */
+	l1 = /* @__PURE__ */ new Map();
+	/** Memoized tiered instances per binding name (each with its own L1). */
+	children = /* @__PURE__ */ new Map();
+	constructor(cache) {
+		this.cache = cache;
+	}
+	/**
+	* Get the tiered cache bound to a KV namespace by its binding name. Memoized:
+	* repeated calls with the same name return the same instance, preserving its
+	* isolate-local L1 across requests/messages.
+	*
+	* @param name - KV namespace binding name (e.g. `'UPLOADS_CACHE'`)
+	* @throws {CacheError} If no binding with that name exists in the environment
+	*/
+	binding(name) {
+		let child = this.children.get(name);
+		if (child === void 0) {
+			child = new _TieredCacheService(this.cache.binding(name));
+			this.children.set(name, child);
+		}
+		return child;
+	}
+	async get(key, typeOrOptions) {
+		const type = typeof typeOrOptions === "string" ? typeOrOptions : typeOrOptions?.type ?? "text";
+		if (type === "text" || type === "json") {
+			const cached = this.l1Read(key);
+			if (cached !== null) return type === "json" ? JSON.parse(cached) : cached;
+		}
+		const value = await this.cache.get(key, typeOrOptions);
+		if (type === "text" && typeof value === "string") this.l1Write(key, value, null);
+		return value;
+	}
+	async getWithMetadata(key, typeOrOptions) {
+		return this.cache.getWithMetadata(key, typeOrOptions);
+	}
+	async put(key, value, options) {
+		await this.cache.put(key, value, options);
+		if (typeof value === "string") this.l1Write(key, value, this.l1ExpiresAt(options));
+		else this.l1.delete(key);
+	}
+	async delete(key) {
+		await this.cache.delete(key);
+		this.l1.delete(key);
+	}
+	async list(options) {
+		return this.cache.list(options);
+	}
+	/** Read a fresh L1 entry, evicting it if expired. Returns `null` on miss. */
+	l1Read(key) {
+		const entry = this.l1.get(key);
+		if (entry === void 0) return null;
+		if (entry.expiresAt !== null && Date.now() >= entry.expiresAt) {
+			this.l1.delete(key);
+			return null;
+		}
+		return entry.value;
+	}
+	/** Write an L1 entry, refreshing its recency and evicting the oldest at cap. */
+	l1Write(key, value, expiresAt) {
+		this.l1.delete(key);
+		if (this.l1.size >= L1_MAX_ENTRIES) {
+			const oldest = this.l1.keys().next().value;
+			if (oldest !== void 0) this.l1.delete(oldest);
+		}
+		this.l1.set(key, {
+			value,
+			expiresAt
+		});
+	}
+	/** Compute an absolute L1 expiry (epoch ms) from KV put options. */
+	l1ExpiresAt(options) {
+		if (options?.expiration !== void 0) return options.expiration * 1e3;
+		if (options?.expirationTtl !== void 0) return Date.now() + options.expirationTtl * 1e3;
+		return null;
+	}
+};
+TieredCacheService = _TieredCacheService = __decorate([Singleton(CACHE_TOKENS.TieredCacheService), __decorateParam(0, inject(CACHE_TOKENS.CacheService))], TieredCacheService);
+//#endregion
 //#region src/cache/cache.module.ts
 /**
 * Cache Module
@@ -237,8 +271,11 @@ let CacheModule = class CacheModule {};
 CacheModule = __decorate([Module({ providers: [{
 	provide: CACHE_TOKENS.CacheService,
 	useClass: CacheService
+}, {
+	provide: CACHE_TOKENS.TieredCacheService,
+	useClass: TieredCacheService
 }] })], CacheModule);
 //#endregion
-export { CACHE_TOKENS, CacheDeleteError, CacheGetError, CacheListError, CacheModule, CachePutError, CacheService };
+export { CACHE_TOKENS, CacheError, CacheModule, CacheService, TieredCacheService };
 
 //# sourceMappingURL=index.mjs.map

package/dist/cache/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/cache/errors/cache-get.error.ts","../../src/cache/errors/cache-put.error.ts","../../src/cache/errors/cache-delete.error.ts","../../src/cache/errors/cache-list.error.ts","../../src/cache/services/cache.service.ts","../../src/cache/cache.module.ts"],"sourcesContent":["import { ERROR_CODES } from '../../errors'\nimport { ApplicationError } from '../../errors'\n\n/**\n * Error thrown when a cache get operation fails\n *\n * Raw error details are logged via LoggerService for security.\n * Only the key is included in the user-facing error message.\n */\nexport class CacheGetError extends ApplicationError {\n  constructor(key: string) {\n    super('errors.cache.getFailed', ERROR_CODES.SYSTEM.INFRASTRUCTURE_ERROR, { key })\n  }\n}\n","import { ERROR_CODES } from '../../errors'\nimport { ApplicationError } from '../../errors'\n\n/**\n * Error thrown when a cache put operation fails\n *\n * Raw error details are logged via LoggerService for security.\n * Only the key is included in the user-facing error message.\n */\nexport class CachePutError extends ApplicationError {\n  constructor(key: string) {\n    super('errors.cache.putFailed', ERROR_CODES.SYSTEM.INFRASTRUCTURE_ERROR, { key })\n  }\n}\n","import { ERROR_CODES } from '../../errors'\nimport { ApplicationError } from '../../errors'\n\n/**\n * Error thrown when a cache delete operation fails\n *\n * Raw error details are logged via LoggerService for security.\n * Only the key is included in the user-facing error message.\n */\nexport class CacheDeleteError extends ApplicationError {\n  constructor(key: string) {\n    super('errors.cache.deleteFailed', ERROR_CODES.SYSTEM.INFRASTRUCTURE_ERROR, { key })\n  }\n}\n","import { ERROR_CODES } from '../../errors'\nimport { ApplicationError } from '../../errors'\n\n/**\n * Error thrown when a cache list operation fails\n *\n * Raw error details are logged via LoggerService for security.\n */\nexport class CacheListError extends ApplicationError {\n  constructor() {\n    super('errors.cache.listFailed', ERROR_CODES.SYSTEM.INFRASTRUCTURE_ERROR, {})\n  }\n}\n","import { inject } from 'tsyringe'\nimport { Transient } from '../../di/decorators'\nimport { DI_TOKENS } from '../../di/tokens'\nimport { type StratalEnv } from '../../env'\nimport { LOGGER_TOKENS, type LoggerService } from '../../logger'\nimport { CACHE_TOKENS } from '../cache.tokens'\nimport {\n  CacheDeleteError,\n  CacheGetError,\n  CacheListError,\n  CachePutError,\n} from '../errors'\n\n/**\n * Cache Service\n *\n * Type-safe wrapper around Cloudflare KV namespaces for caching operations.\n *\n * **Features:**\n * - Mirrors all KVNamespace methods with full type safety\n * - Supports multiple KV bindings via `withBinding()`\n * - Automatic error handling with logging\n * - Security: Raw errors are logged, not exposed to users\n *\n * **Usage:**\n * ```typescript\n * class MyService {\n *   private readonly uploadsCache: CacheService\n *\n *   constructor(\n *     @inject(CACHE_TOKENS.CacheService) private readonly cache: CacheService,\n *     @inject(DI_TOKENS.CloudflareEnv) private readonly env: Env\n *   ) {\n *     // Initialize specialized caches in constructor\n *     this.uploadsCache = this.cache.withBinding(this.env.UPLOADS_CACHE)\n *   }\n *\n *   async cacheData(key: string, value: string) {\n *     await this.cache.put(key, value, { expirationTtl: 3600 })\n *     await this.uploadsCache.put(`upload:${key}`, value)\n *   }\n * }\n * ```\n *\n * @see https://developers.cloudflare.com/kv/api/\n */\n@Transient(CACHE_TOKENS.CacheService)\nexport class CacheService {\n  private kv: KVNamespace\n\n  constructor(\n    @inject(DI_TOKENS.CloudflareEnv) private readonly env: StratalEnv,\n    @inject(LOGGER_TOKENS.LoggerService) private readonly logger: LoggerService\n  ) {\n    this.kv = env.CACHE\n  }\n\n  /**\n   * Set the KV namespace binding\n   *\n   * Used internally by `withBinding()` to configure different KV instances.\n   *\n   * @param kv - KV namespace to use\n   */\n  setKV(kv: KVNamespace): void {\n    this.kv = kv\n  }\n\n  /**\n   * Create a new CacheService instance with a different KV binding\n   *\n   * **Pattern:** Returns a new instance (immutable)\n   *\n   * **Best Practice:** Initialize specialized caches as class properties in constructor\n   *\n   * @example\n   * ```typescript\n   * class MyService {\n   *   private readonly uploadsCache: CacheService\n   *   private readonly systemCache: CacheService\n   *\n   *   constructor(\n   *     @inject(CACHE_TOKENS.CacheService) private readonly cache: CacheService,\n   *     @inject(DI_TOKENS.CloudflareEnv) private readonly env: Env\n   *   ) {\n   *     this.uploadsCache = this.cache.withBinding(this.env.UPLOADS_CACHE)\n   *     this.systemCache = this.cache.withBinding(this.env.SYSTEM_CONFIG_KV)\n   *   }\n   * }\n   * ```\n   *\n   * @param kv - KV namespace to use\n   * @returns New CacheService instance with the specified binding\n   */\n  withBinding(kv: KVNamespace): CacheService {\n    const instance = new CacheService(this.env, this.logger)\n    instance.setKV(kv)\n    return instance\n  }\n\n  // ==================== GET METHODS ====================\n\n  /**\n   * Get a value from cache\n   *\n   * @param key - Cache key\n   * @param typeOrOptions - Type string or options object (defaults to 'text')\n   * @returns Value in specified type, or null if not found\n   * @throws {CacheGetError} If operation fails\n   */\n  async get(key: string, typeOrOptions?: 'text' | KVNamespaceGetOptions<'text'>): Promise<string | null>\n  async get<ExpectedValue = unknown>(key: string, typeOrOptions: 'json' | KVNamespaceGetOptions<'json'>): Promise<ExpectedValue | null>\n  async get(key: string, typeOrOptions: 'arrayBuffer' | KVNamespaceGetOptions<'arrayBuffer'>): Promise<ArrayBuffer | null>\n  async get(key: string, typeOrOptions: 'stream' | KVNamespaceGetOptions<'stream'>): Promise<ReadableStream | null>\n\n  async get<ExpectedValue = unknown>(\n    key: string,\n    typeOrOptions?: string | KVNamespaceGetOptions<'text' | 'json' | 'arrayBuffer' | 'stream'>\n  ): Promise<string | ExpectedValue | ArrayBuffer | ReadableStream | null> {\n    try {\n      if (typeof typeOrOptions === 'string') {\n        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging KV overloaded API\n        return await this.kv.get(key, typeOrOptions as any)\n      }\n\n      if (typeOrOptions) {\n        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging KV overloaded API\n        return await this.kv.get(key, typeOrOptions as any)\n      }\n\n      return await this.kv.get(key)\n    } catch (error) {\n      this.logger.error('Cache get operation failed', { key, error })\n      throw new CacheGetError(key)\n    }\n  }\n\n  // ==================== GET WITH METADATA METHODS ====================\n\n  /**\n   * Get a value with metadata from cache\n   *\n   * @param key - Cache key\n   * @param typeOrOptions - Type string or options object (defaults to 'text')\n   * @returns Object with value, metadata, and cacheStatus\n   * @throws {CacheGetError} If operation fails\n   */\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions?: 'text' | KVNamespaceGetOptions<'text'>\n  ): Promise<KVNamespaceGetWithMetadataResult<string, Metadata>>\n  async getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'json' | KVNamespaceGetOptions<'json'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ExpectedValue, Metadata>>\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'arrayBuffer' | KVNamespaceGetOptions<'arrayBuffer'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ArrayBuffer, Metadata>>\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'stream' | KVNamespaceGetOptions<'stream'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ReadableStream, Metadata>>\n\n  async getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(\n    key: string,\n    typeOrOptions?: string | KVNamespaceGetOptions<'text' | 'json' | 'arrayBuffer' | 'stream'>\n  ): Promise<\n    KVNamespaceGetWithMetadataResult<\n      string | ExpectedValue | ArrayBuffer | ReadableStream,\n      Metadata\n    >\n  > {\n    try {\n      if (typeof typeOrOptions === 'string') {\n        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging KV overloaded API\n        return await this.kv.getWithMetadata(key, typeOrOptions as any)\n      }\n\n      if (typeOrOptions) {\n        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging KV overloaded API\n        return await this.kv.getWithMetadata(key, typeOrOptions as any)\n      }\n\n      return await this.kv.getWithMetadata(key)\n    } catch (error) {\n      this.logger.error('Cache getWithMetadata operation failed', { key, error })\n      throw new CacheGetError(key)\n    }\n  }\n\n  // ==================== PUT METHOD ====================\n\n  /**\n   * Store a value in cache\n   *\n   * @param key - Cache key\n   * @param value - Value to store (string, ArrayBuffer, ArrayBufferView, or ReadableStream)\n   * @param options - Put options (expiration, expirationTtl, metadata)\n   * @throws {CachePutError} If operation fails\n   *\n   * @example\n   * ```typescript\n   * // Simple put\n   * await cache.put('key', 'value')\n   *\n   * // With TTL\n   * await cache.put('key', 'value', { expirationTtl: 3600 })\n   *\n   * // With metadata\n   * await cache.put('key', 'value', { metadata: { created: Date.now() } })\n   * ```\n   */\n  async put(\n    key: string,\n    value: string | ArrayBuffer | ArrayBufferView | ReadableStream,\n    options?: KVNamespacePutOptions\n  ): Promise<void> {\n    try {\n      await this.kv.put(key, value as string, options)\n    } catch (error) {\n      this.logger.error('Cache put operation failed', { key, error })\n      throw new CachePutError(key)\n    }\n  }\n\n  // ==================== DELETE METHODS ====================\n\n  /**\n   * Delete a value from cache\n   *\n   * @param key - Cache key to delete\n   * @throws {CacheDeleteError} If operation fails\n   */\n  async delete(key: string): Promise<void> {\n    try {\n      await this.kv.delete(key)\n    } catch (error) {\n      this.logger.error('Cache delete operation failed', { key, error })\n      throw new CacheDeleteError(key)\n    }\n  }\n\n\n  // ==================== LIST METHOD ====================\n\n  /**\n   * List keys in cache\n   *\n   * @param options - List options (limit, prefix, cursor)\n   * @returns List result with keys and pagination info\n   * @throws {CacheListError} If operation fails\n   *\n   * @example\n   * ```typescript\n   * // List all keys\n   * const result = await cache.list()\n   *\n   * // List with prefix\n   * const result = await cache.list({ prefix: 'user:' })\n   *\n   * // Paginated list\n   * const result = await cache.list({ limit: 100 })\n   * if (!result.list_complete) {\n   *   const nextPage = await cache.list({ cursor: result.cursor })\n   * }\n   * ```\n   */\n  async list<Metadata = unknown>(\n    options?: KVNamespaceListOptions\n  ): Promise<KVNamespaceListResult<Metadata>> {\n    try {\n      return await this.kv.list<Metadata>(options)\n    } catch (error) {\n      this.logger.error('Cache list operation failed', { options, error })\n      throw new CacheListError()\n    }\n  }\n}\n","/**\n * Cache Module\n *\n * Provides key-value caching capabilities using Cloudflare KV namespaces.\n *\n * **Features:**\n * - Type-safe KV wrapper with full method coverage\n * - Multiple KV binding support via `withBinding()`\n * - Automatic error handling with security-focused logging\n * - Singleton service for optimal performance\n */\n\nimport { Module } from '../module'\nimport { CACHE_TOKENS } from './cache.tokens'\nimport { CacheService } from './services'\n\n@Module({\n  providers: [\n    // Singleton - CacheService has no request dependencies\n    { provide: CACHE_TOKENS.CacheService, useClass: CacheService },\n  ],\n})\nexport class CacheModule {}\n"],"mappings":";;;;;;;;;;;;AASA,IAAa,gBAAb,cAAmC,iBAAiB;CAClD,YAAY,KAAa;EACvB,MAAM,0BAA0B,YAAY,OAAO,sBAAsB,EAAE,KAAK,CAAC;;;;;;;;;;;ACFrF,IAAa,gBAAb,cAAmC,iBAAiB;CAClD,YAAY,KAAa;EACvB,MAAM,0BAA0B,YAAY,OAAO,sBAAsB,EAAE,KAAK,CAAC;;;;;;;;;;;ACFrF,IAAa,mBAAb,cAAsC,iBAAiB;CACrD,YAAY,KAAa;EACvB,MAAM,6BAA6B,YAAY,OAAO,sBAAsB,EAAE,KAAK,CAAC;;;;;;;;;;ACHxF,IAAa,iBAAb,cAAoC,iBAAiB;CACnD,cAAc;EACZ,MAAM,2BAA2B,YAAY,OAAO,sBAAsB,EAAE,CAAC;;;;;;ACqC1E,IAAA,eAAA,gBAAA,MAAM,aAAa;CAI4B;CACI;CAJxD;CAEA,YACE,KACA,QACA;EAFkD,KAAA,MAAA;EACI,KAAA,SAAA;EAEtD,KAAK,KAAK,IAAI;;;;;;;;;CAUhB,MAAM,IAAuB;EAC3B,KAAK,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BZ,YAAY,IAA+B;EACzC,MAAM,WAAW,IAAA,cAAiB,KAAK,KAAK,KAAK,OAAO;EACxD,SAAS,MAAM,GAAG;EAClB,OAAO;;CAkBT,MAAM,IACJ,KACA,eACuE;EACvE,IAAI;GACF,IAAI,OAAO,kBAAkB,UAE3B,OAAO,MAAM,KAAK,GAAG,IAAI,KAAK,cAAqB;GAGrD,IAAI,eAEF,OAAO,MAAM,KAAK,GAAG,IAAI,KAAK,cAAqB;GAGrD,OAAO,MAAM,KAAK,GAAG,IAAI,IAAI;WACtB,OAAO;GACd,KAAK,OAAO,MAAM,8BAA8B;IAAE;IAAK;IAAO,CAAC;GAC/D,MAAM,IAAI,cAAc,IAAI;;;CA+BhC,MAAM,gBACJ,KACA,eAMA;EACA,IAAI;GACF,IAAI,OAAO,kBAAkB,UAE3B,OAAO,MAAM,KAAK,GAAG,gBAAgB,KAAK,cAAqB;GAGjE,IAAI,eAEF,OAAO,MAAM,KAAK,GAAG,gBAAgB,KAAK,cAAqB;GAGjE,OAAO,MAAM,KAAK,GAAG,gBAAgB,IAAI;WAClC,OAAO;GACd,KAAK,OAAO,MAAM,0CAA0C;IAAE;IAAK;IAAO,CAAC;GAC3E,MAAM,IAAI,cAAc,IAAI;;;;;;;;;;;;;;;;;;;;;;;CA0BhC,MAAM,IACJ,KACA,OACA,SACe;EACf,IAAI;GACF,MAAM,KAAK,GAAG,IAAI,KAAK,OAAiB,QAAQ;WACzC,OAAO;GACd,KAAK,OAAO,MAAM,8BAA8B;IAAE;IAAK;IAAO,CAAC;GAC/D,MAAM,IAAI,cAAc,IAAI;;;;;;;;;CAYhC,MAAM,OAAO,KAA4B;EACvC,IAAI;GACF,MAAM,KAAK,GAAG,OAAO,IAAI;WAClB,OAAO;GACd,KAAK,OAAO,MAAM,iCAAiC;IAAE;IAAK;IAAO,CAAC;GAClE,MAAM,IAAI,iBAAiB,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;CA6BnC,MAAM,KACJ,SAC0C;EAC1C,IAAI;GACF,OAAO,MAAM,KAAK,GAAG,KAAe,QAAQ;WACrC,OAAO;GACd,KAAK,OAAO,MAAM,+BAA+B;IAAE;IAAS;IAAO,CAAC;GACpE,MAAM,IAAI,gBAAgB;;;;;CArO/B,UAAU,aAAa,aAAa;oBAKhC,OAAO,UAAU,cAAc,CAAA;oBAC/B,OAAO,cAAc,cAAc,CAAA;;;;;;;;;;;;;;;;AC9BjC,IAAA,cAAA,MAAM,YAAY;0BANxB,OAAO,EACN,WAAW,CAET;CAAE,SAAS,aAAa;CAAc,UAAU;CAAc,CAC/D,EACF,CAAC,CAAA,EAAA,YAAA"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/cache/cache.error.ts","../../src/cache/cache.tokens.ts","../../src/cache/services/cache.service.ts","../../src/cache/services/tiered-cache.service.ts","../../src/cache/cache.module.ts"],"sourcesContent":["import { ApplicationError } from '../errors'\n\nexport class CacheError extends ApplicationError {}\n","export const CACHE_TOKENS = {\n  CacheService: Symbol.for('stratal:cache:service'),\n  TieredCacheService: Symbol.for('stratal:cache:tiered-service'),\n} as const\n\nexport type CacheToken = (typeof CACHE_TOKENS)[keyof typeof CACHE_TOKENS]\n","import { inject } from '../../di'\nimport { Singleton } from '../../di/decorators'\nimport { DI_TOKENS } from '../../di/tokens'\nimport { type StratalEnv } from '../../env'\nimport { LOGGER_TOKENS, type LoggerService } from '../../logger'\nimport { CACHE_TOKENS } from '../cache.tokens'\nimport { CacheError } from '../cache.error'\n\n/**\n * Cache Service\n *\n * Type-safe wrapper around Cloudflare KV namespaces for caching operations.\n *\n * Reads are eventually consistent — KV may serve an edge-cached value for up to\n * ~60s after a write. When you need isolate-local read-after-write coherence\n * (e.g. set-once markers like queue idempotency keys), opt into\n * {@link TieredCacheService}, which layers an isolate-local L1 over this\n * service. Do **not** use the L1 tier for read-modify-write counters that need\n * cross-edge freshness (e.g. rate limiting) — plain KV is the correct primitive\n * there.\n *\n * **Features:**\n * - Mirrors all KVNamespace methods with full type safety\n * - Supports multiple KV bindings via `withBinding()` / `binding(name)`\n * - Automatic error handling with logging\n * - Security: Raw errors are logged, not exposed to users\n *\n * **Usage:**\n * ```typescript\n * class MyService {\n *   private readonly uploadsCache: CacheService\n *\n *   constructor(\n *     @inject(CACHE_TOKENS.CacheService) private readonly cache: CacheService,\n *   ) {\n *     // Initialize specialized caches in constructor\n *     this.uploadsCache = this.cache.binding('UPLOADS_CACHE')\n *   }\n *\n *   async cacheData(key: string, value: string) {\n *     await this.cache.put(key, value, { expirationTtl: 3600 })\n *     await this.uploadsCache.put(`upload:${key}`, value)\n *   }\n * }\n * ```\n *\n * @see https://developers.cloudflare.com/kv/api/\n */\n@Singleton(CACHE_TOKENS.CacheService)\nexport class CacheService {\n  private kv: KVNamespace\n\n  constructor(\n    @inject(DI_TOKENS.CloudflareEnv) private readonly env: StratalEnv,\n    @inject(LOGGER_TOKENS.LoggerService) private readonly logger: LoggerService\n  ) {\n    this.kv = env.CACHE\n  }\n\n  /** The KV namespace this instance is bound to. */\n  get namespace(): KVNamespace {\n    return this.kv\n  }\n\n  /**\n   * Create a new CacheService instance bound to a different KV namespace.\n   *\n   * @param kv - KV namespace to use\n   * @returns A new CacheService for the given binding\n   */\n  withBinding(kv: KVNamespace): CacheService {\n    const instance = new CacheService(this.env, this.logger)\n    instance.kv = kv\n    return instance\n  }\n\n  /**\n   * Create a new CacheService instance bound to a KV namespace by its binding\n   * name, resolved from the environment.\n   *\n   * @param name - KV namespace binding name (e.g. `'UPLOADS_CACHE'`)\n   * @returns A new CacheService for the given binding\n   * @throws {CacheError} If no binding with that name exists in the environment\n   */\n  binding(name: string): CacheService {\n    const kv = (this.env as unknown as Record<string, unknown>)[name] as KVNamespace | undefined\n    if (!kv) {\n      throw new CacheError(`KV binding \"${name}\" was not found in the environment`)\n    }\n    return this.withBinding(kv)\n  }\n\n  // ==================== GET METHODS ====================\n\n  /**\n   * Get a value from cache\n   *\n   * @param key - Cache key\n   * @param typeOrOptions - Type string or options object (defaults to 'text')\n   * @returns Value in specified type, or null if not found\n   * @throws {CacheError} If operation fails\n   */\n  async get(key: string, typeOrOptions?: 'text' | KVNamespaceGetOptions<'text'>): Promise<string | null>\n  async get<ExpectedValue = unknown>(key: string, typeOrOptions: 'json' | KVNamespaceGetOptions<'json'>): Promise<ExpectedValue | null>\n  async get(key: string, typeOrOptions: 'arrayBuffer' | KVNamespaceGetOptions<'arrayBuffer'>): Promise<ArrayBuffer | null>\n  async get(key: string, typeOrOptions: 'stream' | KVNamespaceGetOptions<'stream'>): Promise<ReadableStream | null>\n\n  async get<ExpectedValue = unknown>(\n    key: string,\n    typeOrOptions?: string | KVNamespaceGetOptions<'text' | 'json' | 'arrayBuffer' | 'stream'>\n  ): Promise<string | ExpectedValue | ArrayBuffer | ReadableStream | null> {\n    try {\n      if (typeof typeOrOptions === 'string') {\n        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging KV overloaded API\n        return await this.kv.get(key, typeOrOptions as any)\n      }\n\n      if (typeOrOptions) {\n        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging KV overloaded API\n        return await this.kv.get(key, typeOrOptions as any)\n      }\n\n      return await this.kv.get(key)\n    } catch (error) {\n      this.logger.error('Cache get operation failed', { key, error })\n      throw new CacheError(`Failed to get cache key \"${key}\"`)\n    }\n  }\n\n  // ==================== GET WITH METADATA METHODS ====================\n\n  /**\n   * Get a value with metadata from cache\n   *\n   * @param key - Cache key\n   * @param typeOrOptions - Type string or options object (defaults to 'text')\n   * @returns Object with value, metadata, and cacheStatus\n   * @throws {CacheError} If operation fails\n   */\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions?: 'text' | KVNamespaceGetOptions<'text'>\n  ): Promise<KVNamespaceGetWithMetadataResult<string, Metadata>>\n  async getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'json' | KVNamespaceGetOptions<'json'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ExpectedValue, Metadata>>\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'arrayBuffer' | KVNamespaceGetOptions<'arrayBuffer'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ArrayBuffer, Metadata>>\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'stream' | KVNamespaceGetOptions<'stream'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ReadableStream, Metadata>>\n\n  async getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(\n    key: string,\n    typeOrOptions?: string | KVNamespaceGetOptions<'text' | 'json' | 'arrayBuffer' | 'stream'>\n  ): Promise<\n    KVNamespaceGetWithMetadataResult<\n      string | ExpectedValue | ArrayBuffer | ReadableStream,\n      Metadata\n    >\n  > {\n    try {\n      if (typeof typeOrOptions === 'string') {\n        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging KV overloaded API\n        return await this.kv.getWithMetadata(key, typeOrOptions as any)\n      }\n\n      if (typeOrOptions) {\n        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging KV overloaded API\n        return await this.kv.getWithMetadata(key, typeOrOptions as any)\n      }\n\n      return await this.kv.getWithMetadata(key)\n    } catch (error) {\n      this.logger.error('Cache getWithMetadata operation failed', { key, error })\n      throw new CacheError(`Failed to get cache key \"${key}\"`)\n    }\n  }\n\n  // ==================== PUT METHOD ====================\n\n  /**\n   * Store a value in cache\n   *\n   * @param key - Cache key\n   * @param value - Value to store (string, ArrayBuffer, ArrayBufferView, or ReadableStream)\n   * @param options - Put options (expiration, expirationTtl, metadata)\n   * @throws {CacheError} If operation fails\n   *\n   * @example\n   * ```typescript\n   * // Simple put\n   * await cache.put('key', 'value')\n   *\n   * // With TTL\n   * await cache.put('key', 'value', { expirationTtl: 3600 })\n   *\n   * // With metadata\n   * await cache.put('key', 'value', { metadata: { created: Date.now() } })\n   * ```\n   */\n  async put(\n    key: string,\n    value: string | ArrayBuffer | ArrayBufferView | ReadableStream,\n    options?: KVNamespacePutOptions\n  ): Promise<void> {\n    try {\n      await this.kv.put(key, value as string, options)\n    } catch (error) {\n      this.logger.error('Cache put operation failed', { key, error })\n      throw new CacheError(`Failed to store cache key \"${key}\"`)\n    }\n  }\n\n  // ==================== DELETE METHODS ====================\n\n  /**\n   * Delete a value from cache\n   *\n   * @param key - Cache key to delete\n   * @throws {CacheError} If operation fails\n   */\n  async delete(key: string): Promise<void> {\n    try {\n      await this.kv.delete(key)\n    } catch (error) {\n      this.logger.error('Cache delete operation failed', { key, error })\n      throw new CacheError(`Failed to delete cache key \"${key}\"`)\n    }\n  }\n\n\n  // ==================== LIST METHOD ====================\n\n  /**\n   * List keys in cache\n   *\n   * @param options - List options (limit, prefix, cursor)\n   * @returns List result with keys and pagination info\n   * @throws {CacheError} If operation fails\n   *\n   * @example\n   * ```typescript\n   * // List all keys\n   * const result = await cache.list()\n   *\n   * // List with prefix\n   * const result = await cache.list({ prefix: 'user:' })\n   *\n   * // Paginated list\n   * const result = await cache.list({ limit: 100 })\n   * if (!result.list_complete) {\n   *   const nextPage = await cache.list({ cursor: result.cursor })\n   * }\n   * ```\n   */\n  async list<Metadata = unknown>(\n    options?: KVNamespaceListOptions\n  ): Promise<KVNamespaceListResult<Metadata>> {\n    try {\n      return await this.kv.list<Metadata>(options)\n    } catch (error) {\n      this.logger.error('Cache list operation failed', { options, error })\n      throw new CacheError('Failed to list cache keys')\n    }\n  }\n}\n","import { inject } from '../../di'\nimport { Singleton } from '../../di/decorators'\nimport { CACHE_TOKENS } from '../cache.tokens'\nimport type { CacheService } from './cache.service'\n\n/** A value held in the isolate-local L1 tier. */\ninterface L1Entry {\n  /** The raw string value, exactly as it is (or would be) stored in KV. */\n  value: string\n  /** Absolute expiry in epoch milliseconds, or `null` for no expiry. */\n  expiresAt: number | null\n}\n\n/**\n * Max entries kept in the isolate-local L1 before the oldest is evicted (FIFO).\n * Bounds memory per isolate; KV remains the unbounded source of truth.\n */\nconst L1_MAX_ENTRIES = 1000\n\n/**\n * Tiered Cache Service\n *\n * Layers an **isolate-local in-memory L1** over {@link CacheService} (KV, the\n * L2). Opt-in — inject `CACHE_TOKENS.TieredCacheService` instead of\n * `CACHE_TOKENS.CacheService` when you want it.\n *\n * **Why:** KV reads are eventually consistent (a `get` can return an\n * edge-cached value for up to ~60s after a `put`). The L1 makes writes made\n * through *this isolate* immediately and consistently visible to subsequent\n * reads on the same isolate — closing the read-after-write gap KV alone cannot.\n * This is what makes set-once patterns (e.g. queue idempotency markers) reliable\n * within an isolate, even inside KV's consistency window.\n *\n * **Use it for:** set-once / read-mostly values (idempotency claims, immutable\n * lookups). **Do not use it for** read-modify-write counters that need\n * cross-edge freshness (e.g. rate limiting): an isolate that wrote a key reads\n * its own value until the L1 entry expires, so concurrent increments from other\n * isolates are missed and overwritten. Use plain {@link CacheService} (KV) or a\n * Durable-Object store for those.\n *\n * **Semantics:**\n * - L1 caches string-backed values only (`text`/`json`). `arrayBuffer`/`stream`\n *   reads and non-string writes bypass and invalidate L1.\n * - `put`/`delete` are write-through: KV and L1 update in lock-step, honoring\n *   `expirationTtl`/`expiration` for the L1 entry's own expiry.\n * - `get` populates L1 from `text` reads (the only path that yields the raw\n *   string). `json` reads are served from L1 when the string was cached by a\n *   prior `put`/`text` read, otherwise they go straight to KV.\n * - `getWithMetadata` and `list` always read KV directly (metadata is not held\n *   in L1).\n *\n * **Cross-isolate caveat:** the L1 only observes writes made through its own\n * isolate. A value mutated by another isolate is not seen until the local entry\n * expires or is invalidated by a local write/delete.\n *\n * **Bindings:** `binding(name)` returns a memoized tiered instance per binding,\n * so each KV namespace has its own stable, isolate-lifetime L1.\n */\n@Singleton(CACHE_TOKENS.TieredCacheService)\nexport class TieredCacheService {\n  /** Isolate-local L1 tier. Per-instance, so each binding has its own. */\n  private readonly l1 = new Map<string, L1Entry>()\n  /** Memoized tiered instances per binding name (each with its own L1). */\n  private readonly children = new Map<string, TieredCacheService>()\n\n  constructor(\n    @inject(CACHE_TOKENS.CacheService) private readonly cache: CacheService\n  ) {}\n\n  /**\n   * Get the tiered cache bound to a KV namespace by its binding name. Memoized:\n   * repeated calls with the same name return the same instance, preserving its\n   * isolate-local L1 across requests/messages.\n   *\n   * @param name - KV namespace binding name (e.g. `'UPLOADS_CACHE'`)\n   * @throws {CacheError} If no binding with that name exists in the environment\n   */\n  binding(name: string): TieredCacheService {\n    let child = this.children.get(name)\n    if (child === undefined) {\n      child = new TieredCacheService(this.cache.binding(name))\n      this.children.set(name, child)\n    }\n    return child\n  }\n\n  // ==================== GET ====================\n\n  async get(key: string, typeOrOptions?: 'text' | KVNamespaceGetOptions<'text'>): Promise<string | null>\n  async get<ExpectedValue = unknown>(key: string, typeOrOptions: 'json' | KVNamespaceGetOptions<'json'>): Promise<ExpectedValue | null>\n  async get(key: string, typeOrOptions: 'arrayBuffer' | KVNamespaceGetOptions<'arrayBuffer'>): Promise<ArrayBuffer | null>\n  async get(key: string, typeOrOptions: 'stream' | KVNamespaceGetOptions<'stream'>): Promise<ReadableStream | null>\n\n  async get<ExpectedValue = unknown>(\n    key: string,\n    typeOrOptions?: string | KVNamespaceGetOptions<'text' | 'json' | 'arrayBuffer' | 'stream'>\n  ): Promise<string | ExpectedValue | ArrayBuffer | ReadableStream | null> {\n    const type = typeof typeOrOptions === 'string'\n      ? typeOrOptions\n      : typeOrOptions?.type ?? 'text'\n\n    // L1 holds string-backed values only. Serve text/json from it when present.\n    if (type === 'text' || type === 'json') {\n      const cached = this.l1Read(key)\n      if (cached !== null) {\n        return type === 'json' ? (JSON.parse(cached) as ExpectedValue) : cached\n      }\n    }\n\n    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging the typed CacheService.get overloads\n    const value = await this.cache.get<ExpectedValue>(key, typeOrOptions as any)\n\n    // Only `text` reads yield the raw string we can cache; back-populate L1.\n    if (type === 'text' && typeof value === 'string') {\n      this.l1Write(key, value, null)\n    }\n\n    return value\n  }\n\n  // ==================== GET WITH METADATA (KV-direct) ====================\n\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions?: 'text' | KVNamespaceGetOptions<'text'>\n  ): Promise<KVNamespaceGetWithMetadataResult<string, Metadata>>\n  async getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'json' | KVNamespaceGetOptions<'json'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ExpectedValue, Metadata>>\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'arrayBuffer' | KVNamespaceGetOptions<'arrayBuffer'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ArrayBuffer, Metadata>>\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'stream' | KVNamespaceGetOptions<'stream'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ReadableStream, Metadata>>\n\n  async getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(\n    key: string,\n    typeOrOptions?: string | KVNamespaceGetOptions<'text' | 'json' | 'arrayBuffer' | 'stream'>\n  ): Promise<\n    KVNamespaceGetWithMetadataResult<\n      string | ExpectedValue | ArrayBuffer | ReadableStream,\n      Metadata\n    >\n  > {\n    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging the typed CacheService.getWithMetadata overloads\n    return this.cache.getWithMetadata<ExpectedValue, Metadata>(key, typeOrOptions as any)\n  }\n\n  // ==================== PUT (write-through) ====================\n\n  async put(\n    key: string,\n    value: string | ArrayBuffer | ArrayBufferView | ReadableStream,\n    options?: KVNamespacePutOptions\n  ): Promise<void> {\n    await this.cache.put(key, value, options)\n    // Write-through: cache strings in L1; invalidate for binary values, which\n    // L1 does not hold.\n    if (typeof value === 'string') {\n      this.l1Write(key, value, this.l1ExpiresAt(options))\n    } else {\n      this.l1.delete(key)\n    }\n  }\n\n  // ==================== DELETE (write-through) ====================\n\n  async delete(key: string): Promise<void> {\n    await this.cache.delete(key)\n    this.l1.delete(key)\n  }\n\n  // ==================== LIST (KV-direct) ====================\n\n  async list<Metadata = unknown>(\n    options?: KVNamespaceListOptions\n  ): Promise<KVNamespaceListResult<Metadata>> {\n    return this.cache.list<Metadata>(options)\n  }\n\n  // ==================== L1 TIER ====================\n\n  /** Read a fresh L1 entry, evicting it if expired. Returns `null` on miss. */\n  private l1Read(key: string): string | null {\n    const entry = this.l1.get(key)\n    if (entry === undefined) return null\n    if (entry.expiresAt !== null && Date.now() >= entry.expiresAt) {\n      this.l1.delete(key)\n      return null\n    }\n    return entry.value\n  }\n\n  /** Write an L1 entry, refreshing its recency and evicting the oldest at cap. */\n  private l1Write(key: string, value: string, expiresAt: number | null): void {\n    // Re-insert so the most recently written key is youngest in iteration order.\n    this.l1.delete(key)\n    if (this.l1.size >= L1_MAX_ENTRIES) {\n      const oldest = this.l1.keys().next().value\n      if (oldest !== undefined) this.l1.delete(oldest)\n    }\n    this.l1.set(key, { value, expiresAt })\n  }\n\n  /** Compute an absolute L1 expiry (epoch ms) from KV put options. */\n  private l1ExpiresAt(options?: KVNamespacePutOptions): number | null {\n    if (options?.expiration !== undefined) return options.expiration * 1000\n    if (options?.expirationTtl !== undefined) return Date.now() + options.expirationTtl * 1000\n    return null\n  }\n}\n","/**\n * Cache Module\n *\n * Provides key-value caching capabilities using Cloudflare KV namespaces.\n *\n * **Features:**\n * - Type-safe KV wrapper with full method coverage\n * - Multiple KV binding support via `withBinding()`\n * - Automatic error handling with security-focused logging\n * - Singleton service for optimal performance\n */\n\nimport { Module } from '../module'\nimport { CACHE_TOKENS } from './cache.tokens'\nimport { CacheService, TieredCacheService } from './services'\n\n@Module({\n  providers: [\n    // Singleton - CacheService has no request dependencies\n    { provide: CACHE_TOKENS.CacheService, useClass: CacheService },\n    // Opt-in isolate-local L1 over CacheService (for set-once/read-mostly keys)\n    { provide: CACHE_TOKENS.TieredCacheService, useClass: TieredCacheService },\n  ],\n})\nexport class CacheModule {}\n"],"mappings":"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"}

package/dist/{cache.service-DsnKuNyO.d.mts → cache.service-uElmBtdS.d.mts}

@@ -1,5 +1,5 @@
-import { t as StratalEnv } from "./env-D1rcZ8_r.mjs";
-import { i as LoggerService } from "./index-DBd_2wv8.mjs";
+import { t as StratalEnv } from "./env-ug22bJj7.mjs";
+import { r as LoggerService } from "./index-BUt92sAE.mjs";
 
 //#region src/cache/services/cache.service.d.ts
 /**
@@ -7,9 +7,17 @@ import { i as LoggerService } from "./index-DBd_2wv8.mjs";
  *
  * Type-safe wrapper around Cloudflare KV namespaces for caching operations.
  *
+ * Reads are eventually consistent — KV may serve an edge-cached value for up to
+ * ~60s after a write. When you need isolate-local read-after-write coherence
+ * (e.g. set-once markers like queue idempotency keys), opt into
+ * {@link TieredCacheService}, which layers an isolate-local L1 over this
+ * service. Do **not** use the L1 tier for read-modify-write counters that need
+ * cross-edge freshness (e.g. rate limiting) — plain KV is the correct primitive
+ * there.
+ *
  * **Features:**
  * - Mirrors all KVNamespace methods with full type safety
- * - Supports multiple KV bindings via `withBinding()`
+ * - Supports multiple KV bindings via `withBinding()` / `binding(name)`
  * - Automatic error handling with logging
  * - Security: Raw errors are logged, not exposed to users
  *
@@ -20,10 +28,9 @@ import { i as LoggerService } from "./index-DBd_2wv8.mjs";
  *
  *   constructor(
  *     @inject(CACHE_TOKENS.CacheService) private readonly cache: CacheService,
- *     @inject(DI_TOKENS.CloudflareEnv) private readonly env: Env
  *   ) {
  *     // Initialize specialized caches in constructor
- *     this.uploadsCache = this.cache.withBinding(this.env.UPLOADS_CACHE)
+ *     this.uploadsCache = this.cache.binding('UPLOADS_CACHE')
  *   }
  *
  *   async cacheData(key: string, value: string) {
@@ -40,48 +47,31 @@ declare class CacheService {
   private readonly logger;
   private kv;
   constructor(env: StratalEnv, logger: LoggerService);
+  /** The KV namespace this instance is bound to. */
+  get namespace(): KVNamespace;
   /**
-   * Set the KV namespace binding
-   *
-   * Used internally by `withBinding()` to configure different KV instances.
+   * Create a new CacheService instance bound to a different KV namespace.
    *
    * @param kv - KV namespace to use
+   * @returns A new CacheService for the given binding
    */
-  setKV(kv: KVNamespace): void;
+  withBinding(kv: KVNamespace): CacheService;
   /**
-   * Create a new CacheService instance with a different KV binding
-   *
-   * **Pattern:** Returns a new instance (immutable)
+   * Create a new CacheService instance bound to a KV namespace by its binding
+   * name, resolved from the environment.
    *
-   * **Best Practice:** Initialize specialized caches as class properties in constructor
-   *
-   * @example
-   * ```typescript
-   * class MyService {
-   *   private readonly uploadsCache: CacheService
-   *   private readonly systemCache: CacheService
-   *
-   *   constructor(
-   *     @inject(CACHE_TOKENS.CacheService) private readonly cache: CacheService,
-   *     @inject(DI_TOKENS.CloudflareEnv) private readonly env: Env
-   *   ) {
-   *     this.uploadsCache = this.cache.withBinding(this.env.UPLOADS_CACHE)
-   *     this.systemCache = this.cache.withBinding(this.env.SYSTEM_CONFIG_KV)
-   *   }
-   * }
-   * ```
-   *
-   * @param kv - KV namespace to use
-   * @returns New CacheService instance with the specified binding
+   * @param name - KV namespace binding name (e.g. `'UPLOADS_CACHE'`)
+   * @returns A new CacheService for the given binding
+   * @throws {CacheError} If no binding with that name exists in the environment
    */
-  withBinding(kv: KVNamespace): CacheService;
+  binding(name: string): CacheService;
   /**
    * Get a value from cache
    *
    * @param key - Cache key
    * @param typeOrOptions - Type string or options object (defaults to 'text')
    * @returns Value in specified type, or null if not found
-   * @throws {CacheGetError} If operation fails
+   * @throws {CacheError} If operation fails
    */
   get(key: string, typeOrOptions?: 'text' | KVNamespaceGetOptions<'text'>): Promise<string | null>;
   get<ExpectedValue = unknown>(key: string, typeOrOptions: 'json' | KVNamespaceGetOptions<'json'>): Promise<ExpectedValue | null>;
@@ -93,7 +83,7 @@ declare class CacheService {
    * @param key - Cache key
    * @param typeOrOptions - Type string or options object (defaults to 'text')
    * @returns Object with value, metadata, and cacheStatus
-   * @throws {CacheGetError} If operation fails
+   * @throws {CacheError} If operation fails
    */
   getWithMetadata<Metadata = unknown>(key: string, typeOrOptions?: 'text' | KVNamespaceGetOptions<'text'>): Promise<KVNamespaceGetWithMetadataResult<string, Metadata>>;
   getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(key: string, typeOrOptions: 'json' | KVNamespaceGetOptions<'json'>): Promise<KVNamespaceGetWithMetadataResult<ExpectedValue, Metadata>>;
@@ -105,7 +95,7 @@ declare class CacheService {
    * @param key - Cache key
    * @param value - Value to store (string, ArrayBuffer, ArrayBufferView, or ReadableStream)
    * @param options - Put options (expiration, expirationTtl, metadata)
-   * @throws {CachePutError} If operation fails
+   * @throws {CacheError} If operation fails
    *
    * @example
    * ```typescript
@@ -124,7 +114,7 @@ declare class CacheService {
    * Delete a value from cache
    *
    * @param key - Cache key to delete
-   * @throws {CacheDeleteError} If operation fails
+   * @throws {CacheError} If operation fails
    */
   delete(key: string): Promise<void>;
   /**
@@ -132,7 +122,7 @@ declare class CacheService {
    *
    * @param options - List options (limit, prefix, cursor)
    * @returns List result with keys and pagination info
-   * @throws {CacheListError} If operation fails
+   * @throws {CacheError} If operation fails
    *
    * @example
    * ```typescript
@@ -153,4 +143,4 @@ declare class CacheService {
 }
 //#endregion
 export { CacheService as t };
-//# sourceMappingURL=cache.service-DsnKuNyO.d.mts.map
+//# sourceMappingURL=cache.service-uElmBtdS.d.mts.map

package/dist/cache.service-uElmBtdS.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.service-uElmBtdS.d.mts","names":[],"sources":["../src/cache/services/cache.service.ts"],"mappings":";;;;;;AAgDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cACa,YAAA;EAAA,iBAIyC,GAAA;EAAA,iBACI,MAAA;EAAA,QAJhD,EAAA;cAG4C,GAAA,EAAK,UAAA,EACD,MAAA,EAAQ,aAAA;EA2J7D;EAAA,IArJC,SAAA,IAAa,WAAA;EAyML;;;;;;EA/LZ,WAAA,CAAY,EAAA,EAAI,WAAA,GAAc,YAAA;EAhB0B;;;;;;;;EA8BxD,OAAA,CAAQ,IAAA,WAAe,YAAA;EAdvB;;;;;;;;EAgCM,GAAA,CAAI,GAAA,UAAa,aAAA,YAAyB,qBAAA,WAAgC,OAAA;EAC1E,GAAA,0BAA6B,GAAA,UAAa,aAAA,WAAwB,qBAAA,WAAgC,OAAA,CAAQ,aAAA;EAC1G,GAAA,CAAI,GAAA,UAAa,aAAA,kBAA+B,qBAAA,kBAAuC,OAAA,CAAQ,WAAA;EAC/F,GAAA,CAAI,GAAA,UAAa,aAAA,aAA0B,qBAAA,aAAkC,OAAA,CAAQ,cAAA;EAFrF;;;;;;;;EAoCA,eAAA,qBACJ,GAAA,UACA,aAAA,YAAyB,qBAAA,WACxB,OAAA,CAAQ,gCAAA,SAAyC,QAAA;EAC9C,eAAA,8CACJ,GAAA,UACA,aAAA,WAAwB,qBAAA,WACvB,OAAA,CAAQ,gCAAA,CAAiC,aAAA,EAAe,QAAA;EACrD,eAAA,qBACJ,GAAA,UACA,aAAA,kBAA+B,qBAAA,kBAC9B,OAAA,CAAQ,gCAAA,CAAiC,WAAA,EAAa,QAAA;EACnD,eAAA,qBACJ,GAAA,UACA,aAAA,aAA0B,qBAAA,aACzB,OAAA,CAAQ,gCAAA,CAAiC,cAAA,EAAgB,QAAA;EAlDyC;;;;;;;;;;;;;;;;;;;;EAqG/F,GAAA,CACJ,GAAA,UACA,KAAA,WAAgB,WAAA,GAAc,eAAA,GAAkB,cAAA,EAChD,OAAA,GAAU,qBAAA,GACT,OAAA;EA/DA;;;;;;EAgFG,MAAA,CAAO,GAAA,WAAc,OAAA;EA7EM;;;;;;;;;;;;;;;;;;;;;;EA+G3B,IAAA,qBACJ,OAAA,GAAU,sBAAA,GACT,OAAA,CAAQ,qBAAA,CAAsB,QAAA;AAAA"}

package/dist/{command-BgSlsS4M.mjs → command-BvmUAPPQ.mjs}

@@ -1,5 +1,16 @@
-import { a as green, n as cyan, o as red, r as dim, s as yellow, t as bold } from "./colors-DJaRDXoS.mjs";
-import "reflect-metadata";
+//#region src/quarry/colors.ts
+/** Minimal ANSI color helpers that respect the `NO_COLOR` convention. */
+const isEnabled = () => typeof process !== "undefined" ? !process.env.NO_COLOR : true;
+/** Create an ANSI formatter that wraps text with the given open/close SGR codes. */
+const code = (open, close) => (s) => isEnabled() ? `\x1b[${open}m${s}\x1b[${close}m` : s;
+const bold = code(1, 22);
+const dim = code(2, 22);
+const cyan = code(36, 39);
+const green = code(32, 39);
+const red = code(31, 39);
+const yellow = code(33, 39);
+const dimWhite = (s) => isEnabled() ? `\x1b[2;37m${s}\x1b[22;39m` : s;
+//#endregion
 //#region src/quarry/constants.ts
 /**
 * Symbol key for storing internal mutable state on Command instances.
@@ -191,6 +202,6 @@ var Command = class {
 	}
 };
 //#endregion
-export { CommandError as n, COMMAND_INTERNALS as r, Command as t };
+export { cyan as a, green as c, bold as i, red as l, CommandError as n, dim as o, COMMAND_INTERNALS as r, dimWhite as s, Command as t, yellow as u };
 
-//# sourceMappingURL=command-BgSlsS4M.mjs.map
+//# sourceMappingURL=command-BvmUAPPQ.mjs.map