stratal 0.0.12 → 0.0.14

package/README.md

@@ -56,7 +56,7 @@ Available templates:
 | `middleware` | Middleware configuration with apply/exclude/forRoutes | [Source](https://github.com/strataljs/stratal/tree/main/examples/05-middleware) |
 | `queues` | Queue producer/consumer pattern with Cloudflare Queues | [Source](https://github.com/strataljs/stratal/tree/main/examples/06-queues) |
 | `scheduled-tasks` | Cron job scheduling with the CronJob interface | [Source](https://github.com/strataljs/stratal/tree/main/examples/07-scheduled-tasks) |
-| `openapi` | OpenAPI docs with Scalar UI and Zod schema integration | [Source](https://github.com/strataljs/stratal/tree/main/examples/08-openapi) |
+| `openapi` | OpenAPI docs with Swagger UI and Zod schema integration | [Source](https://github.com/strataljs/stratal/tree/main/examples/08-openapi) |
 
 For benchmarks, see the [main README](https://github.com/strataljs/stratal#benchmarks).
 

package/dist/base-email.provider-bzdAYp8Z.mjs

@@ -0,0 +1,42 @@
+//#region src/email/providers/base-email.provider.ts
+/**
+* Base Email Provider
+*
+* Abstract base class for email providers.
+* Provides shared implementation of sendBatch() to reduce code duplication.
+*/
+var BaseEmailProvider = class {
+	/**
+	* Send multiple emails in a batch
+	*
+	* Default implementation sends emails sequentially.
+	* Concrete providers can override for optimized batch sending.
+	*/
+	async sendBatch(messages) {
+		const results = [];
+		let successful = 0;
+		let failed = 0;
+		for (const message of messages) try {
+			const result = await this.send(message);
+			results.push(result);
+			successful++;
+		} catch (error) {
+			results.push({
+				messageId: "",
+				accepted: false,
+				metadata: { error: error instanceof Error ? error.message : "Unknown error" }
+			});
+			failed++;
+		}
+		return {
+			total: messages.length,
+			successful,
+			failed,
+			results
+		};
+	}
+};
+//#endregion
+export { BaseEmailProvider as t };
+
+//# sourceMappingURL=base-email.provider-bzdAYp8Z.mjs.map

package/dist/base-email.provider-bzdAYp8Z.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-email.provider-bzdAYp8Z.mjs","names":[],"sources":["../src/email/providers/base-email.provider.ts"],"sourcesContent":["import type { ResolvedEmailMessage } from '../contracts'\nimport type { EmailBatchSendResult, EmailSendResult, IEmailProvider } from './email-provider.interface'\n\n/**\n * Base Email Provider\n *\n * Abstract base class for email providers.\n * Provides shared implementation of sendBatch() to reduce code duplication.\n */\nexport abstract class BaseEmailProvider implements IEmailProvider {\n  /**\n   * Send a single email - must be implemented by concrete providers\n   */\n  abstract send(message: ResolvedEmailMessage): Promise<EmailSendResult>\n\n  /**\n   * Send multiple emails in a batch\n   *\n   * Default implementation sends emails sequentially.\n   * Concrete providers can override for optimized batch sending.\n   */\n  async sendBatch(messages: ResolvedEmailMessage[]): Promise<EmailBatchSendResult> {\n    const results: EmailSendResult[] = []\n    let successful = 0\n    let failed = 0\n\n    for (const message of messages) {\n      try {\n        const result = await this.send(message)\n        results.push(result)\n        successful++\n      }\n      catch (error) {\n        results.push({\n          messageId: '',\n          accepted: false,\n          metadata: {\n            error: error instanceof Error ? error.message : 'Unknown error',\n          },\n        })\n        failed++\n      }\n    }\n\n    return {\n      total: messages.length,\n      successful,\n      failed,\n      results,\n    }\n  }\n}\n"],"mappings":";;;;;;;AASA,IAAsB,oBAAtB,MAAkE;;;;;;;CAYhE,MAAM,UAAU,UAAiE;EAC/E,MAAM,UAA6B,EAAE;EACrC,IAAI,aAAa;EACjB,IAAI,SAAS;AAEb,OAAK,MAAM,WAAW,SACpB,KAAI;GACF,MAAM,SAAS,MAAM,KAAK,KAAK,QAAQ;AACvC,WAAQ,KAAK,OAAO;AACpB;WAEK,OAAO;AACZ,WAAQ,KAAK;IACX,WAAW;IACX,UAAU;IACV,UAAU,EACR,OAAO,iBAAiB,QAAQ,MAAM,UAAU,iBACjD;IACF,CAAC;AACF;;AAIJ,SAAO;GACL,OAAO,SAAS;GAChB;GACA;GACA;GACD"}

package/dist/cache/index.d.mts

@@ -0,0 +1,219 @@
+import { Ht as StratalEnv, s as ApplicationError } from "../index-C9bIk5tt.mjs";
+import { i as LoggerService } from "../index-3TtGtYlJ.mjs";
+
+//#region src/cache/cache.module.d.ts
+/**
+ * Cache Module
+ *
+ * Provides key-value caching capabilities using Cloudflare KV namespaces.
+ *
+ * **Features:**
+ * - Type-safe KV wrapper with full method coverage
+ * - Multiple KV binding support via `withBinding()`
+ * - Automatic error handling with security-focused logging
+ * - Singleton service for optimal performance
+ */
+declare class CacheModule {}
+//#endregion
+//#region src/cache/cache.tokens.d.ts
+declare const CACHE_TOKENS: {
+  readonly CacheService: 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
+//#region src/cache/services/cache.service.d.ts
+/**
+ * Cache Service
+ *
+ * Type-safe wrapper around Cloudflare KV namespaces for caching operations.
+ *
+ * **Features:**
+ * - Mirrors all KVNamespace methods with full type safety
+ * - Supports multiple KV bindings via `withBinding()`
+ * - Automatic error handling with logging
+ * - Security: Raw errors are logged, not exposed to users
+ *
+ * **Usage:**
+ * ```typescript
+ * class MyService {
+ *   private readonly uploadsCache: CacheService
+ *
+ *   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)
+ *   }
+ *
+ *   async cacheData(key: string, value: string) {
+ *     await this.cache.put(key, value, { expirationTtl: 3600 })
+ *     await this.uploadsCache.put(`upload:${key}`, value)
+ *   }
+ * }
+ * ```
+ *
+ * @see https://developers.cloudflare.com/kv/api/
+ */
+declare class CacheService {
+  private readonly env;
+  private readonly logger;
+  private kv;
+  constructor(env: StratalEnv, logger: LoggerService);
+  /**
+   * Set the KV namespace binding
+   *
+   * Used internally by `withBinding()` to configure different KV instances.
+   *
+   * @param kv - KV namespace to use
+   */
+  setKV(kv: KVNamespace): void;
+  /**
+   * 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)
+   *   }
+   * }
+   * ```
+   *
+   * @param kv - KV namespace to use
+   * @returns New CacheService instance with the specified binding
+   */
+  withBinding(kv: KVNamespace): 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
+   */
+  get(key: string, typeOrOptions?: 'text' | KVNamespaceGetOptions<'text'>): Promise<string | null>;
+  get<ExpectedValue = unknown>(key: string, typeOrOptions: 'json' | KVNamespaceGetOptions<'json'>): Promise<ExpectedValue | null>;
+  get(key: string, typeOrOptions: 'arrayBuffer' | KVNamespaceGetOptions<'arrayBuffer'>): Promise<ArrayBuffer | null>;
+  get(key: string, typeOrOptions: 'stream' | KVNamespaceGetOptions<'stream'>): Promise<ReadableStream | null>;
+  /**
+   * Get a value with metadata from cache
+   *
+   * @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
+   */
+  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>>;
+  getWithMetadata<Metadata = unknown>(key: string, typeOrOptions: 'arrayBuffer' | KVNamespaceGetOptions<'arrayBuffer'>): Promise<KVNamespaceGetWithMetadataResult<ArrayBuffer, Metadata>>;
+  getWithMetadata<Metadata = unknown>(key: string, typeOrOptions: 'stream' | KVNamespaceGetOptions<'stream'>): Promise<KVNamespaceGetWithMetadataResult<ReadableStream, Metadata>>;
+  /**
+   * Store a value in cache
+   *
+   * @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
+   *
+   * @example
+   * ```typescript
+   * // Simple put
+   * await cache.put('key', 'value')
+   *
+   * // With TTL
+   * await cache.put('key', 'value', { expirationTtl: 3600 })
+   *
+   * // With metadata
+   * await cache.put('key', 'value', { metadata: { created: Date.now() } })
+   * ```
+   */
+  put(key: string, value: string | ArrayBuffer | ArrayBufferView | ReadableStream, options?: KVNamespacePutOptions): Promise<void>;
+  /**
+   * Delete a value from cache
+   *
+   * @param key - Cache key to delete
+   * @throws {CacheDeleteError} If operation fails
+   */
+  delete(key: string): Promise<void>;
+  /**
+   * List keys in cache
+   *
+   * @param options - List options (limit, prefix, cursor)
+   * @returns List result with keys and pagination info
+   * @throws {CacheListError} If operation fails
+   *
+   * @example
+   * ```typescript
+   * // List all keys
+   * const result = await cache.list()
+   *
+   * // List with prefix
+   * const result = await cache.list({ prefix: 'user:' })
+   *
+   * // Paginated list
+   * const result = await cache.list({ limit: 100 })
+   * if (!result.list_complete) {
+   *   const nextPage = await cache.list({ cursor: result.cursor })
+   * }
+   * ```
+   */
+  list<Metadata = unknown>(options?: KVNamespaceListOptions): Promise<KVNamespaceListResult<Metadata>>;
+}
+//#endregion
+export { CACHE_TOKENS, CacheDeleteError, CacheGetError, CacheListError, CacheModule, CachePutError, CacheService, CacheToken };
+//# sourceMappingURL=index.d.mts.map

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

@@ -0,0 +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","../../src/cache/services/cache.service.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;;;;;;ALQpC;;;;;;;;AChBA;;;;;AAIA;;;;;;;;ACKA;;;;;;;;;cIsCa,YAAA;EAAA,iBAIyC,GAAA;EAAA,iBACI,MAAA;EAAA,QAJhD,EAAA;cAG4C,GAAA,EAAK,UAAA,EACD,MAAA,EAAQ,aAAA;;;;;;;;EAYhE,KAAA,CAAM,EAAA,EAAI,WAAA;;;AFvDZ;;;;;;;;;;;;ACDA;;;;;;;;ACsCA;;;;EAgDE,WAAA,CAAY,EAAA,EAAI,WAAA,GAAc,YAAA;EA9BpB;;;;;;;;EA8CJ,GAAA,CAAI,GAAA,UAAa,aAAA,YAAyB,qBAAA,WAAgC,OAAA;EAC1E,GAAA,yBAAA,CAA6B,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;EAAA;;;;;;;;EAkCrF,eAAA,oBAAA,CACJ,GAAA,UACA,aAAA,YAAyB,qBAAA,WACxB,OAAA,CAAQ,gCAAA,SAAyC,QAAA;EAC9C,eAAA,6CAAA,CACJ,GAAA,UACA,aAAA,WAAwB,qBAAA,WACvB,OAAA,CAAQ,gCAAA,CAAiC,aAAA,EAAe,QAAA;EACrD,eAAA,oBAAA,CACJ,GAAA,UACA,aAAA,kBAA+B,qBAAA,kBAC9B,OAAA,CAAQ,gCAAA,CAAiC,WAAA,EAAa,QAAA;EACnD,eAAA,oBAAA,CACJ,GAAA,UACA,aAAA,aAA0B,qBAAA,aACzB,OAAA,CAAQ,gCAAA,CAAiC,cAAA,EAAgB,QAAA;EAJhB;;;;;;;;;;;;;;;;;;;;EAuDtC,GAAA,CACJ,GAAA,UACA,KAAA,WAAgB,WAAA,GAAc,eAAA,GAAkB,cAAA,EAChD,OAAA,GAAU,qBAAA,GACT,OAAA;EAtKiD;;;;;;EAuL9C,MAAA,CAAO,GAAA,WAAc,OAAA;EAtL6B;;;;;;;;;;;;;;;;;;;;;;EAwNlD,IAAA,oBAAA,CACJ,OAAA,GAAU,sBAAA,GACT,OAAA,CAAQ,qBAAA,CAAsB,QAAA;AAAA"}

package/dist/cache/index.mjs

@@ -0,0 +1,247 @@
+import { S as ApplicationError, b as ERROR_CODES } from "../errors-BRJgVd5-.mjs";
+import { a as __decorate, d as Transient, g as DI_TOKENS, o as __decorateParam, s as __decorateMetadata, u as LOGGER_TOKENS } from "../logger-Bg-CuidS.mjs";
+import { r as Module } from "../module-Dvzm4dhS.mjs";
+import "../events-CQyvSyrQ.mjs";
+import "../middleware-B3tx1u1K.mjs";
+import "../router-context-DlTxpJUG.mjs";
+import { inject } from "tsyringe";
+//#region src/cache/cache.tokens.ts
+const CACHE_TOKENS = { CacheService: Symbol.for("stratal:cache:service") };
+//#endregion
+//#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 });
+	}
+};
+//#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, {});
+	}
+};
+//#endregion
+//#region src/cache/services/cache.service.ts
+var _CacheService;
+let CacheService = _CacheService = class CacheService {
+	kv;
+	constructor(env, logger) {
+		this.env = env;
+		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;
+	}
+	/**
+	* 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)
+	*   }
+	* }
+	* ```
+	*
+	* @param kv - KV namespace to use
+	* @returns New CacheService instance with the specified binding
+	*/
+	withBinding(kv) {
+		const instance = new _CacheService(this.env, this.logger);
+		instance.setKV(kv);
+		return instance;
+	}
+	async get(key, typeOrOptions) {
+		try {
+			if (typeof typeOrOptions === "string") return await this.kv.get(key, typeOrOptions);
+			if (typeOrOptions) return await this.kv.get(key, typeOrOptions);
+			return await this.kv.get(key);
+		} catch (error) {
+			this.logger.error("Cache get operation failed", {
+				key,
+				error
+			});
+			throw new CacheGetError(key);
+		}
+	}
+	async getWithMetadata(key, typeOrOptions) {
+		try {
+			if (typeof typeOrOptions === "string") return await this.kv.getWithMetadata(key, typeOrOptions);
+			if (typeOrOptions) return await this.kv.getWithMetadata(key, typeOrOptions);
+			return await this.kv.getWithMetadata(key);
+		} catch (error) {
+			this.logger.error("Cache getWithMetadata operation failed", {
+				key,
+				error
+			});
+			throw new CacheGetError(key);
+		}
+	}
+	/**
+	* Store a value in cache
+	*
+	* @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
+	*
+	* @example
+	* ```typescript
+	* // Simple put
+	* await cache.put('key', 'value')
+	*
+	* // With TTL
+	* await cache.put('key', 'value', { expirationTtl: 3600 })
+	*
+	* // With metadata
+	* await cache.put('key', 'value', { metadata: { created: Date.now() } })
+	* ```
+	*/
+	async put(key, value, options) {
+		try {
+			await this.kv.put(key, value, options);
+		} catch (error) {
+			this.logger.error("Cache put operation failed", {
+				key,
+				error
+			});
+			throw new CachePutError(key);
+		}
+	}
+	/**
+	* Delete a value from cache
+	*
+	* @param key - Cache key to delete
+	* @throws {CacheDeleteError} If operation fails
+	*/
+	async delete(key) {
+		try {
+			await this.kv.delete(key);
+		} catch (error) {
+			this.logger.error("Cache delete operation failed", {
+				key,
+				error
+			});
+			throw new CacheDeleteError(key);
+		}
+	}
+	/**
+	* List keys in cache
+	*
+	* @param options - List options (limit, prefix, cursor)
+	* @returns List result with keys and pagination info
+	* @throws {CacheListError} If operation fails
+	*
+	* @example
+	* ```typescript
+	* // List all keys
+	* const result = await cache.list()
+	*
+	* // List with prefix
+	* const result = await cache.list({ prefix: 'user:' })
+	*
+	* // Paginated list
+	* const result = await cache.list({ limit: 100 })
+	* if (!result.list_complete) {
+	*   const nextPage = await cache.list({ cursor: result.cursor })
+	* }
+	* ```
+	*/
+	async list(options) {
+		try {
+			return await this.kv.list(options);
+		} catch (error) {
+			this.logger.error("Cache list operation failed", {
+				options,
+				error
+			});
+			throw new CacheListError();
+		}
+	}
+};
+CacheService = _CacheService = __decorate([
+	Transient(CACHE_TOKENS.CacheService),
+	__decorateParam(0, inject(DI_TOKENS.CloudflareEnv)),
+	__decorateParam(1, inject(LOGGER_TOKENS.LoggerService)),
+	__decorateMetadata("design:paramtypes", [Object, Object])
+], CacheService);
+//#endregion
+//#region src/cache/cache.module.ts
+/**
+* Cache Module
+*
+* Provides key-value caching capabilities using Cloudflare KV namespaces.
+*
+* **Features:**
+* - Type-safe KV wrapper with full method coverage
+* - Multiple KV binding support via `withBinding()`
+* - Automatic error handling with security-focused logging
+* - Singleton service for optimal performance
+*/
+let CacheModule = class CacheModule {};
+CacheModule = __decorate([Module({ providers: [{
+	provide: CACHE_TOKENS.CacheService,
+	useClass: CacheService
+}] })], CacheModule);
+//#endregion
+export { CACHE_TOKENS, CacheDeleteError, CacheGetError, CacheListError, CacheModule, CachePutError, CacheService };
+
+//# sourceMappingURL=index.mjs.map

package/dist/cache/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../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","../../src/cache/services/cache.service.ts","../../src/cache/cache.module.ts"],"sourcesContent":["export const CACHE_TOKENS = {\n  CacheService: Symbol.for('stratal:cache:service'),\n} as const\n\nexport type CacheToken = (typeof CACHE_TOKENS)[keyof typeof CACHE_TOKENS]\n","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":"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"}

package/dist/chunk-D1SwGrFN.mjs

@@ -0,0 +1,27 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+//#endregion
+export { __reExport as n, __exportAll as t };