@warlock.js/cache 5.30.0 → 5.32.0

package/esm/cache-manager.d.mts

@@ -1,8 +1,7 @@
 import { CacheConfigurations, CacheDriver, CacheEventHandler, CacheEventType, CacheKey, CacheListAccessor, CacheMetricsSnapshot, CacheNamespaceOptions, CacheSetOptions, CacheSimilarHit, CacheSimilarOptions, CacheSwrOptions, CacheTtl, DriverClass, LockOptions, LockOutcome, RememberOptions, ScopedCacheContract, TaggedCacheDriver } from "./types.mjs";
 import { CacheMetricsCollector } from "./metrics.mjs";
-
 //#region ../../packages/cache/src/cache-manager.d.ts
-declare class CacheManager implements CacheDriver<any, any> {
+export declare class CacheManager implements CacheDriver<any, any> {
   /**
    * Cache Driver
    */
@@ -213,7 +212,9 @@ declare class CacheManager implements CacheDriver<any, any> {
   /**
    * {@inheritdoc}
    */
-  increment(key: CacheKey, value?: number): Promise<number>;
+  increment(key: CacheKey, value?: number, options?: {
+    ttl?: CacheTtl;
+  }): Promise<number>;
   /**
    * {@inheritdoc}
    */
@@ -312,7 +313,6 @@ declare class CacheManager implements CacheDriver<any, any> {
   namespace(prefix: string, options?: CacheNamespaceOptions): ScopedCacheContract;
   similar<T = any>(vector: number[], options: CacheSimilarOptions): Promise<CacheSimilarHit<T>[]>;
 }
-declare const cache: CacheManager;
+export declare const cache: CacheManager;
 //#endregion
-export { CacheManager, cache };
 //# sourceMappingURL=cache-manager.d.mts.map

package/esm/cache-manager.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"cache-manager.d.mts","names":[],"sources":["../../../../../../../packages/cache/src/cache-manager.ts"],"mappings":"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"}
+{"version":3,"file":"cache-manager.d.mts","names":[],"sources":["../../../../../../../packages/cache/src/cache-manager.ts"],"mappings":";;;qBAyBa,wBAAwB;;;;EAI5B,gBAAgB;;;;EAKhB,eAAe,eAAe;;;;YAK3B,gBAAc,YAAA,QAAA;;;;YAKd,gBAAgB;;;;YAQhB,sBAAsB,IAAI,gBAAgB,IAAI;;;;;;YAO9C,mBAAmB;;;;EAKtB;;;;MAKI;;;;EAOJ,uBAAuB,gBAAgB;;;;EAUvC,gBAAgB;;;;;;;;;;;;;;;;;;;EAwBV,IAAI,iBAAiB,uBAAuB,iBAAiB,sBAAmB;;;;YA2BnF;;;;;;;;;;;EAgBH,WAAW;;;;;EAQX;;;;;;;YAUG,0BAA0B;;;;;;;YAwBpB,MAAM,GAAG,YAAY,QAAQ,IAAI,sBAAsB,QAAQ;;;;EAmBlE,IAAI,SAAS,KAAK,WAAW,QAAQ;;;;;;;;EAYrC,IAAI,KAAK,UAAU,YAAY,eAAe,WAAW,kBAAe;;;;EAmBxE,OAAO,KAAK,WAAQ;;;;EAQpB,gBAAgB,oBAAiB;;;;EAQjC,SAAK;;;;EAQL,WAAO;;;;EAQb,SAAS,KAAK;;;;MAQV;;;;EAQJ,WAAW,SAAS;;;;;;;EAWd,OAAO,oBAAoB,iBAAiB,sBAAmB,QAAA;;;;EAa/D,QAAI;;;;;;;;;;;;;;;EA0BJ,KAAK,gBAAgB,iBAAiB,sBAAmB,QAAA;;;;;;;;YAyD5D,0BACR,oBACA,gBAAgB;;;;EAkBX,eAAe,oBAAoB,aAAa;;;;EAO1C,cAAU;;;;EAmBV,IAAI,KAAK,WAAW;;;;EAQpB,SAAS,SACpB,KAAK,UACL,cAAc,WAAW,iBACzB,gBAAgB,QAAQ,KACvB,QAAQ;;;;;;;;;;;;;;EA6BE,IAAI,SACf,KAAK,UACL,SAAS,iBACT,gBAAgB,QAAQ,KACvB,QAAQ;;;;EAiBE,KAAK,KAAK,WAAW;;;;EAQrB,QAAQ,KAAK,UAAU,aAAa;;;;EAQpC,UACX,KAAK,UACL,gBACA;IAAY,MAAM;MACjB;;;;EAQU,UAAU,KAAK,UAAU,iBAAiB;;;;EAQ1C,KAAK,MAAM,aAAa;;;;EAQxB,QAAQ,OAAO,qBAAqB,eAAe;;;;EAQzD,GAAG,OAAO,gBAAgB,SAAS;;;;EAsBnC,IAAI,OAAO,gBAAgB,SAAS;;;;EAsBpC,KAAK,OAAO,gBAAgB,SAAS;;;;YAWlC,sBAAsB,QAAQ;;;;;;EAa3B,MAAM,KAAK,UAAU,YAAY,eAAe;;;;EAetD,KAAK,iBAAiB;;;;EAQhB,OAAO,SAClB,KAAK,UACL,KAAK,SAAS,aAAa,WAAW,QAAQ,WAC9C;IAAY,MAAM;MACjB,QAAQ;;;;EAQE,MAAM,UAAU,sBAAsB,qBACjD,KAAK,UACL,SAAS,QAAQ,IACjB;IAAY,MAAM;MACjB,QAAQ;;;;EAQJ,KAAK,SAAS,KAAK,WAAW,kBAAkB;;;;;;;;;;;;;;;;;;EAsB1C,KAAK,GAChB,KAAK,UACL,cAAc,WAAW,aACzB,UAAU,QAAQ,KACjB,QAAQ,YAAY;;;;;;;;;;;;;;;;;;;;;;;;EAoChB,UAAU,gBAAgB,UAAU,wBAAwB;EAKtD,QAAQ,SACnB,kBACA,SAAS,sBACR,QAAQ,gBAAgB;;qBAMhB,OAAK"}

package/esm/cache-manager.mjs

@@ -344,9 +344,9 @@ var CacheManager = class {
 	/**
 	* {@inheritdoc}
 	*/
-	async increment(key, value) {
+	async increment(key, value, options) {
 		this.ensureDriverInitialized();
-		return this.currentDriver.increment(key, value);
+		return this.currentDriver.increment(key, value, options);
 	}
 	/**
 	* {@inheritdoc}

package/esm/cache-manager.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cache-manager.mjs","names":[],"sources":["../../../../../../../packages/cache/src/cache-manager.ts"],"sourcesContent":["import { CacheMetricsCollector } from \"./metrics\";\nimport { ScopedCache } from \"./scoped-cache\";\nimport type {\n  CacheConfigurations,\n  CacheDriver,\n  CacheEventHandler,\n  CacheEventType,\n  CacheKey,\n  CacheListAccessor,\n  CacheMetricsSnapshot,\n  CacheNamespaceOptions,\n  CacheSetOptions,\n  CacheSimilarHit,\n  CacheSimilarOptions,\n  CacheSwrOptions,\n  CacheTtl,\n  DriverClass,\n  LockOptions,\n  LockOutcome,\n  RememberOptions,\n  ScopedCacheContract,\n  TaggedCacheDriver,\n} from \"./types\";\nimport { CacheConfigurationError, CacheDriverNotInitializedError } from \"./types\";\n\nexport class CacheManager implements CacheDriver<any, any> {\n  /**\n   * Cache Driver\n   */\n  public currentDriver?: CacheDriver<any, any>;\n\n  /**\n   * Loaded drivers\n   */\n  public loadedDrivers: Record<string, CacheDriver<any, any>> = {};\n\n  /**\n   * In-flight `load()` promises, so concurrent callers share one `connect()`.\n   */\n  protected loadingDrivers = new Map<string, Promise<CacheDriver<any, any>>>();\n\n  /**\n   * Configurations list\n   */\n  protected configurations: CacheConfigurations = {\n    drivers: {},\n    options: {},\n  };\n\n  /**\n   * Global event listeners\n   */\n  protected globalEventListeners: Map<CacheEventType, Set<CacheEventHandler>> = new Map();\n\n  /**\n   * Metrics collector — lazy on first {@link metrics} call so apps that\n   * never read metrics pay zero cost. Once instantiated, it stays\n   * subscribed to events for the manager's lifetime.\n   */\n  protected metricsCollector?: CacheMetricsCollector;\n\n  /**\n   * {@inheritdoc}\n   */\n  public name = \"cacheManager\";\n\n  /**\n   * {@inheritdoc}\n   */\n  public get client() {\n    return this.currentDriver?.client;\n  }\n\n  /**\n   * Set the cache configurations\n   */\n  public setCacheConfigurations(configurations: CacheConfigurations) {\n    this.configurations.default = configurations.default;\n    this.configurations.drivers = configurations.drivers;\n    this.configurations.options = configurations.options;\n    this.configurations.logging = configurations.logging;\n  }\n\n  /**\n   * Set logging state\n   */\n  public setLoggingState(loggingState: boolean) {\n    this.ensureDriverInitialized();\n\n    this.currentDriver!.setLoggingState(loggingState);\n  }\n\n  /**\n   * Switch the manager to a registered driver, optionally injecting runtime\n   * options that merge over the static config.\n   *\n   * The string form looks the driver up in `setCacheConfigurations({ drivers })`,\n   * loads it (or returns the cached instance), and sets it as `currentDriver`.\n   * The instance form takes a pre-built driver and bypasses the registry; the\n   * `runtimeOptions` argument is silently ignored in that case because the\n   * instance was constructed externally.\n   *\n   * Runtime options merge over `config.options[name]` per-key — runtime wins.\n   * Use this for constructor-only knobs that can't live in static config\n   * (e.g. `pg`'s `client: pg.Pool`).\n   *\n   * @example\n   * const pool = new Pool({ connectionString });\n   * await cache.use(\"pg\", { client: pool });\n   */\n  public async use(\n    driver: string | CacheDriver<any, any>,\n    runtimeOptions?: Record<string, any>,\n  ) {\n    if (typeof driver === \"string\") {\n      const driverInstance = await this.load(driver, runtimeOptions);\n\n      if (!driverInstance) {\n        throw new CacheConfigurationError(\n          `Cache driver ${driver} is not found, please declare it in the cache drivers in the configurations list.`,\n        );\n      }\n\n      driver = driverInstance;\n    }\n\n    this.attachGlobalListeners(driver);\n\n    if (this.configurations.logging !== undefined) {\n      driver.setLoggingState(this.configurations.logging);\n    }\n\n    this.currentDriver = driver;\n\n    return this;\n  }\n\n  /**\n   * Ensure driver is initialized before operations\n   */\n  protected ensureDriverInitialized(): void {\n    if (!this.currentDriver) {\n      throw new CacheDriverNotInitializedError();\n    }\n  }\n\n  /**\n   * Return the running metrics snapshot — counters, hit-rate, latency\n   * percentiles, per-driver breakdowns. Lazy-attaches the collector on\n   * first call so apps that never read metrics pay zero cost.\n   *\n   * @example\n   * const m = cache.metrics();\n   * console.log(`hit rate: ${(m.hitRate * 100).toFixed(1)}%`);\n   * console.log(`p95: ${m.latencyMs.p95.toFixed(2)}ms`);\n   */\n  public metrics(): CacheMetricsSnapshot {\n    return this.ensureMetricsCollector().snapshot();\n  }\n\n  /**\n   * Wipe every counter + latency sample and reset `startedAt` to now.\n   * The collector itself stays subscribed to events.\n   */\n  public resetMetrics(): void {\n    this.ensureMetricsCollector().reset();\n  }\n\n  /**\n   * Lazy-construct the metrics collector and wire it to the global event\n   * bus. Subsequent calls return the same instance — survives `cache.use()`\n   * driver switches because handlers attach via `on()` and re-bind to every\n   * loaded driver.\n   */\n  protected ensureMetricsCollector(): CacheMetricsCollector {\n    if (this.metricsCollector) {\n      return this.metricsCollector;\n    }\n\n    const collector = new CacheMetricsCollector();\n\n    this.on(\"hit\", (data) => collector.recordEvent(\"hit\", data));\n    this.on(\"miss\", (data) => collector.recordEvent(\"miss\", data));\n    this.on(\"set\", (data) => collector.recordEvent(\"set\", data));\n    this.on(\"removed\", (data) => collector.recordEvent(\"removed\", data));\n    this.on(\"error\", (data) => collector.recordEvent(\"error\", data));\n\n    this.metricsCollector = collector;\n\n    return collector;\n  }\n\n  /**\n   * Time the body, record the elapsed milliseconds against the metrics\n   * collector for the given driver (defaults to the current driver's name).\n   * Pass-through if the collector hasn't been instantiated yet — apps that\n   * don't read metrics never pay for sample collection.\n   */\n  protected async timed<T>(\n    body: () => Promise<T>,\n    driverName?: string,\n  ): Promise<T> {\n    if (!this.metricsCollector) {\n      return body();\n    }\n\n    const start = performance.now();\n\n    try {\n      return await body();\n    } finally {\n      const elapsed = performance.now() - start;\n      const name = driverName ?? this.currentDriver?.name ?? \"unknown\";\n      this.metricsCollector.recordLatency(name, elapsed);\n    }\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async get<T = any>(key: CacheKey): Promise<T | null> {\n    this.ensureDriverInitialized();\n    return this.timed(() => this.currentDriver!.get<T>(key));\n  }\n\n  /**\n   * Set a value in the cache.\n   *\n   * Accepts a positional TTL (number of seconds or duration string like `\"1h\"`)\n   * or a rich {@link CacheSetOptions} object supporting `ttl`, `expiresAt`,\n   * `tags`, `onConflict`, `namespace`, and per-call `driver` overrides.\n   */\n  public async set(key: CacheKey, value: any, ttlOrOptions?: CacheTtl | CacheSetOptions) {\n    this.ensureDriverInitialized();\n\n    const driverOverride =\n      ttlOrOptions && typeof ttlOrOptions === \"object\" && \"driver\" in ttlOrOptions\n        ? ttlOrOptions.driver\n        : undefined;\n\n    if (driverOverride) {\n      const driver = await this.load(driverOverride);\n      return this.timed(() => driver.set(key, value, ttlOrOptions), driver.name);\n    }\n\n    return this.timed(() => this.currentDriver!.set(key, value, ttlOrOptions));\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async remove(key: CacheKey) {\n    this.ensureDriverInitialized();\n    return this.timed(() => this.currentDriver!.remove(key));\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async removeNamespace(namespace: string) {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.removeNamespace(namespace);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async flush() {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.flush();\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async connect() {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.connect();\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public parseKey(key: CacheKey) {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.parseKey(key);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public get options() {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.options;\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public setOptions(options: Record<string, any>) {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.setOptions(options || {});\n  }\n\n  /**\n   * Return the loaded driver instance for `driverName`, loading it on first\n   * call. Optional `runtimeOptions` follow the same merge-over-config rules\n   * as {@link load}; passing options after the driver has already been\n   * loaded throws to avoid silent swallowing.\n   */\n  public async driver(driverName: string, runtimeOptions?: Record<string, any>) {\n    if (this.loadedDrivers[driverName]) {\n      this.assertNoConflictingReload(driverName, runtimeOptions);\n\n      return this.loadedDrivers[driverName];\n    }\n\n    return this.load(driverName, runtimeOptions);\n  }\n\n  /**\n   * Initialize the cache manager and pick the default driver\n   */\n  public async init() {\n    const defaultCacheDriverName = this.configurations.default;\n\n    if (!defaultCacheDriverName) {\n      return;\n    }\n\n    const driver = await this.driver(defaultCacheDriverName);\n\n    await this.use(driver);\n  }\n\n  /**\n   * Load and connect the registered driver named `driver`. First-call wins —\n   * subsequent calls without `runtimeOptions` return the cached instance, and\n   * subsequent calls *with* `runtimeOptions` throw {@link CacheConfigurationError}\n   * to avoid silently dropping the new options.\n   *\n   * `runtimeOptions` merge over `config.options[driver]` per-key (runtime wins),\n   * letting consumers split static knobs (table, ttl, globalPrefix) from\n   * constructor-only ones (pg's `client`, custom adapters, etc.).\n   *\n   * @example\n   * const pool = new Pool({ connectionString });\n   * const pg = await cache.load(\"pg\", { client: pool });\n   */\n  public async load(driver: string, runtimeOptions?: Record<string, any>) {\n    if (this.loadedDrivers[driver]) {\n      this.assertNoConflictingReload(driver, runtimeOptions);\n\n      return this.loadedDrivers[driver];\n    }\n\n    const inFlight = this.loadingDrivers.get(driver);\n\n    if (inFlight) {\n      this.assertNoConflictingReload(driver, runtimeOptions);\n\n      return inFlight;\n    }\n\n    const Driver = this.configurations.drivers[\n      driver as keyof typeof this.configurations.drivers\n    ] as DriverClass | undefined;\n\n    if (!Driver) {\n      throw new CacheConfigurationError(\n        `Cache driver ${driver} is not found, please declare it in the cache drivers in the configurations list.`,\n      );\n    }\n\n    const driverInstance = new Driver();\n    const configOptions =\n      this.configurations.options[driver as keyof typeof this.configurations.options] || {};\n\n    driverInstance.setOptions({ ...configOptions, ...(runtimeOptions ?? {}) });\n\n    const promise = (async () => {\n      try {\n        await driverInstance.connect();\n\n        this.attachGlobalListeners(driverInstance);\n\n        this.loadedDrivers[driver] = driverInstance;\n\n        return driverInstance as CacheDriver<any, any>;\n      } finally {\n        this.loadingDrivers.delete(driver);\n      }\n    })();\n\n    this.loadingDrivers.set(driver, promise);\n\n    return promise;\n  }\n\n  /**\n   * Guard against silently dropping runtime options on a re-load. Once a\n   * driver has been instantiated, its options are frozen — calling `load` /\n   * `driver` / `use` again with a non-empty `runtimeOptions` would otherwise\n   * appear to work but actually use the original options. We throw instead\n   * so the misuse surfaces at the call site.\n   */\n  protected assertNoConflictingReload(\n    driverName: string,\n    runtimeOptions: Record<string, any> | undefined,\n  ): void {\n    if (runtimeOptions === undefined) {\n      return;\n    }\n\n    if (Object.keys(runtimeOptions).length === 0) {\n      return;\n    }\n\n    throw new CacheConfigurationError(\n      `Cache driver '${driverName}' is already loaded; runtime options on subsequent calls are ignored — register a second driver name if you need a different configuration.`,\n    );\n  }\n\n  /**\n   * Register and bind a driver\n   */\n  public registerDriver(driverName: string, driverClass: DriverClass) {\n    (this.configurations.drivers as Record<string, DriverClass>)[driverName] = driverClass;\n  }\n\n  /**\n   * Disconnect the cache manager\n   */\n  public async disconnect() {\n    const drivers = new Set<any>(Object.values(this.loadedDrivers));\n\n    if (this.currentDriver) {\n      drivers.add(this.currentDriver);\n    }\n\n    await Promise.allSettled([...drivers].map(driver => driver.disconnect()));\n\n    for (const name of Object.keys(this.loadedDrivers)) {\n      delete this.loadedDrivers[name];\n    }\n\n    this.loadingDrivers.clear();\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async has(key: CacheKey): Promise<boolean> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.has(key);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async remember<T = any>(\n    key: CacheKey,\n    ttlOrOptions: CacheTtl | RememberOptions,\n    callback: () => Promise<T>,\n  ): Promise<T> {\n    this.ensureDriverInitialized();\n\n    const driverOverride =\n      ttlOrOptions && typeof ttlOrOptions === \"object\" && \"driver\" in ttlOrOptions\n        ? ttlOrOptions.driver\n        : undefined;\n\n    if (driverOverride) {\n      const driver = await this.load(driverOverride);\n      return driver.remember(key, ttlOrOptions, callback);\n    }\n\n    return this.currentDriver!.remember(key, ttlOrOptions, callback);\n  }\n\n  /**\n   * Stale-while-revalidate. Returns cached when fresh, returns the stale\n   * value plus a background refresh when within `freshTtl..staleTtl`,\n   * blocks like a normal miss past `staleTtl`. Honors per-call `driver`\n   * override the same way `remember()` does.\n   *\n   * @example\n   * const product = await cache.swr(\n   *   \"product.42\",\n   *   { freshTtl: \"1m\", staleTtl: \"1h\" },\n   *   () => db.products.find(42),\n   * );\n   */\n  public async swr<T = any>(\n    key: CacheKey,\n    options: CacheSwrOptions,\n    callback: () => Promise<T>,\n  ): Promise<T> {\n    this.ensureDriverInitialized();\n\n    const driverOverride = options.driver;\n\n    if (driverOverride) {\n      const driver = await this.load(driverOverride);\n\n      return driver.swr<T>(key, options, callback);\n    }\n\n    return this.currentDriver!.swr<T>(key, options, callback);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async pull(key: CacheKey): Promise<any | null> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.pull(key);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async forever(key: CacheKey, value: any): Promise<any> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.forever(key, value);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async increment(key: CacheKey, value?: number): Promise<number> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.increment(key, value);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async decrement(key: CacheKey, value?: number): Promise<number> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.decrement(key, value);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async many(keys: CacheKey[]): Promise<any[]> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.many(keys);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async setMany(items: Record<string, any>, ttl?: number): Promise<void> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.setMany(items, ttl);\n  }\n\n  /**\n   * Register a global event listener (applies to all drivers)\n   */\n  public on(event: CacheEventType, handler: CacheEventHandler): this {\n    if (!this.globalEventListeners.has(event)) {\n      this.globalEventListeners.set(event, new Set());\n    }\n    this.globalEventListeners.get(event)!.add(handler);\n\n    // Also attach to current driver if exists\n    if (this.currentDriver) {\n      this.currentDriver.on(event, handler);\n    }\n\n    // Attach to all loaded drivers\n    for (const driver of Object.values(this.loadedDrivers)) {\n      driver.on(event, handler);\n    }\n\n    return this;\n  }\n\n  /**\n   * Remove a global event listener\n   */\n  public off(event: CacheEventType, handler: CacheEventHandler): this {\n    const handlers = this.globalEventListeners.get(event);\n    if (handlers) {\n      handlers.delete(handler);\n    }\n\n    // Also remove from current driver\n    if (this.currentDriver) {\n      this.currentDriver.off(event, handler);\n    }\n\n    // Remove from all loaded drivers\n    for (const driver of Object.values(this.loadedDrivers)) {\n      driver.off(event, handler);\n    }\n\n    return this;\n  }\n\n  /**\n   * Register a one-time global event listener\n   */\n  public once(event: CacheEventType, handler: CacheEventHandler): this {\n    const onceHandler: CacheEventHandler = async (data) => {\n      await handler(data);\n      this.off(event, onceHandler);\n    };\n    return this.on(event, onceHandler);\n  }\n\n  /**\n   * Attach global listeners to a driver\n   */\n  protected attachGlobalListeners(driver: CacheDriver<any, any>) {\n    for (const [event, handlers] of this.globalEventListeners) {\n      for (const handler of handlers) {\n        driver.on(event, handler);\n      }\n    }\n  }\n\n  /**\n   * Set if not exists (atomic operation)\n   * Returns true if key was set, false if key already existed\n   * Note: Only supported by drivers that implement setNX (e.g., Redis)\n   */\n  public async setNX(key: CacheKey, value: any, ttl?: number): Promise<boolean> {\n    this.ensureDriverInitialized();\n\n    if (!this.currentDriver!.setNX) {\n      throw new Error(\n        `setNX is not supported by the current cache driver: ${this.currentDriver!.name}`,\n      );\n    }\n\n    return this.currentDriver!.setNX(key, value, ttl);\n  }\n\n  /**\n   * Create a tagged cache instance for the given tags\n   */\n  public tags(tags: string[]): TaggedCacheDriver {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.tags(tags);\n  }\n\n  /**\n   * Atomically read, transform, and write a cached value. Delegates to the current driver.\n   */\n  public async update<T = any>(\n    key: CacheKey,\n    fn: (current: T | null) => T | null | Promise<T | null>,\n    options?: { ttl?: CacheTtl },\n  ): Promise<T | null> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.update<T>(key, fn, options);\n  }\n\n  /**\n   * Shallow-merge a partial object into a cached value.\n   */\n  public async merge<T extends Record<string, any> = Record<string, any>>(\n    key: CacheKey,\n    partial: Partial<T>,\n    options?: { ttl?: CacheTtl },\n  ): Promise<T> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.merge<T>(key, partial, options);\n  }\n\n  /**\n   * Obtain a list accessor bound to the current driver.\n   */\n  public list<T = any>(key: CacheKey): CacheListAccessor<T> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.list<T>(key);\n  }\n\n  /**\n   * Acquire a distributed lock, run `fn`, and auto-release. Returns a\n   * {@link LockOutcome} discriminated union so callers can distinguish\n   * \"ran and got this value\" from \"skipped because someone else holds it\".\n   *\n   * Honors the `driver` option for per-call driver override, same as `set`\n   * and `remember`.\n   *\n   * @example\n   * const outcome = await cache.lock(\"lock.import\", \"5m\", async () => {\n   *   await runImport();\n   *   return \"done\";\n   * });\n   * if (!outcome.acquired) {\n   *   console.log(\"another worker is already importing\");\n   * }\n   */\n  public async lock<T>(\n    key: CacheKey,\n    ttlOrOptions: CacheTtl | LockOptions,\n    fn: () => Promise<T>,\n  ): Promise<LockOutcome<T>> {\n    this.ensureDriverInitialized();\n\n    const driverOverride =\n      ttlOrOptions && typeof ttlOrOptions === \"object\" && \"driver\" in ttlOrOptions\n        ? ttlOrOptions.driver\n        : undefined;\n\n    const driver = driverOverride\n      ? await this.load(driverOverride)\n      : this.currentDriver!;\n\n    return driver.lock<T>(key, ttlOrOptions as CacheTtl | Omit<LockOptions, \"driver\">, fn);\n  }\n\n  /**\n   * Similarity retrieval. Delegates to the current driver's `similar()` impl.\n   *\n   * Drivers that lack a similarity index throw {@link CacheUnsupportedError}.\n   *\n   * @example\n   * const hits = await cache.similar(await embed(query), { topK: 5, threshold: 0.7 });\n   */\n  /**\n   * Create a scoped view over the cache. Every key written through the\n   * returned scope is automatically prefixed with `prefix`; optional defaults\n   * (`ttl`, `tags`) flow through every write inside the scope.\n   *\n   * Per-call options always win over scope defaults. Scope tags merge\n   * additively with per-call tags. Nested scopes inherit from the parent.\n   *\n   * @example\n   * const chat = cache.namespace(\"chats.10\", { ttl: \"30d\" });\n   * await chat.set(\"messages.1\", msg);          // → \"chats.10.messages.1\", 30d\n   * await chat.set(\"draft\", d, { ttl: \"1h\" });  // per-call ttl wins\n   * await chat.namespace(\"typing\", { ttl: \"5s\" }).set(\"user.42\", true);\n   * await chat.clear();                          // wipe the whole scope\n   */\n  public namespace(prefix: string, options?: CacheNamespaceOptions): ScopedCacheContract {\n    this.ensureDriverInitialized();\n    return new ScopedCache(this, prefix, options);\n  }\n\n  public async similar<T = any>(\n    vector: number[],\n    options: CacheSimilarOptions,\n  ): Promise<CacheSimilarHit<T>[]> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.similar<T>(vector, options);\n  }\n}\n\nexport const cache = new CacheManager();\n"],"mappings":"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"}
+{"version":3,"file":"cache-manager.mjs","names":[],"sources":["../../../../../../../packages/cache/src/cache-manager.ts"],"sourcesContent":["import { CacheMetricsCollector } from \"./metrics\";\nimport { ScopedCache } from \"./scoped-cache\";\nimport type {\n  CacheConfigurations,\n  CacheDriver,\n  CacheEventHandler,\n  CacheEventType,\n  CacheKey,\n  CacheListAccessor,\n  CacheMetricsSnapshot,\n  CacheNamespaceOptions,\n  CacheSetOptions,\n  CacheSimilarHit,\n  CacheSimilarOptions,\n  CacheSwrOptions,\n  CacheTtl,\n  DriverClass,\n  LockOptions,\n  LockOutcome,\n  RememberOptions,\n  ScopedCacheContract,\n  TaggedCacheDriver,\n} from \"./types\";\nimport { CacheConfigurationError, CacheDriverNotInitializedError } from \"./types\";\n\nexport class CacheManager implements CacheDriver<any, any> {\n  /**\n   * Cache Driver\n   */\n  public currentDriver?: CacheDriver<any, any>;\n\n  /**\n   * Loaded drivers\n   */\n  public loadedDrivers: Record<string, CacheDriver<any, any>> = {};\n\n  /**\n   * In-flight `load()` promises, so concurrent callers share one `connect()`.\n   */\n  protected loadingDrivers = new Map<string, Promise<CacheDriver<any, any>>>();\n\n  /**\n   * Configurations list\n   */\n  protected configurations: CacheConfigurations = {\n    drivers: {},\n    options: {},\n  };\n\n  /**\n   * Global event listeners\n   */\n  protected globalEventListeners: Map<CacheEventType, Set<CacheEventHandler>> = new Map();\n\n  /**\n   * Metrics collector — lazy on first {@link metrics} call so apps that\n   * never read metrics pay zero cost. Once instantiated, it stays\n   * subscribed to events for the manager's lifetime.\n   */\n  protected metricsCollector?: CacheMetricsCollector;\n\n  /**\n   * {@inheritdoc}\n   */\n  public name = \"cacheManager\";\n\n  /**\n   * {@inheritdoc}\n   */\n  public get client() {\n    return this.currentDriver?.client;\n  }\n\n  /**\n   * Set the cache configurations\n   */\n  public setCacheConfigurations(configurations: CacheConfigurations) {\n    this.configurations.default = configurations.default;\n    this.configurations.drivers = configurations.drivers;\n    this.configurations.options = configurations.options;\n    this.configurations.logging = configurations.logging;\n  }\n\n  /**\n   * Set logging state\n   */\n  public setLoggingState(loggingState: boolean) {\n    this.ensureDriverInitialized();\n\n    this.currentDriver!.setLoggingState(loggingState);\n  }\n\n  /**\n   * Switch the manager to a registered driver, optionally injecting runtime\n   * options that merge over the static config.\n   *\n   * The string form looks the driver up in `setCacheConfigurations({ drivers })`,\n   * loads it (or returns the cached instance), and sets it as `currentDriver`.\n   * The instance form takes a pre-built driver and bypasses the registry; the\n   * `runtimeOptions` argument is silently ignored in that case because the\n   * instance was constructed externally.\n   *\n   * Runtime options merge over `config.options[name]` per-key — runtime wins.\n   * Use this for constructor-only knobs that can't live in static config\n   * (e.g. `pg`'s `client: pg.Pool`).\n   *\n   * @example\n   * const pool = new Pool({ connectionString });\n   * await cache.use(\"pg\", { client: pool });\n   */\n  public async use(driver: string | CacheDriver<any, any>, runtimeOptions?: Record<string, any>) {\n    if (typeof driver === \"string\") {\n      const driverInstance = await this.load(driver, runtimeOptions);\n\n      if (!driverInstance) {\n        throw new CacheConfigurationError(\n          `Cache driver ${driver} is not found, please declare it in the cache drivers in the configurations list.`,\n        );\n      }\n\n      driver = driverInstance;\n    }\n\n    this.attachGlobalListeners(driver);\n\n    if (this.configurations.logging !== undefined) {\n      driver.setLoggingState(this.configurations.logging);\n    }\n\n    this.currentDriver = driver;\n\n    return this;\n  }\n\n  /**\n   * Ensure driver is initialized before operations\n   */\n  protected ensureDriverInitialized(): void {\n    if (!this.currentDriver) {\n      throw new CacheDriverNotInitializedError();\n    }\n  }\n\n  /**\n   * Return the running metrics snapshot — counters, hit-rate, latency\n   * percentiles, per-driver breakdowns. Lazy-attaches the collector on\n   * first call so apps that never read metrics pay zero cost.\n   *\n   * @example\n   * const m = cache.metrics();\n   * console.log(`hit rate: ${(m.hitRate * 100).toFixed(1)}%`);\n   * console.log(`p95: ${m.latencyMs.p95.toFixed(2)}ms`);\n   */\n  public metrics(): CacheMetricsSnapshot {\n    return this.ensureMetricsCollector().snapshot();\n  }\n\n  /**\n   * Wipe every counter + latency sample and reset `startedAt` to now.\n   * The collector itself stays subscribed to events.\n   */\n  public resetMetrics(): void {\n    this.ensureMetricsCollector().reset();\n  }\n\n  /**\n   * Lazy-construct the metrics collector and wire it to the global event\n   * bus. Subsequent calls return the same instance — survives `cache.use()`\n   * driver switches because handlers attach via `on()` and re-bind to every\n   * loaded driver.\n   */\n  protected ensureMetricsCollector(): CacheMetricsCollector {\n    if (this.metricsCollector) {\n      return this.metricsCollector;\n    }\n\n    const collector = new CacheMetricsCollector();\n\n    this.on(\"hit\", (data) => collector.recordEvent(\"hit\", data));\n    this.on(\"miss\", (data) => collector.recordEvent(\"miss\", data));\n    this.on(\"set\", (data) => collector.recordEvent(\"set\", data));\n    this.on(\"removed\", (data) => collector.recordEvent(\"removed\", data));\n    this.on(\"error\", (data) => collector.recordEvent(\"error\", data));\n\n    this.metricsCollector = collector;\n\n    return collector;\n  }\n\n  /**\n   * Time the body, record the elapsed milliseconds against the metrics\n   * collector for the given driver (defaults to the current driver's name).\n   * Pass-through if the collector hasn't been instantiated yet — apps that\n   * don't read metrics never pay for sample collection.\n   */\n  protected async timed<T>(body: () => Promise<T>, driverName?: string): Promise<T> {\n    if (!this.metricsCollector) {\n      return body();\n    }\n\n    const start = performance.now();\n\n    try {\n      return await body();\n    } finally {\n      const elapsed = performance.now() - start;\n      const name = driverName ?? this.currentDriver?.name ?? \"unknown\";\n      this.metricsCollector.recordLatency(name, elapsed);\n    }\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async get<T = any>(key: CacheKey): Promise<T | null> {\n    this.ensureDriverInitialized();\n    return this.timed(() => this.currentDriver!.get<T>(key));\n  }\n\n  /**\n   * Set a value in the cache.\n   *\n   * Accepts a positional TTL (number of seconds or duration string like `\"1h\"`)\n   * or a rich {@link CacheSetOptions} object supporting `ttl`, `expiresAt`,\n   * `tags`, `onConflict`, `namespace`, and per-call `driver` overrides.\n   */\n  public async set(key: CacheKey, value: any, ttlOrOptions?: CacheTtl | CacheSetOptions) {\n    this.ensureDriverInitialized();\n\n    const driverOverride =\n      ttlOrOptions && typeof ttlOrOptions === \"object\" && \"driver\" in ttlOrOptions\n        ? ttlOrOptions.driver\n        : undefined;\n\n    if (driverOverride) {\n      const driver = await this.load(driverOverride);\n      return this.timed(() => driver.set(key, value, ttlOrOptions), driver.name);\n    }\n\n    return this.timed(() => this.currentDriver!.set(key, value, ttlOrOptions));\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async remove(key: CacheKey) {\n    this.ensureDriverInitialized();\n    return this.timed(() => this.currentDriver!.remove(key));\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async removeNamespace(namespace: string) {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.removeNamespace(namespace);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async flush() {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.flush();\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async connect() {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.connect();\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public parseKey(key: CacheKey) {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.parseKey(key);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public get options() {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.options;\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public setOptions(options: Record<string, any>) {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.setOptions(options || {});\n  }\n\n  /**\n   * Return the loaded driver instance for `driverName`, loading it on first\n   * call. Optional `runtimeOptions` follow the same merge-over-config rules\n   * as {@link load}; passing options after the driver has already been\n   * loaded throws to avoid silent swallowing.\n   */\n  public async driver(driverName: string, runtimeOptions?: Record<string, any>) {\n    if (this.loadedDrivers[driverName]) {\n      this.assertNoConflictingReload(driverName, runtimeOptions);\n\n      return this.loadedDrivers[driverName];\n    }\n\n    return this.load(driverName, runtimeOptions);\n  }\n\n  /**\n   * Initialize the cache manager and pick the default driver\n   */\n  public async init() {\n    const defaultCacheDriverName = this.configurations.default;\n\n    if (!defaultCacheDriverName) {\n      return;\n    }\n\n    const driver = await this.driver(defaultCacheDriverName);\n\n    await this.use(driver);\n  }\n\n  /**\n   * Load and connect the registered driver named `driver`. First-call wins —\n   * subsequent calls without `runtimeOptions` return the cached instance, and\n   * subsequent calls *with* `runtimeOptions` throw {@link CacheConfigurationError}\n   * to avoid silently dropping the new options.\n   *\n   * `runtimeOptions` merge over `config.options[driver]` per-key (runtime wins),\n   * letting consumers split static knobs (table, ttl, globalPrefix) from\n   * constructor-only ones (pg's `client`, custom adapters, etc.).\n   *\n   * @example\n   * const pool = new Pool({ connectionString });\n   * const pg = await cache.load(\"pg\", { client: pool });\n   */\n  public async load(driver: string, runtimeOptions?: Record<string, any>) {\n    if (this.loadedDrivers[driver]) {\n      this.assertNoConflictingReload(driver, runtimeOptions);\n\n      return this.loadedDrivers[driver];\n    }\n\n    const inFlight = this.loadingDrivers.get(driver);\n\n    if (inFlight) {\n      this.assertNoConflictingReload(driver, runtimeOptions);\n\n      return inFlight;\n    }\n\n    const Driver = this.configurations.drivers[\n      driver as keyof typeof this.configurations.drivers\n    ] as DriverClass | undefined;\n\n    if (!Driver) {\n      throw new CacheConfigurationError(\n        `Cache driver ${driver} is not found, please declare it in the cache drivers in the configurations list.`,\n      );\n    }\n\n    const driverInstance = new Driver();\n    const configOptions =\n      this.configurations.options[driver as keyof typeof this.configurations.options] || {};\n\n    driverInstance.setOptions({ ...configOptions, ...(runtimeOptions ?? {}) });\n\n    const promise = (async () => {\n      try {\n        await driverInstance.connect();\n\n        this.attachGlobalListeners(driverInstance);\n\n        this.loadedDrivers[driver] = driverInstance;\n\n        return driverInstance as CacheDriver<any, any>;\n      } finally {\n        this.loadingDrivers.delete(driver);\n      }\n    })();\n\n    this.loadingDrivers.set(driver, promise);\n\n    return promise;\n  }\n\n  /**\n   * Guard against silently dropping runtime options on a re-load. Once a\n   * driver has been instantiated, its options are frozen — calling `load` /\n   * `driver` / `use` again with a non-empty `runtimeOptions` would otherwise\n   * appear to work but actually use the original options. We throw instead\n   * so the misuse surfaces at the call site.\n   */\n  protected assertNoConflictingReload(\n    driverName: string,\n    runtimeOptions: Record<string, any> | undefined,\n  ): void {\n    if (runtimeOptions === undefined) {\n      return;\n    }\n\n    if (Object.keys(runtimeOptions).length === 0) {\n      return;\n    }\n\n    throw new CacheConfigurationError(\n      `Cache driver '${driverName}' is already loaded; runtime options on subsequent calls are ignored — register a second driver name if you need a different configuration.`,\n    );\n  }\n\n  /**\n   * Register and bind a driver\n   */\n  public registerDriver(driverName: string, driverClass: DriverClass) {\n    (this.configurations.drivers as Record<string, DriverClass>)[driverName] = driverClass;\n  }\n\n  /**\n   * Disconnect the cache manager\n   */\n  public async disconnect() {\n    const drivers = new Set<any>(Object.values(this.loadedDrivers));\n\n    if (this.currentDriver) {\n      drivers.add(this.currentDriver);\n    }\n\n    await Promise.allSettled([...drivers].map((driver) => driver.disconnect()));\n\n    for (const name of Object.keys(this.loadedDrivers)) {\n      delete this.loadedDrivers[name];\n    }\n\n    this.loadingDrivers.clear();\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async has(key: CacheKey): Promise<boolean> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.has(key);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async remember<T = any>(\n    key: CacheKey,\n    ttlOrOptions: CacheTtl | RememberOptions,\n    callback: () => Promise<T>,\n  ): Promise<T> {\n    this.ensureDriverInitialized();\n\n    const driverOverride =\n      ttlOrOptions && typeof ttlOrOptions === \"object\" && \"driver\" in ttlOrOptions\n        ? ttlOrOptions.driver\n        : undefined;\n\n    if (driverOverride) {\n      const driver = await this.load(driverOverride);\n      return driver.remember(key, ttlOrOptions, callback);\n    }\n\n    return this.currentDriver!.remember(key, ttlOrOptions, callback);\n  }\n\n  /**\n   * Stale-while-revalidate. Returns cached when fresh, returns the stale\n   * value plus a background refresh when within `freshTtl..staleTtl`,\n   * blocks like a normal miss past `staleTtl`. Honors per-call `driver`\n   * override the same way `remember()` does.\n   *\n   * @example\n   * const product = await cache.swr(\n   *   \"product.42\",\n   *   { freshTtl: \"1m\", staleTtl: \"1h\" },\n   *   () => db.products.find(42),\n   * );\n   */\n  public async swr<T = any>(\n    key: CacheKey,\n    options: CacheSwrOptions,\n    callback: () => Promise<T>,\n  ): Promise<T> {\n    this.ensureDriverInitialized();\n\n    const driverOverride = options.driver;\n\n    if (driverOverride) {\n      const driver = await this.load(driverOverride);\n\n      return driver.swr<T>(key, options, callback);\n    }\n\n    return this.currentDriver!.swr<T>(key, options, callback);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async pull(key: CacheKey): Promise<any | null> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.pull(key);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async forever(key: CacheKey, value: any): Promise<any> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.forever(key, value);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async increment(\n    key: CacheKey,\n    value?: number,\n    options?: { ttl?: CacheTtl },\n  ): Promise<number> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.increment(key, value, options);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async decrement(key: CacheKey, value?: number): Promise<number> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.decrement(key, value);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async many(keys: CacheKey[]): Promise<any[]> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.many(keys);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async setMany(items: Record<string, any>, ttl?: number): Promise<void> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.setMany(items, ttl);\n  }\n\n  /**\n   * Register a global event listener (applies to all drivers)\n   */\n  public on(event: CacheEventType, handler: CacheEventHandler): this {\n    if (!this.globalEventListeners.has(event)) {\n      this.globalEventListeners.set(event, new Set());\n    }\n    this.globalEventListeners.get(event)!.add(handler);\n\n    // Also attach to current driver if exists\n    if (this.currentDriver) {\n      this.currentDriver.on(event, handler);\n    }\n\n    // Attach to all loaded drivers\n    for (const driver of Object.values(this.loadedDrivers)) {\n      driver.on(event, handler);\n    }\n\n    return this;\n  }\n\n  /**\n   * Remove a global event listener\n   */\n  public off(event: CacheEventType, handler: CacheEventHandler): this {\n    const handlers = this.globalEventListeners.get(event);\n    if (handlers) {\n      handlers.delete(handler);\n    }\n\n    // Also remove from current driver\n    if (this.currentDriver) {\n      this.currentDriver.off(event, handler);\n    }\n\n    // Remove from all loaded drivers\n    for (const driver of Object.values(this.loadedDrivers)) {\n      driver.off(event, handler);\n    }\n\n    return this;\n  }\n\n  /**\n   * Register a one-time global event listener\n   */\n  public once(event: CacheEventType, handler: CacheEventHandler): this {\n    const onceHandler: CacheEventHandler = async (data) => {\n      await handler(data);\n      this.off(event, onceHandler);\n    };\n    return this.on(event, onceHandler);\n  }\n\n  /**\n   * Attach global listeners to a driver\n   */\n  protected attachGlobalListeners(driver: CacheDriver<any, any>) {\n    for (const [event, handlers] of this.globalEventListeners) {\n      for (const handler of handlers) {\n        driver.on(event, handler);\n      }\n    }\n  }\n\n  /**\n   * Set if not exists (atomic operation)\n   * Returns true if key was set, false if key already existed\n   * Note: Only supported by drivers that implement setNX (e.g., Redis)\n   */\n  public async setNX(key: CacheKey, value: any, ttl?: number): Promise<boolean> {\n    this.ensureDriverInitialized();\n\n    if (!this.currentDriver!.setNX) {\n      throw new Error(\n        `setNX is not supported by the current cache driver: ${this.currentDriver!.name}`,\n      );\n    }\n\n    return this.currentDriver!.setNX(key, value, ttl);\n  }\n\n  /**\n   * Create a tagged cache instance for the given tags\n   */\n  public tags(tags: string[]): TaggedCacheDriver {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.tags(tags);\n  }\n\n  /**\n   * Atomically read, transform, and write a cached value. Delegates to the current driver.\n   */\n  public async update<T = any>(\n    key: CacheKey,\n    fn: (current: T | null) => T | null | Promise<T | null>,\n    options?: { ttl?: CacheTtl },\n  ): Promise<T | null> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.update<T>(key, fn, options);\n  }\n\n  /**\n   * Shallow-merge a partial object into a cached value.\n   */\n  public async merge<T extends Record<string, any> = Record<string, any>>(\n    key: CacheKey,\n    partial: Partial<T>,\n    options?: { ttl?: CacheTtl },\n  ): Promise<T> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.merge<T>(key, partial, options);\n  }\n\n  /**\n   * Obtain a list accessor bound to the current driver.\n   */\n  public list<T = any>(key: CacheKey): CacheListAccessor<T> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.list<T>(key);\n  }\n\n  /**\n   * Acquire a distributed lock, run `fn`, and auto-release. Returns a\n   * {@link LockOutcome} discriminated union so callers can distinguish\n   * \"ran and got this value\" from \"skipped because someone else holds it\".\n   *\n   * Honors the `driver` option for per-call driver override, same as `set`\n   * and `remember`.\n   *\n   * @example\n   * const outcome = await cache.lock(\"lock.import\", \"5m\", async () => {\n   *   await runImport();\n   *   return \"done\";\n   * });\n   * if (!outcome.acquired) {\n   *   console.log(\"another worker is already importing\");\n   * }\n   */\n  public async lock<T>(\n    key: CacheKey,\n    ttlOrOptions: CacheTtl | LockOptions,\n    fn: () => Promise<T>,\n  ): Promise<LockOutcome<T>> {\n    this.ensureDriverInitialized();\n\n    const driverOverride =\n      ttlOrOptions && typeof ttlOrOptions === \"object\" && \"driver\" in ttlOrOptions\n        ? ttlOrOptions.driver\n        : undefined;\n\n    const driver = driverOverride ? await this.load(driverOverride) : this.currentDriver!;\n\n    return driver.lock<T>(key, ttlOrOptions as CacheTtl | Omit<LockOptions, \"driver\">, fn);\n  }\n\n  /**\n   * Similarity retrieval. Delegates to the current driver's `similar()` impl.\n   *\n   * Drivers that lack a similarity index throw {@link CacheUnsupportedError}.\n   *\n   * @example\n   * const hits = await cache.similar(await embed(query), { topK: 5, threshold: 0.7 });\n   */\n  /**\n   * Create a scoped view over the cache. Every key written through the\n   * returned scope is automatically prefixed with `prefix`; optional defaults\n   * (`ttl`, `tags`) flow through every write inside the scope.\n   *\n   * Per-call options always win over scope defaults. Scope tags merge\n   * additively with per-call tags. Nested scopes inherit from the parent.\n   *\n   * @example\n   * const chat = cache.namespace(\"chats.10\", { ttl: \"30d\" });\n   * await chat.set(\"messages.1\", msg);          // → \"chats.10.messages.1\", 30d\n   * await chat.set(\"draft\", d, { ttl: \"1h\" });  // per-call ttl wins\n   * await chat.namespace(\"typing\", { ttl: \"5s\" }).set(\"user.42\", true);\n   * await chat.clear();                          // wipe the whole scope\n   */\n  public namespace(prefix: string, options?: CacheNamespaceOptions): ScopedCacheContract {\n    this.ensureDriverInitialized();\n    return new ScopedCache(this, prefix, options);\n  }\n\n  public async similar<T = any>(\n    vector: number[],\n    options: CacheSimilarOptions,\n  ): Promise<CacheSimilarHit<T>[]> {\n    this.ensureDriverInitialized();\n    return this.currentDriver!.similar<T>(vector, options);\n  }\n}\n\nexport const cache = new CacheManager();\n"],"mappings":"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"}

package/esm/cached/auto-key.d.mts

@@ -19,7 +19,6 @@
  * deriveAutoKey("featured", []);        // "featured"
  * deriveAutoKey("user", [42]);          // "user.<16 hex chars>"
  */
-declare function deriveAutoKey(prefix: string, args: readonly unknown[]): string;
+export declare function deriveAutoKey(prefix: string, args: readonly unknown[]): string;
 //#endregion
-export { deriveAutoKey };
 //# sourceMappingURL=auto-key.d.mts.map

package/esm/cached/auto-key.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"auto-key.d.mts","names":[],"sources":["../../../../../../../../packages/cache/src/cached/auto-key.ts"],"mappings":";;AAuBA;;;;AAAsE;;;;;;;;;;;;;;;iBAAtD,aAAA,CAAc,MAAA,UAAgB,IAAwB"}
+{"version":3,"file":"auto-key.d.mts","names":[],"sources":["../../../../../../../../packages/cache/src/cached/auto-key.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;wBAuBgB,cAAc,gBAAgB"}

package/esm/cached/cached.d.mts

@@ -1,12 +1,11 @@
 import { CacheTtl } from "../types.mjs";
 import { CachedOptions } from "./normalize-args.mjs";
-
 //#region ../../packages/cache/src/cached/cached.d.ts
 /**
  * The shape returned by `cached()`. Callable like the wrapped function, plus
  * helpers for manual invalidation.
  */
-type CachedFn<Args extends unknown[], R> = ((...args: Args) => Promise<R>) & {
+export type CachedFn<Args extends unknown[], R> = ((...args: Args) => Promise<R>) & {
   /**
    * Drop the cache entry for a specific argument combination.
    *
@@ -46,9 +45,8 @@ type CachedFn<Args extends unknown[], R> = ((...args: Args) => Promise<R>) & {
  * // Manual invalidation — uses the same key scheme the wrapper uses internally.
  * await getUser.invalidate(42);
  */
-declare function cached<Args extends unknown[], R>(fn: (...args: Args) => Promise<R>, prefix: string): CachedFn<Args, R>;
-declare function cached<Args extends unknown[], R>(fn: (...args: Args) => Promise<R>, prefix: string, ttl: CacheTtl): CachedFn<Args, R>;
-declare function cached<Args extends unknown[], R>(fn: (...args: Args) => Promise<R>, options: CachedOptions<Args>): CachedFn<Args, R>;
+export declare function cached<Args extends unknown[], R>(fn: (...args: Args) => Promise<R>, prefix: string): CachedFn<Args, R>;
+export declare function cached<Args extends unknown[], R>(fn: (...args: Args) => Promise<R>, prefix: string, ttl: CacheTtl): CachedFn<Args, R>;
+export declare function cached<Args extends unknown[], R>(fn: (...args: Args) => Promise<R>, options: CachedOptions<Args>): CachedFn<Args, R>;
 //#endregion
-export { CachedFn, cached };
 //# sourceMappingURL=cached.d.mts.map

package/esm/cached/cached.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"cached.d.mts","names":[],"sources":["../../../../../../../../packages/cache/src/cached/cached.ts"],"mappings":";;;;;;AASA;;KAAY,QAAA,mCAA2C,IAAA,EAAM,IAAA,KAAS,OAAA,CAAQ,CAAA;EAAjB;;;;;;;EAQ3D,UAAA,IAAc,IAAA,EAAM,IAAA,GAAO,OAAA;AAAA;;;;;;;;;;AAAO;AAiCpC;;;;;;;;;;;;;;;;;;;;iBAAgB,MAAA,4BACd,EAAA,MAAQ,IAAA,EAAM,IAAA,KAAS,OAAA,CAAQ,CAAA,GAC/B,MAAA,WACC,QAAA,CAAS,IAAA,EAAM,CAAA;AAAA,iBACF,MAAA,4BACd,EAAA,MAAQ,IAAA,EAAM,IAAA,KAAS,OAAA,CAAQ,CAAA,GAC/B,MAAA,UACA,GAAA,EAAK,QAAA,GACJ,QAAA,CAAS,IAAA,EAAM,CAAA;AAAA,iBACF,MAAA,4BACd,EAAA,MAAQ,IAAA,EAAM,IAAA,KAAS,OAAA,CAAQ,CAAA,GAC/B,OAAA,EAAS,aAAA,CAAc,IAAA,IACtB,QAAA,CAAS,IAAA,EAAM,CAAA"}
+{"version":3,"file":"cached.d.mts","names":[],"sources":["../../../../../../../../packages/cache/src/cached/cached.ts"],"mappings":";;;;;;;YASY,SAAS,wBAAwB,UAAU,MAAM,SAAS,QAAQ;;;;;;;;EAQ5E,cAAc,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAiCb,OAAO,wBAAwB,GAC7C,QAAQ,MAAM,SAAS,QAAQ,IAC/B,iBACC,SAAS,MAAM;wBACF,OAAO,wBAAwB,GAC7C,QAAQ,MAAM,SAAS,QAAQ,IAC/B,gBACA,KAAK,WACJ,SAAS,MAAM;wBACF,OAAO,wBAAwB,GAC7C,QAAQ,MAAM,SAAS,QAAQ,IAC/B,SAAS,cAAc,QACtB,SAAS,MAAM"}

package/esm/cached/index.d.mts

@@ -1,3 +1,4 @@
 import { deriveAutoKey } from "./auto-key.mjs";
 import { CachedOptions, NormalizedCachedConfig, normalizeCachedArgs } from "./normalize-args.mjs";
-import { CachedFn, cached } from "./cached.mjs";
+import { CachedFn, cached } from "./cached.mjs";
+export { CachedFn, CachedOptions, NormalizedCachedConfig, cached, deriveAutoKey, normalizeCachedArgs };

package/esm/cached/index.mjs

@@ -2,4 +2,4 @@ import { deriveAutoKey } from "./auto-key.mjs";
 import { normalizeCachedArgs } from "./normalize-args.mjs";
 import { cached } from "./cached.mjs";
 
-export {  };
+export { cached, deriveAutoKey, normalizeCachedArgs };

package/esm/cached/normalize-args.d.mts

@@ -1,5 +1,4 @@
 import { CacheTtl } from "../types.mjs";
-
 //#region ../../packages/cache/src/cached/normalize-args.d.ts
 /**
  * Options accepted by the `cached()` factory in its verbose form. `key` is the
@@ -7,7 +6,7 @@ import { CacheTtl } from "../types.mjs";
  *
  * @see cached
  */
-type CachedOptions<Args extends unknown[]> = {
+export type CachedOptions<Args extends unknown[]> = {
   /**
    * Derive a cache key from the wrapped function's arguments. Must be pure and
    * deterministic — every call with equivalent inputs should produce the same
@@ -35,7 +34,7 @@ type CachedOptions<Args extends unknown[]> = {
  *
  * @internal
  */
-type NormalizedCachedConfig<Args extends unknown[]> = {
+export type NormalizedCachedConfig<Args extends unknown[]> = {
   key: (...args: Args) => string;
   ttl?: CacheTtl;
   tags?: string[];
@@ -45,7 +44,6 @@ type NormalizedCachedConfig<Args extends unknown[]> = {
  * Resolve the positional-or-options arguments of `cached()` into a single
  * normalized config. Keeps the wrapper body free of shape-checks.
  */
-declare function normalizeCachedArgs<Args extends unknown[]>(prefixOrOptions: string | CachedOptions<Args>, maybeTtl?: CacheTtl): NormalizedCachedConfig<Args>;
+export declare function normalizeCachedArgs<Args extends unknown[]>(prefixOrOptions: string | CachedOptions<Args>, maybeTtl?: CacheTtl): NormalizedCachedConfig<Args>;
 //#endregion
-export { CachedOptions, NormalizedCachedConfig, normalizeCachedArgs };
 //# sourceMappingURL=normalize-args.d.mts.map

package/esm/cached/normalize-args.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize-args.d.mts","names":[],"sources":["../../../../../../../../packages/cache/src/cached/normalize-args.ts"],"mappings":";;;;;AASA;;;;KAAY,aAAA;EAMV;;;;;EAAA,GAAA,MAAS,IAAA,EAAM,IAAA;EAcf;;AAAM;EAVN,GAAA,GAAM,QAAQ;EAmBkB;;;;EAdhC,IAAA;EAeS;;;;EAVT,MAAA;AAAA;;AAaM;AAOR;;;;KAXY,sBAAA;EACV,GAAA,MAAS,IAAA,EAAM,IAAA;EACf,GAAA,GAAM,QAAQ;EACd,IAAA;EACA,MAAA;AAAA;;;;;iBAOc,mBAAA,yBACd,eAAA,WAA0B,aAAA,CAAc,IAAA,GACxC,QAAA,GAAW,QAAA,GACV,sBAAA,CAAuB,IAAA"}
+{"version":3,"file":"normalize-args.d.mts","names":[],"sources":["../../../../../../../../packages/cache/src/cached/normalize-args.ts"],"mappings":";;;;;;;;YASY,cAAc;;;;;;EAMxB,SAAS,MAAM;;;;EAIf,MAAM;;;;;EAKN;;;;;EAKA;;;;;;;;YASU,uBAAuB;EACjC,SAAS,MAAM;EACf,MAAM;EACN;EACA;;;;;;wBAOc,oBAAoB,wBAClC,0BAA0B,cAAc,OACxC,WAAW,WACV,uBAAuB"}

package/esm/drivers/base-cache-driver.d.mts

@@ -1,5 +1,4 @@
 import { CacheConflictPolicy, CacheData, CacheDriver, CacheEventData, CacheEventHandler, CacheEventType, CacheKey, CacheListAccessor, CacheOperationType, CacheSetOptions, CacheSimilarHit, CacheSimilarOptions, CacheSwrOptions, CacheTtl, LockOptions, LockOutcome, RememberOptions } from "../types.mjs";
-
 //#region ../../packages/cache/src/drivers/base-cache-driver.d.ts
 /**
  * Normalized form of the 3rd `set` argument.
@@ -7,7 +6,7 @@ import { CacheConflictPolicy, CacheData, CacheDriver, CacheEventData, CacheEvent
  * All drivers operate on this shape internally regardless of whether the caller
  * passed a positional TTL, a duration string, or a rich options object.
  */
-type NormalizedSetOptions = {
+export type NormalizedSetOptions = {
   /**
    * Final TTL in seconds — already merged with the driver-level default
    * (`this.options.ttl`). `Infinity` means "no expiration".
@@ -39,7 +38,7 @@ type NormalizedSetOptions = {
    */
   staleAt?: number;
 };
-declare abstract class BaseCacheDriver<ClientType, Options extends Record<string, any>> implements CacheDriver<ClientType, Options> {
+export declare abstract class BaseCacheDriver<ClientType, Options extends Record<string, any>> implements CacheDriver<ClientType, Options> {
   /**
    * CLient driver
    */
@@ -292,7 +291,9 @@ declare abstract class BaseCacheDriver<ClientType, Options extends Record<string
    * The remaining TTL is rounded down, so repeated increments can never push
    * a window's deadline later.
    */
-  increment(key: CacheKey, value?: number): Promise<number>;
+  increment(key: CacheKey, value?: number, options?: {
+    ttl?: CacheTtl;
+  }): Promise<number>;
   /**
    * {@inheritdoc}
    */
@@ -422,5 +423,4 @@ declare abstract class BaseCacheDriver<ClientType, Options extends Record<string
   };
 }
 //#endregion
-export { BaseCacheDriver, NormalizedSetOptions };
 //# sourceMappingURL=base-cache-driver.d.mts.map

package/esm/drivers/base-cache-driver.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"base-cache-driver.d.mts","names":[],"sources":["../../../../../../../../packages/cache/src/drivers/base-cache-driver.ts"],"mappings":"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"}
+{"version":3,"file":"base-cache-driver.d.mts","names":[],"sources":["../../../../../../../../packages/cache/src/drivers/base-cache-driver.ts"],"mappings":"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"}

package/esm/drivers/base-cache-driver.mjs

@@ -408,7 +408,8 @@ var BaseCacheDriver = class {
 	* The remaining TTL is rounded down, so repeated increments can never push
 	* a window's deadline later.
 	*/
-	async increment(key, value = 1) {
+	async increment(key, value = 1, options = {}) {
+		const ttl = options.ttl === void 0 ? this.ttl : parseTtl(options.ttl);
 		const parsedKey = this.parseKey(key);
 		return this.runSerialized(parsedKey, async () => {
 			const entry = await this.getEntry(key);
@@ -419,8 +420,8 @@ var BaseCacheDriver = class {
 			const base = current === null || current === void 0 ? 0 : current;
 			if (typeof base !== "number") throw new Error(`Cannot increment non-numeric value for key: ${maskEmailsInText(parsedKey)}`);
 			const newValue = base + value;
-			if (!live) await this.set(key, newValue);
-			else if (expiresAt == null || expiresAt === Infinity) await this.set(key, newValue, { ttl: Infinity });
+			if (!live) await this.set(key, newValue, { ttl });
+			else if (expiresAt == null || expiresAt === Infinity) await this.set(key, newValue, { ttl: options.ttl === void 0 ? Infinity : ttl });
 			else await this.set(key, newValue, { ttl: Math.max(1, Math.floor((expiresAt - now) / 1e3)) });
 			return newValue;
 		});