@warlock.js/cache 4.0.171 → 4.1.1

package/esm/cache-manager.mjs

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

package/esm/cache-manager.mjs.map

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

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

@@ -0,0 +1,25 @@
+//#region ../../@warlock.js/cache/src/cached/auto-key.d.ts
+/**
+ * Derive a cache key from a prefix and a set of function arguments.
+ *
+ * Rules (in order of precedence):
+ * 1. No args → prefix alone.
+ * 2. All primitives (`string`, `number`, `boolean`) or `null` / `undefined` /
+ *    `bigint` → joined onto the prefix with dots.
+ * 3. Any non-primitive arg present → the full args array is `JSON.stringify`-ed
+ *    and appended to the prefix.
+ * 4. Serialization throws (circular refs, `BigInt` nested in an object) → we
+ *    re-throw as `CacheConfigurationError` so the caller sees a cache-scoped
+ *    error rather than a cryptic `TypeError`.
+ *
+ * @example
+ * deriveAutoKey("user", [42]);                         // "user.42"
+ * deriveAutoKey("orders", [42, "abc"]);                // "orders.42.abc"
+ * deriveAutoKey("featured", []);                       // "featured"
+ * deriveAutoKey("search", [{ q: "hello" }]);           // "search.[{\"q\":\"hello\"}]"
+ * deriveAutoKey("user", [null, undefined]);            // "user.null.undefined"
+ */
+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

@@ -0,0 +1 @@
+{"version":3,"file":"auto-key.d.mts","names":[],"sources":["../../../../../../@warlock.js/cache/src/cached/auto-key.ts"],"mappings":";;AAsBA;;;;AAAsE;;;;;;;;;;;;;;;iBAAtD,aAAA,CAAc,MAAA,UAAgB,IAAwB"}

package/esm/cached/auto-key.mjs

@@ -0,0 +1,55 @@
+import { CacheConfigurationError } from "../types.mjs";
+
+//#region ../../@warlock.js/cache/src/cached/auto-key.ts
+/**
+* Derive a cache key from a prefix and a set of function arguments.
+*
+* Rules (in order of precedence):
+* 1. No args → prefix alone.
+* 2. All primitives (`string`, `number`, `boolean`) or `null` / `undefined` /
+*    `bigint` → joined onto the prefix with dots.
+* 3. Any non-primitive arg present → the full args array is `JSON.stringify`-ed
+*    and appended to the prefix.
+* 4. Serialization throws (circular refs, `BigInt` nested in an object) → we
+*    re-throw as `CacheConfigurationError` so the caller sees a cache-scoped
+*    error rather than a cryptic `TypeError`.
+*
+* @example
+* deriveAutoKey("user", [42]);                         // "user.42"
+* deriveAutoKey("orders", [42, "abc"]);                // "orders.42.abc"
+* deriveAutoKey("featured", []);                       // "featured"
+* deriveAutoKey("search", [{ q: "hello" }]);           // "search.[{\"q\":\"hello\"}]"
+* deriveAutoKey("user", [null, undefined]);            // "user.null.undefined"
+*/
+function deriveAutoKey(prefix, args) {
+	if (args.length === 0) return prefix;
+	if (args.every(isPrimitiveOrNullish)) return prefix + "." + args.map(serializePrimitive).join(".");
+	try {
+		return prefix + "." + JSON.stringify(args);
+	} catch (error) {
+		throw new CacheConfigurationError(`cached(): could not derive an auto-key from args for prefix "${prefix}". The args include a value that is not JSON-serializable (circular reference, BigInt nested inside an object, or similar). Use the options form with a custom key function. Original error: ${error.message}`);
+	}
+}
+/**
+* Primitives and nullish values can be concatenated directly onto a key without
+* JSON serialization. Adding `bigint` here avoids the `JSON.stringify` throw on
+* top-level bigint args.
+*/
+function isPrimitiveOrNullish(value) {
+	if (value === null || value === void 0) return true;
+	const type = typeof value;
+	return type === "string" || type === "number" || type === "boolean" || type === "bigint";
+}
+/**
+* Serialize a single primitive or nullish value to its string key-segment form.
+*/
+function serializePrimitive(value) {
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	if (typeof value === "bigint") return value.toString();
+	return String(value);
+}
+
+//#endregion
+export { deriveAutoKey };
+//# sourceMappingURL=auto-key.mjs.map

package/esm/cached/auto-key.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-key.mjs","names":[],"sources":["../../../../../../@warlock.js/cache/src/cached/auto-key.ts"],"sourcesContent":["import { CacheConfigurationError } from \"../types\";\n\n/**\n * Derive a cache key from a prefix and a set of function arguments.\n *\n * Rules (in order of precedence):\n * 1. No args → prefix alone.\n * 2. All primitives (`string`, `number`, `boolean`) or `null` / `undefined` /\n *    `bigint` → joined onto the prefix with dots.\n * 3. Any non-primitive arg present → the full args array is `JSON.stringify`-ed\n *    and appended to the prefix.\n * 4. Serialization throws (circular refs, `BigInt` nested in an object) → we\n *    re-throw as `CacheConfigurationError` so the caller sees a cache-scoped\n *    error rather than a cryptic `TypeError`.\n *\n * @example\n * deriveAutoKey(\"user\", [42]);                         // \"user.42\"\n * deriveAutoKey(\"orders\", [42, \"abc\"]);                // \"orders.42.abc\"\n * deriveAutoKey(\"featured\", []);                       // \"featured\"\n * deriveAutoKey(\"search\", [{ q: \"hello\" }]);           // \"search.[{\\\"q\\\":\\\"hello\\\"}]\"\n * deriveAutoKey(\"user\", [null, undefined]);            // \"user.null.undefined\"\n */\nexport function deriveAutoKey(prefix: string, args: readonly unknown[]): string {\n  if (args.length === 0) {\n    return prefix;\n  }\n\n  if (args.every(isPrimitiveOrNullish)) {\n    return prefix + \".\" + args.map(serializePrimitive).join(\".\");\n  }\n\n  try {\n    return prefix + \".\" + JSON.stringify(args);\n  } catch (error) {\n    throw new CacheConfigurationError(\n      `cached(): could not derive an auto-key from args for prefix \"${prefix}\". ` +\n        `The args include a value that is not JSON-serializable (circular reference, ` +\n        `BigInt nested inside an object, or similar). Use the options form with a custom ` +\n        `key function. Original error: ${(error as Error).message}`,\n    );\n  }\n}\n\n/**\n * Primitives and nullish values can be concatenated directly onto a key without\n * JSON serialization. Adding `bigint` here avoids the `JSON.stringify` throw on\n * top-level bigint args.\n */\nfunction isPrimitiveOrNullish(value: unknown): boolean {\n  if (value === null || value === undefined) {\n    return true;\n  }\n\n  const type = typeof value;\n  return type === \"string\" || type === \"number\" || type === \"boolean\" || type === \"bigint\";\n}\n\n/**\n * Serialize a single primitive or nullish value to its string key-segment form.\n */\nfunction serializePrimitive(value: unknown): string {\n  if (value === null) return \"null\";\n  if (value === undefined) return \"undefined\";\n  if (typeof value === \"bigint\") return value.toString();\n  return String(value);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,cAAc,QAAgB,MAAkC;CAC9E,IAAI,KAAK,WAAW,GAClB,OAAO;CAGT,IAAI,KAAK,MAAM,oBAAoB,GACjC,OAAO,SAAS,MAAM,KAAK,IAAI,kBAAkB,EAAE,KAAK,GAAG;CAG7D,IAAI;EACF,OAAO,SAAS,MAAM,KAAK,UAAU,IAAI;CAC3C,SAAS,OAAO;EACd,MAAM,IAAI,wBACR,gEAAgE,OAAO,+LAGnC,MAAgB,SACtD;CACF;AACF;;;;;;AAOA,SAAS,qBAAqB,OAAyB;CACrD,IAAI,UAAU,QAAQ,UAAU,QAC9B,OAAO;CAGT,MAAM,OAAO,OAAO;CACpB,OAAO,SAAS,YAAY,SAAS,YAAY,SAAS,aAAa,SAAS;AAClF;;;;AAKA,SAAS,mBAAmB,OAAwB;CAClD,IAAI,UAAU,MAAM,OAAO;CAC3B,IAAI,UAAU,QAAW,OAAO;CAChC,IAAI,OAAO,UAAU,UAAU,OAAO,MAAM,SAAS;CACrD,OAAO,OAAO,KAAK;AACrB"}