@warlock.js/cache 5.19.1 → 5.21.0

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

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

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

@@ -1,7 +1,8 @@
-import { CacheUnsupportedError } from "../types.mjs";
+import { CacheConfigurationError, CacheUnsupportedError } from "../types.mjs";
 import { normalizeToOptions, parseCacheKey, parseTtl, resolveTtl, safeErrorInfo } from "../utils.mjs";
 import { MemoryCacheList } from "../list/memory-cache-list.mjs";
 import { TaggedCache } from "../tagged-cache.mjs";
+import { randomUUID } from "node:crypto";
 import { log } from "@warlock.js/logger";
 
 //#region ../cache/src/drivers/base-cache-driver.ts
@@ -29,7 +30,10 @@ var BaseCacheDriver = class {
 	constructor() {
 		this.shouldLog = true;
 		this.eventListeners = /* @__PURE__ */ new Map();
-		this.locks = /* @__PURE__ */ new Map();
+		this.rememberInFlight = /* @__PURE__ */ new Map();
+		this.swrFetchInFlight = /* @__PURE__ */ new Map();
+		this.swrRefreshes = /* @__PURE__ */ new Map();
+		this.updateChains = /* @__PURE__ */ new Map();
 	}
 	/**
 	* {@inheritdoc}
@@ -138,13 +142,67 @@ var BaseCacheDriver = class {
 		if (!tags || tags.length === 0) return null;
 		const allKeys = /* @__PURE__ */ new Set();
 		for (const tag of tags) {
-			const tagKey = `cache:tags:${tag}`;
-			const keys = await this.get(tagKey) || [];
+			const keys = await this.tagMembers(`cache:tags:${tag}`);
 			for (const k of keys) allKeys.add(this.parseKey(k));
 		}
 		return allKeys;
 	}
 	/**
+	* {@inheritdoc}
+	*
+	* Default implementation: the index is an ordinary entry holding a string
+	* array, read-modified-written under {@link runSerialized} — correct within
+	* THIS process only. Drivers with a native primitive override it (redis SET,
+	* pg atomic upsert, the in-process drivers' {@link InMemoryTagIndex}).
+	*/
+	async tagAdd(tagKey, members) {
+		if (members.length === 0) return;
+		await this.runSerialized(this.parseKey(tagKey), async () => {
+			const current = await this.readTagArray(tagKey);
+			const merged = new Set(current);
+			for (const member of members) merged.add(member);
+			if (merged.size !== current.length) await this.set(tagKey, [...merged], Infinity);
+		});
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async tagMembers(tagKey) {
+		return this.readTagArray(tagKey);
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Default implementation: serialized read-filter-write (process-local); an
+	* emptied index is removed.
+	*/
+	async tagRemove(tagKey, members) {
+		if (members.length === 0) return;
+		await this.runSerialized(this.parseKey(tagKey), async () => {
+			const current = await this.readTagArray(tagKey);
+			const dropped = new Set(members);
+			const kept = current.filter((member) => !dropped.has(member));
+			if (kept.length === current.length) return;
+			if (kept.length === 0) await this.remove(tagKey);
+			else await this.set(tagKey, kept, Infinity);
+		});
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async tagDelete(tagKey) {
+		await this.runSerialized(this.parseKey(tagKey), () => this.remove(tagKey));
+	}
+	/**
+	* The index stored as a plain entry, or `[]`. Non-string members (a corrupted
+	* or foreign value) are ignored rather than trusted.
+	*/
+	async readTagArray(tagKey) {
+		const value = await this.get(tagKey);
+		if (!Array.isArray(value)) return [];
+		return value.filter((member) => typeof member === "string");
+	}
+	/**
 	* Apply tag relationships after a successful write. Called by drivers once
 	* the value is in storage.
 	*
@@ -162,25 +220,44 @@ var BaseCacheDriver = class {
 		return await this.get(key) !== null;
 	}
 	/**
+	* Run `task` once per key at a time: concurrent callers for the same
+	* `parsedKey` share the in-flight promise registered in `inFlight`.
+	*/
+	singleFlight(inFlight, parsedKey, task) {
+		const existing = inFlight.get(parsedKey);
+		if (existing) return existing;
+		const promise = task().finally(() => {
+			if (inFlight.get(parsedKey) === promise) inFlight.delete(parsedKey);
+		});
+		inFlight.set(parsedKey, promise);
+		return promise;
+	}
+	/**
+	* Chain `task` after every earlier serialized task for the same key, so
+	* read-modify-write callers in THIS process run one at a time. This is
+	* process-local: it does not coordinate with other servers.
+	*/
+	runSerialized(parsedKey, task) {
+		const next = (this.updateChains.get(parsedKey) ?? Promise.resolve()).catch(() => void 0).then(task);
+		this.updateChains.set(parsedKey, next);
+		next.finally(() => {
+			if (this.updateChains.get(parsedKey) === next) this.updateChains.delete(parsedKey);
+		}).catch(() => void 0);
+		return next;
+	}
+	/**
 	* {@inheritdoc}
 	*/
 	async remember(key, ttlOrOptions, callback) {
 		const parsedKey = this.parseKey(key);
 		const setOptions = this.normalizeRememberOptions(ttlOrOptions);
 		const cachedValue = await this.get(key);
-		if (cachedValue) return cachedValue;
-		const existingLock = this.locks.get(parsedKey);
-		if (existingLock) return existingLock;
-		const promise = callback().then(async (result) => {
+		if (cachedValue !== null && cachedValue !== void 0) return cachedValue;
+		return this.singleFlight(this.rememberInFlight, parsedKey, async () => {
+			const result = await callback();
 			await this.set(key, result, setOptions);
-			this.locks.delete(parsedKey);
 			return result;
-		}).catch((err) => {
-			this.locks.delete(parsedKey);
-			throw err;
 		});
-		this.locks.set(parsedKey, promise);
-		return promise;
 	}
 	/**
 	* Resolve the TTL-or-options arg of `remember` into a `CacheSetOptions` object
@@ -198,8 +275,9 @@ var BaseCacheDriver = class {
 	*
 	* Default implementation: read raw entry, branch on freshness/staleness,
 	* trigger background refresh in the stale window, fall through to
-	* `callback` on miss/expiry. Concurrent stale-window callers share a
-	* single in-flight refresh via {@link locks}.
+	* `callback` on miss/expiry. Concurrent cold-miss callers share one fetch
+	* ({@link swrFetchInFlight}); concurrent stale-window callers share one
+	* background refresh ({@link swrRefreshes}).
 	*
 	* Drivers without a real {@link getEntry} override degrade gracefully —
 	* the synthetic entry has no `staleAt`, which the freshness check treats
@@ -214,7 +292,7 @@ var BaseCacheDriver = class {
 		const entry = await this.getEntry(key);
 		const now = Date.now();
 		const isExpired = entry?.expiresAt !== void 0 && entry.expiresAt <= now;
-		if (!entry || isExpired) return this.swrFetchAndStore(key, options, callback, freshSeconds, staleSeconds);
+		if (!entry || isExpired) return this.singleFlight(this.swrFetchInFlight, parsedKey, () => this.swrFetchAndStore(key, options, callback, freshSeconds, staleSeconds));
 		if (entry.staleAt === void 0 || entry.staleAt > now) return entry.data;
 		this.scheduleSwrRefresh(parsedKey, key, options, callback, freshSeconds, staleSeconds);
 		return entry.data;
@@ -273,7 +351,7 @@ var BaseCacheDriver = class {
 	* `error` — the stale-returning caller never sees the failure.
 	*/
 	scheduleSwrRefresh(parsedKey, key, options, callback, freshSeconds, staleSeconds) {
-		if (this.locks.has(parsedKey)) return;
+		if (this.swrRefreshes.has(parsedKey)) return;
 		let refresh;
 		refresh = (async () => {
 			try {
@@ -290,18 +368,25 @@ var BaseCacheDriver = class {
 					error
 				});
 			} finally {
-				if (this.locks.get(parsedKey) === refresh) this.locks.delete(parsedKey);
+				if (this.swrRefreshes.get(parsedKey) === refresh) this.swrRefreshes.delete(parsedKey);
 			}
 		})();
-		this.locks.set(parsedKey, refresh);
+		this.swrRefreshes.set(parsedKey, refresh);
 	}
 	/**
 	* {@inheritdoc}
+	*
+	* Default implementation: get-then-remove, serialized per key in THIS
+	* process. Drivers with a native primitive override it to be atomic across
+	* servers (redis `GETDEL`, pg `DELETE … RETURNING`) or process-atomic
+	* (memory, lru, mock).
 	*/
 	async pull(key) {
-		const value = await this.get(key);
-		if (value !== null) await this.remove(key);
-		return value;
+		return this.runSerialized(this.parseKey(key), async () => {
+			const value = await this.get(key);
+			if (value !== null) await this.remove(key);
+			return value;
+		});
 	}
 	/**
 	* {@inheritdoc}
@@ -311,13 +396,24 @@ var BaseCacheDriver = class {
 	}
 	/**
 	* {@inheritdoc}
+	*
+	* Default implementation: read-add-write serialized per key in THIS process,
+	* keeping the entry's remaining TTL (a missing key starts from 0 with the
+	* driver default TTL). Not atomic across servers: drivers with a native
+	* primitive override it (redis `INCRBY`, pg single-statement upsert).
 	*/
 	async increment(key, value = 1) {
-		const current = await this.get(key) || 0;
-		if (typeof current !== "number") throw new Error(`Cannot increment non-numeric value for key: ${this.parseKey(key)}`);
-		const newValue = current + value;
-		await this.set(key, newValue);
-		return newValue;
+		const parsedKey = this.parseKey(key);
+		return this.runSerialized(parsedKey, async () => {
+			const current = await this.get(key);
+			const base = current === null || current === void 0 ? 0 : current;
+			if (typeof base !== "number") throw new Error(`Cannot increment non-numeric value for key: ${parsedKey}`);
+			const newValue = base + value;
+			const remainingTtl = current === null ? void 0 : await this.getRemainingTtl(key);
+			if (remainingTtl !== void 0) await this.set(key, newValue, { ttl: remainingTtl });
+			else await this.set(key, newValue);
+			return newValue;
+		});
 	}
 	/**
 	* {@inheritdoc}
@@ -432,13 +528,12 @@ var BaseCacheDriver = class {
 	/**
 	* {@inheritdoc}
 	*
-	* Default implementation: read → transform → write under a per-key in-process
-	* lock. Drivers that can offer stronger semantics (Redis via `WATCH`/`MULTI`)
-	* should override.
+	* Default implementation: read → transform → write, serialized per key in
+	* THIS process only. Drivers that can offer cross-server atomicity (redis,
+	* pg: compare-and-set with retries) override it.
 	*/
 	async update(key, fn, options = {}) {
-		const parsedKey = this.parseKey(key);
-		const next = (this.locks.get(parsedKey) ?? Promise.resolve()).catch(() => void 0).then(async () => {
+		return this.runSerialized(this.parseKey(key), async () => {
 			const result = await fn(await this.get(key));
 			if (result === null) {
 				await this.remove(key);
@@ -453,11 +548,6 @@ var BaseCacheDriver = class {
 			else await this.set(key, result);
 			return result;
 		});
-		this.locks.set(parsedKey, next);
-		next.finally(() => {
-			if (this.locks.get(parsedKey) === next) this.locks.delete(parsedKey);
-		});
-		return next;
 	}
 	/**
 	* {@inheritdoc}
@@ -487,12 +577,16 @@ var BaseCacheDriver = class {
 	* The lock value is the resolved `owner` (defaults to `pid.<process.pid>`).
 	*
 	* Always releases in `finally`, even if `fn` throws — the thrown error
-	* propagates to the caller unchanged.
+	* propagates to the caller unchanged, and a failed release is logged rather
+	* than replacing `fn`'s result or error. The ttl must be finite and
+	* positive; there is no renewal, so it must exceed the worst-case duration.
 	*/
 	async lock(key, ttlOrOptions, fn) {
 		const { ttl, owner } = this.normalizeLockOptions(ttlOrOptions);
-		const lockOwner = owner ?? `pid.${process.pid}`;
-		const setResult = await this.set(key, lockOwner, {
+		const ttlSeconds = parseTtl(ttl);
+		if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) throw new CacheConfigurationError(`cache.lock() requires a finite, positive ttl (got ${String(ttl)}). The ttl must exceed the worst-case duration of the locked work.`);
+		const lockValue = `${owner ?? `pid.${process.pid}`}#${randomUUID()}`;
+		const setResult = await this.set(key, lockValue, {
 			onConflict: "create",
 			ttl
 		});
@@ -503,10 +597,26 @@ var BaseCacheDriver = class {
 				value: await fn()
 			};
 		} finally {
-			await this.remove(key);
+			try {
+				await this.deleteIfEquals(key, lockValue);
+			} catch (error) {
+				this.logError(`lock release failed for ${this.parseKey(key)}`, error);
+			}
 		}
 	}
 	/**
+	* Compare-and-delete: remove `key` only when its current value equals
+	* `expected`. Returns whether a delete happened.
+	*
+	* This default is get-then-remove and is NOT atomic across processes; drivers
+	* with a real primitive (memory, redis, pg) override it.
+	*/
+	async deleteIfEquals(key, expected) {
+		if (await this.get(key) !== expected) return false;
+		await this.remove(key);
+		return true;
+	}
+	/**
 	* {@inheritdoc}
 	*
 	* Default implementation throws {@link CacheUnsupportedError}. Drivers that

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

@@ -1 +1 @@
-{"version":3,"file":"base-cache-driver.mjs","names":[],"sources":["../../../../../../../cache/src/drivers/base-cache-driver.ts"],"sourcesContent":["import { log } from \"@warlock.js/logger\";\r\nimport { MemoryCacheList } from \"../list/memory-cache-list\";\r\nimport { TaggedCache } from \"../tagged-cache\";\r\nimport type {\r\n  CacheConflictPolicy,\r\n  CacheData,\r\n  CacheDriver,\r\n  CacheEventData,\r\n  CacheEventHandler,\r\n  CacheEventType,\r\n  CacheKey,\r\n  CacheListAccessor,\r\n  CacheOperationType,\r\n  CacheSetOptions,\r\n  CacheSetResult,\r\n  CacheSimilarHit,\r\n  CacheSimilarOptions,\r\n  CacheSwrOptions,\r\n  CacheTtl,\r\n  LockOptions,\r\n  LockOutcome,\r\n  RememberOptions,\r\n} from \"../types\";\r\nimport { CacheUnsupportedError } from \"../types\";\r\nimport {\r\n  normalizeToOptions,\r\n  parseCacheKey,\r\n  parseTtl,\r\n  resolveTtl,\r\n  safeErrorInfo,\r\n} from \"../utils\";\r\n\r\n/**\r\n * Normalized form of the 3rd `set` argument.\r\n *\r\n * All drivers operate on this shape internally regardless of whether the caller\r\n * passed a positional TTL, a duration string, or a rich options object.\r\n */\r\nexport type NormalizedSetOptions = {\r\n  /**\r\n   * Final TTL in seconds — already merged with the driver-level default\r\n   * (`this.options.ttl`). `Infinity` means \"no expiration\".\r\n   *\r\n   * Always populated. Drivers do NOT need to fall back to `this.ttl`\r\n   * themselves — `resolveSetOptions` does the merge centrally so that\r\n   * every driver respects the configured default without ceremony.\r\n   */\r\n  ttl: number;\r\n  /**\r\n   * Inline tag list, or undefined when none were provided.\r\n   */\r\n  tags?: string[];\r\n  /**\r\n   * Conflict policy. Defaults to `\"upsert\"`.\r\n   */\r\n  onConflict: CacheConflictPolicy;\r\n  /**\r\n   * Optional embedding vector for similarity retrieval. Drivers that do not\r\n   * support similarity must throw {@link CacheUnsupportedError} when this is\r\n   * present (rather than silently dropping it).\r\n   */\r\n  vector?: number[];\r\n  /**\r\n   * Optional freshness deadline as a millisecond timestamp. Set by `swr()`\r\n   * to mark when the entry stops being \"fresh\" and becomes\r\n   * \"stale-but-revalidatable.\" Drivers route this through\r\n   * `prepareDataForStorage` so it persists in the wrapper.\r\n   */\r\n  staleAt?: number;\r\n};\r\n\r\nconst messages = {\r\n  clearing: \"Clearing namespace\",\r\n  cleared: \"Namespace cleared\",\r\n  fetching: \"Fetching key\",\r\n  fetched: \"Key fetched\",\r\n  caching: \"Caching key\",\r\n  cached: \"Key cached\",\r\n  flushing: \"Flushing cache\",\r\n  flushed: \"Cache flushed\",\r\n  removing: \"Removing key\",\r\n  removed: \"Key removed\",\r\n  expired: \"Key expired\",\r\n  notFound: \"Key not found\",\r\n  connecting: \"Connecting to the cache engine.\",\r\n  connected: \"Connected to the cache engine.\",\r\n  disconnecting: \"Disconnecting from the cache engine.\",\r\n  disconnected: \"Disconnected from the cache engine.\",\r\n  connectionFailed: \"Failed to connect to the cache engine.\",\r\n  error: \"Error occurred\",\r\n};\r\n\r\nexport abstract class BaseCacheDriver<\r\n  ClientType,\r\n  Options extends Record<string, any>,\r\n> implements CacheDriver<ClientType, Options> {\r\n  /**\r\n   * CLient driver\r\n   */\r\n  protected clientDriver!: ClientType;\r\n\r\n  /**\r\n   * Determine whether to log or not\r\n   */\r\n  protected shouldLog: boolean = true;\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public get client() {\r\n    return (this.clientDriver || this) as unknown as ClientType;\r\n  }\r\n\r\n  /**\r\n   * Set logging state\r\n   */\r\n  public setLoggingState(shouldLog: boolean) {\r\n    this.shouldLog = shouldLog;\r\n\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * Set client driver\r\n   */\r\n  public set client(client: ClientType) {\r\n    this.clientDriver = client;\r\n  }\r\n\r\n  /**\r\n   * Get the cache driver name\r\n   */\r\n  public abstract name: string;\r\n\r\n  /**\r\n   * Options list\r\n   */\r\n  public options!: Options;\r\n\r\n  /**\r\n   * Event listeners storage\r\n   */\r\n  protected eventListeners: Map<CacheEventType, Set<CacheEventHandler>> =\r\n    new Map();\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public parseKey(key: CacheKey) {\r\n    return parseCacheKey(key, this.options);\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public setOptions(options: Options) {\r\n    this.options = options || {};\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * Register an event listener\r\n   */\r\n  public on(event: CacheEventType, handler: CacheEventHandler): this {\r\n    if (!this.eventListeners.has(event)) {\r\n      this.eventListeners.set(event, new Set());\r\n    }\r\n    this.eventListeners.get(event)!.add(handler);\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * Remove an event listener\r\n   */\r\n  public off(event: CacheEventType, handler: CacheEventHandler): this {\r\n    const handlers = this.eventListeners.get(event);\r\n    if (handlers) {\r\n      handlers.delete(handler);\r\n    }\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * Register a one-time 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   * Emit an event to all registered listeners\r\n   */\r\n  protected async emit(\r\n    event: CacheEventType,\r\n    data: Partial<CacheEventData> = {},\r\n  ): Promise<void> {\r\n    const handlers = this.eventListeners.get(event);\r\n    if (!handlers || handlers.size === 0) return;\r\n\r\n    const eventData: CacheEventData = {\r\n      driver: this.name,\r\n      ...data,\r\n    };\r\n\r\n    // Execute all handlers\r\n    const promises: Promise<void>[] = [];\r\n    for (const handler of handlers) {\r\n      try {\r\n        const result = handler(eventData);\r\n        if (result instanceof Promise) {\r\n          promises.push(result);\r\n        }\r\n      } catch (error) {\r\n        this.logError(`Error in event handler for '${event}'`, error);\r\n      }\r\n    }\r\n\r\n    // Wait for all async handlers\r\n    if (promises.length > 0) {\r\n      await Promise.allSettled(promises);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public abstract removeNamespace(namespace: string): Promise<any>;\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public abstract set(\r\n    key: CacheKey,\r\n    value: any,\r\n    ttlOrOptions?: CacheTtl | CacheSetOptions,\r\n  ): Promise<any>;\r\n\r\n  /**\r\n   * Normalize the 3rd argument of a `set` call into a single shape every driver\r\n   * can act on. Handles TTL parsing (number | string | Infinity), `expiresAt` →\r\n   * relative TTL conversion, and mutual-exclusion validation.\r\n   *\r\n   * @throws {CacheConfigurationError} when `ttl` and `expiresAt` are passed together\r\n   * or an unparseable duration string is supplied.\r\n   */\r\n  protected resolveSetOptions(\r\n    ttlOrOptions?: CacheTtl | CacheSetOptions,\r\n  ): NormalizedSetOptions {\r\n    const options = normalizeToOptions(ttlOrOptions);\r\n\r\n    return {\r\n      ttl: resolveTtl(options.ttl, options.expiresAt, this.ttl),\r\n      tags: options.tags,\r\n      onConflict: options.onConflict ?? \"upsert\",\r\n      vector: options.vector,\r\n      staleAt: options.staleAt,\r\n    };\r\n  }\r\n\r\n  /**\r\n   * Resolve the union of cache keys associated with any of the given tags.\r\n   * Used by `similar()` to narrow the candidate pool before similarity ranking.\r\n   *\r\n   * Returns `null` when no tags are passed (callers should treat that as \"no filter\").\r\n   * Keys come back parsed (prefixed) — the index stores them un-prefixed, but\r\n   * callers match them against their own parsed storage keys.\r\n   */\r\n  protected async getKeysForTags(\r\n    tags: string[] | undefined,\r\n  ): Promise<Set<string> | null> {\r\n    if (!tags || tags.length === 0) {\r\n      return null;\r\n    }\r\n\r\n    const allKeys = new Set<string>();\r\n    for (const tag of tags) {\r\n      const tagKey = `cache:tags:${tag}`;\r\n      const keys = ((await this.get(tagKey)) as string[] | null) || [];\r\n      for (const k of keys) {\r\n        allKeys.add(this.parseKey(k));\r\n      }\r\n    }\r\n\r\n    return allKeys;\r\n  }\r\n\r\n  /**\r\n   * Apply tag relationships after a successful write. Called by drivers once\r\n   * the value is in storage.\r\n   *\r\n   * Pass the caller's key, not the parsed one: the tag index stores keys\r\n   * un-prefixed so `invalidate()` can delete them through `remove(key)`.\r\n   */\r\n  protected async applyTags(key: CacheKey, tags: string[]): Promise<void> {\r\n    if (tags.length === 0) {\r\n      return;\r\n    }\r\n\r\n    const tagged = this.tags(tags);\r\n    await (tagged as TaggedCache).storeTagRelationship(key);\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public abstract get(key: CacheKey): Promise<any>;\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public abstract remove(key: CacheKey): Promise<void>;\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public abstract flush(): Promise<void>;\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async has(key: CacheKey): Promise<boolean> {\r\n    const value = await this.get(key);\r\n    // Event is emitted by get() method\r\n    return value !== null;\r\n  }\r\n\r\n  /**\r\n   * Lock storage for preventing cache stampede\r\n   */\r\n  protected locks: Map<string, Promise<any>> = new Map();\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async remember(\r\n    key: CacheKey,\r\n    ttlOrOptions: CacheTtl | RememberOptions,\r\n    callback: () => Promise<any>,\r\n  ): Promise<any> {\r\n    const parsedKey = this.parseKey(key);\r\n\r\n    // The options-form lets callers forward tags / driver-override through to\r\n    // the cache-miss write. Normalize both shapes into a single CacheSetOptions\r\n    // blob so there's one path from here on.\r\n    const setOptions = this.normalizeRememberOptions(ttlOrOptions);\r\n\r\n    const cachedValue = await this.get(key);\r\n    if (cachedValue) {\r\n      return cachedValue;\r\n    }\r\n\r\n    const existingLock = this.locks.get(parsedKey);\r\n    if (existingLock) {\r\n      return existingLock;\r\n    }\r\n\r\n    const promise = callback()\r\n      .then(async (result) => {\r\n        await this.set(key, result, setOptions);\r\n        this.locks.delete(parsedKey);\r\n        return result;\r\n      })\r\n      .catch((err) => {\r\n        this.locks.delete(parsedKey);\r\n        throw err;\r\n      });\r\n\r\n    this.locks.set(parsedKey, promise);\r\n    return promise;\r\n  }\r\n\r\n  /**\r\n   * Resolve the TTL-or-options arg of `remember` into a `CacheSetOptions` object\r\n   * that can be passed straight to `set()`. Keeps the implementation unbranched.\r\n   */\r\n  protected normalizeRememberOptions(\r\n    ttlOrOptions: CacheTtl | RememberOptions,\r\n  ): CacheSetOptions {\r\n    if (typeof ttlOrOptions === \"number\" || typeof ttlOrOptions === \"string\") {\r\n      return { ttl: ttlOrOptions };\r\n    }\r\n\r\n    return {\r\n      ttl: ttlOrOptions.ttl,\r\n      tags: ttlOrOptions.tags,\r\n    };\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   *\r\n   * Default implementation: read raw entry, branch on freshness/staleness,\r\n   * trigger background refresh in the stale window, fall through to\r\n   * `callback` on miss/expiry. Concurrent stale-window callers share a\r\n   * single in-flight refresh via {@link locks}.\r\n   *\r\n   * Drivers without a real {@link getEntry} override degrade gracefully —\r\n   * the synthetic entry has no `staleAt`, which the freshness check treats\r\n   * as \"always fresh,\" so SWR behaves like a TTL-only cached read on those\r\n   * drivers (no background refresh, but no double-fetch either).\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    const parsedKey = this.parseKey(key);\r\n    const freshSeconds = parseTtl(options.freshTtl);\r\n    const staleSeconds = parseTtl(options.staleTtl);\r\n\r\n    if (staleSeconds <= freshSeconds) {\r\n      throw new Error(\r\n        `cache.swr: 'staleTtl' (${staleSeconds}s) must be greater than 'freshTtl' (${freshSeconds}s).`,\r\n      );\r\n    }\r\n\r\n    const entry = await this.getEntry(key);\r\n    const now = Date.now();\r\n\r\n    const isExpired = entry?.expiresAt !== undefined && entry.expiresAt <= now;\r\n\r\n    if (!entry || isExpired) {\r\n      return this.swrFetchAndStore<T>(\r\n        key,\r\n        options,\r\n        callback,\r\n        freshSeconds,\r\n        staleSeconds,\r\n      );\r\n    }\r\n\r\n    const isFresh = entry.staleAt === undefined || entry.staleAt > now;\r\n\r\n    if (isFresh) {\r\n      return entry.data as T;\r\n    }\r\n\r\n    this.scheduleSwrRefresh<T>(\r\n      parsedKey,\r\n      key,\r\n      options,\r\n      callback,\r\n      freshSeconds,\r\n      staleSeconds,\r\n    );\r\n\r\n    return entry.data as T;\r\n  }\r\n\r\n  /**\r\n   * Read the raw {@link CacheData} wrapper for a key, including any\r\n   * `expiresAt` / `staleAt` metadata. Default implementation falls back to\r\n   * `get()` and synthesizes a metadata-less wrapper — drivers that store\r\n   * the wrapper directly (memory, lru, file, redis, pg, mock) override\r\n   * this to return real metadata so SWR can branch on freshness.\r\n   */\r\n  protected async getEntry(key: CacheKey): Promise<CacheData | null> {\r\n    const value = await this.get(key);\r\n\r\n    if (value === null) {\r\n      return null;\r\n    }\r\n\r\n    return { data: value };\r\n  }\r\n\r\n  /**\r\n   * Remaining lifetime of an existing entry, in seconds — used by TTL-preserving\r\n   * writes such as `update()` / `merge()` when the caller passes no explicit\r\n   * `ttl`.\r\n   *\r\n   * - `Infinity` — the entry exists with no expiry (preserve \"never expires\").\r\n   * - positive number — seconds left before the entry expires.\r\n   * - `undefined` — the key is missing or already past its deadline; the caller\r\n   *   should fall back to the driver default TTL.\r\n   *\r\n   * Default reads `expiresAt` from {@link getEntry}, which the metadata-aware\r\n   * drivers (memory, lru, mock, pg) populate. Drivers that track TTL natively\r\n   * and don't carry `expiresAt` in their payload (Redis) override this.\r\n   */\r\n  protected async getRemainingTtl(key: CacheKey): Promise<number | undefined> {\r\n    const entry = await this.getEntry(key);\r\n\r\n    if (!entry) {\r\n      return undefined;\r\n    }\r\n\r\n    if (!entry.expiresAt || entry.expiresAt === Infinity) {\r\n      return Infinity;\r\n    }\r\n\r\n    const remainingSeconds = Math.ceil((entry.expiresAt - Date.now()) / 1000);\r\n\r\n    return remainingSeconds > 0 ? remainingSeconds : undefined;\r\n  }\r\n\r\n  /**\r\n   * Block-and-fetch path of `swr()`: invoked on miss or past-`staleTtl`\r\n   * expiry. Writes through `set()` with the SWR options translated into\r\n   * standard `CacheSetOptions` (ttl = staleTtl, staleAt = now + freshTtl).\r\n   */\r\n  protected async swrFetchAndStore<T>(\r\n    key: CacheKey,\r\n    options: CacheSwrOptions,\r\n    callback: () => Promise<T>,\r\n    freshSeconds: number,\r\n    staleSeconds: number,\r\n  ): Promise<T> {\r\n    const result = await callback();\r\n\r\n    await this.set(key, result, {\r\n      ttl: staleSeconds,\r\n      staleAt: Date.now() + freshSeconds * 1000,\r\n      tags: options.tags,\r\n    });\r\n\r\n    return result;\r\n  }\r\n\r\n  /**\r\n   * Stale-window background refresh. Registers a single in-flight promise\r\n   * per parsed key so concurrent SWR callers share one refresh. Failed\r\n   * refreshes preserve the stale entry, log via `logError`, and emit on\r\n   * `error` — the stale-returning caller never sees the failure.\r\n   */\r\n  protected scheduleSwrRefresh<T>(\r\n    parsedKey: string,\r\n    key: CacheKey,\r\n    options: CacheSwrOptions,\r\n    callback: () => Promise<T>,\r\n    freshSeconds: number,\r\n    staleSeconds: number,\r\n  ): void {\r\n    if (this.locks.has(parsedKey)) {\r\n      return;\r\n    }\r\n\r\n    let refresh!: Promise<void>;\r\n    refresh = (async () => {\r\n      try {\r\n        const result = await callback();\r\n\r\n        await this.set(key, result, {\r\n          ttl: staleSeconds,\r\n          staleAt: Date.now() + freshSeconds * 1000,\r\n          tags: options.tags,\r\n        });\r\n      } catch (error) {\r\n        this.logError(`SWR background refresh failed for ${parsedKey}`, error);\r\n        await this.emit(\"error\", { key: parsedKey, error });\r\n      } finally {\r\n        if (this.locks.get(parsedKey) === refresh) {\r\n          this.locks.delete(parsedKey);\r\n        }\r\n      }\r\n    })();\r\n\r\n    this.locks.set(parsedKey, refresh);\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async pull(key: CacheKey): Promise<any | null> {\r\n    const value = await this.get(key);\r\n    if (value !== null) {\r\n      await this.remove(key);\r\n    }\r\n    // Events are emitted by get() and remove() methods\r\n    return value;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async forever(key: CacheKey, value: any): Promise<any> {\r\n    // Event is emitted by set() method\r\n    return this.set(key, value, Infinity);\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async increment(key: CacheKey, value: number = 1): Promise<number> {\r\n    const current = (await this.get(key)) || 0;\r\n\r\n    if (typeof current !== \"number\") {\r\n      throw new Error(\r\n        `Cannot increment non-numeric value for key: ${this.parseKey(key)}`,\r\n      );\r\n    }\r\n\r\n    const newValue = current + value;\r\n    await this.set(key, newValue);\r\n    return newValue;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async decrement(key: CacheKey, value: number = 1): Promise<number> {\r\n    return this.increment(key, -value);\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async many(keys: CacheKey[]): Promise<any[]> {\r\n    return Promise.all(keys.map((key) => this.get(key)));\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async setMany(\r\n    items: Record<string, any>,\r\n    ttl?: number,\r\n  ): Promise<void> {\r\n    await Promise.all(\r\n      Object.entries(items).map(([key, value]) => this.set(key, value, ttl)),\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Log the operation\r\n   */\r\n  protected log(operation: CacheOperationType, key?: string | any) {\r\n    if (!this.shouldLog) return;\r\n\r\n    if (typeof key === \"string\") {\r\n      // this will be likely used with file cache driver as it will convert the dot to slash\r\n      // to make it consistent and not to confuse developers we will output the key by making sure it's a dot\r\n      key = key.replace(/\\//g, \".\");\r\n    }\r\n\r\n    if (operation === \"connectionFailed\") {\r\n      log.fatal(`cache.${this.name}`, operation, key);\r\n    }\r\n\r\n    if (operation == \"notFound\" || operation == \"expired\") {\r\n      return log.info(\r\n        \"cache.\" + this.name,\r\n        operation,\r\n        (key ? key + \" \" : \"\") + messages[operation],\r\n      );\r\n    }\r\n\r\n    if (operation.endsWith(\"ed\")) {\r\n      return log.success(\r\n        \"cache.\" + this.name,\r\n        operation,\r\n        (key ? key + \" \" : \"\") + messages[operation],\r\n      );\r\n    }\r\n\r\n    log.info(\r\n      \"cache.\" + this.name,\r\n      operation,\r\n      (key ? key + \" \" : \"\") + messages[operation],\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Log error message\r\n   *\r\n   * Never logs the raw `error` object — driver connection errors (Redis,\r\n   * Postgres, ...) can carry the connection string, including the password,\r\n   * in the message/cause. Only a redacted `{ message, code }` shape is\r\n   * passed to the structured logger.\r\n   */\r\n  protected logError(message: string, error?: any) {\r\n    if (error) {\r\n      log.error(\"cache.\" + this.name, \"error\", message, safeErrorInfo(error));\r\n    } else {\r\n      log.error(\"cache.\" + this.name, \"error\", message);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get the default TTL in seconds. Parses human-readable strings (`\"1h\"`, `\"30m\"`)\r\n   * from driver options if present; falls back to `Infinity` when no default is set.\r\n   */\r\n  public get ttl() {\r\n    if (this.options.ttl === undefined) {\r\n      return Infinity;\r\n    }\r\n\r\n    return parseTtl(this.options.ttl);\r\n  }\r\n\r\n  /**\r\n   * Get time to live value in milliseconds\r\n   */\r\n  public getExpiresAt(ttl: number = this.ttl) {\r\n    if (ttl) {\r\n      return new Date().getTime() + ttl * 1000;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Wrap a value with TTL and optional freshness metadata for backend\r\n   * storage. `staleAt` persists alongside `expiresAt` when supplied — used\r\n   * by the SWR flow to mark when the entry stops being fresh.\r\n   */\r\n  protected prepareDataForStorage(data: any, ttl?: number, staleAt?: number) {\r\n    const preparedData: CacheData = {\r\n      data,\r\n    };\r\n\r\n    if (ttl) {\r\n      preparedData.ttl = ttl;\r\n      preparedData.expiresAt = this.getExpiresAt(ttl);\r\n    }\r\n\r\n    if (staleAt !== undefined) {\r\n      preparedData.staleAt = staleAt;\r\n    }\r\n\r\n    return preparedData;\r\n  }\r\n\r\n  /**\r\n   * Parse fetched data from cache\r\n   */\r\n  protected async parseCachedData(key: string, data: CacheData) {\r\n    this.log(\"fetched\", key);\r\n\r\n    if (data.expiresAt && data.expiresAt < Date.now()) {\r\n      this.remove(key);\r\n      return null;\r\n    }\r\n\r\n    const value = data.data;\r\n\r\n    // Skip cloning for primitives (immutable types)\r\n    if (value === null || value === undefined) {\r\n      return value;\r\n    }\r\n\r\n    const type = typeof value;\r\n    if (type === \"string\" || type === \"number\" || type === \"boolean\") {\r\n      return value;\r\n    }\r\n\r\n    // Deep clone objects/arrays to prevent cache mutation\r\n    try {\r\n      return structuredClone(value);\r\n    } catch (error) {\r\n      this.logError(\r\n        `Failed to clone cached value for ${key}, typeof value: ${typeof value}`,\r\n        error,\r\n      );\r\n      throw error;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async connect() {\r\n    this.log(\"connecting\");\r\n    this.log(\"connected\");\r\n    await this.emit(\"connected\");\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async disconnect() {\r\n    this.log(\"disconnected\");\r\n    await this.emit(\"disconnected\");\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[]): any {\r\n    return new TaggedCache(tags, this);\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   *\r\n   * Default implementation: read → transform → write under a per-key in-process\r\n   * lock. Drivers that can offer stronger semantics (Redis via `WATCH`/`MULTI`)\r\n   * should override.\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    const parsedKey = this.parseKey(key);\r\n\r\n    // Chain each update onto the previous one for the same key so concurrent\r\n    // callers are serialized end-to-end, not merely awakened together when an\r\n    // earlier lock resolves.\r\n    const previous = this.locks.get(parsedKey) ?? Promise.resolve();\r\n\r\n    const next = previous\r\n      .catch(() => undefined)\r\n      .then(async () => {\r\n        const current = (await this.get(key)) as T | null;\r\n        const result = await fn(current);\r\n\r\n        if (result === null) {\r\n          await this.remove(key);\r\n          return null;\r\n        }\r\n\r\n        if (options.ttl !== undefined) {\r\n          await this.set(key, result, { ttl: options.ttl });\r\n\r\n          return result;\r\n        }\r\n\r\n        // No explicit TTL → preserve the existing entry's remaining lifetime\r\n        // rather than resetting it to the driver default.\r\n        const remainingTtl = await this.getRemainingTtl(key);\r\n\r\n        if (remainingTtl !== undefined) {\r\n          await this.set(key, result, { ttl: remainingTtl });\r\n        } else {\r\n          await this.set(key, result);\r\n        }\r\n\r\n        return result;\r\n      });\r\n\r\n    this.locks.set(parsedKey, next);\r\n\r\n    // Clean up the slot once this link finishes — but only if nobody chained\r\n    // a follow-up onto it in the meantime.\r\n    next.finally(() => {\r\n      if (this.locks.get(parsedKey) === next) {\r\n        this.locks.delete(parsedKey);\r\n      }\r\n    });\r\n\r\n    return next;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\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    const result = await this.update<T>(\r\n      key,\r\n      (current) => {\r\n        const base = (current ?? {}) as T;\r\n        return { ...base, ...partial } as T;\r\n      },\r\n      options,\r\n    );\r\n\r\n    return result as T;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   *\r\n   * Default implementation: read-mutate-write array backed by the underlying\r\n   * cache entry. Concrete drivers (e.g. Redis) override with native commands.\r\n   */\r\n  public list<T = any>(key: CacheKey): CacheListAccessor<T> {\r\n    return new MemoryCacheList<T>(this, key);\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   *\r\n   * Built on top of `set({ onConflict: \"create\" })` — Redis-native `SET … NX EX`\r\n   * under the hood on Redis, emulated via key-existence check on other drivers.\r\n   * The lock value is the resolved `owner` (defaults to `pid.<process.pid>`).\r\n   *\r\n   * Always releases in `finally`, even if `fn` throws — the thrown error\r\n   * propagates to the caller unchanged.\r\n   */\r\n  public async lock<T>(\r\n    key: CacheKey,\r\n    ttlOrOptions: CacheTtl | Omit<LockOptions, \"driver\">,\r\n    fn: () => Promise<T>,\r\n  ): Promise<LockOutcome<T>> {\r\n    const { ttl, owner } = this.normalizeLockOptions(ttlOrOptions);\r\n    const lockOwner = owner ?? `pid.${process.pid}`;\r\n\r\n    const setResult = (await this.set(key, lockOwner, {\r\n      onConflict: \"create\",\r\n      ttl,\r\n    })) as CacheSetResult | unknown;\r\n\r\n    // `onConflict` drivers return CacheSetResult. Drivers that no-op on set\r\n    // (e.g. the null driver) may return anything else — treat that as\r\n    // \"acquired\" since there's nothing to collide with.\r\n    const wasSet =\r\n      typeof setResult === \"object\" &&\r\n      setResult !== null &&\r\n      \"wasSet\" in setResult\r\n        ? (setResult as CacheSetResult).wasSet\r\n        : true;\r\n\r\n    if (!wasSet) {\r\n      return { acquired: false };\r\n    }\r\n\r\n    try {\r\n      const value = await fn();\r\n      return { acquired: true, value };\r\n    } finally {\r\n      await this.remove(key);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   *\r\n   * Default implementation throws {@link CacheUnsupportedError}. Drivers that\r\n   * support similarity retrieval (memory family, `pg`, `redis` w/ RediSearch)\r\n   * override this with a real impl.\r\n   */\r\n  public async similar<T = any>(\r\n    _vector: number[],\r\n    _options: CacheSimilarOptions,\r\n  ): Promise<CacheSimilarHit<T>[]> {\r\n    throw new CacheUnsupportedError(\r\n      `'${this.name}' driver does not support similarity retrieval. Use a memory driver, 'pg' (with pgvector), or 'redis' (with RediSearch).`,\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Resolve the TTL-or-options arg of `lock` into a uniform shape.\r\n   */\r\n  protected normalizeLockOptions(\r\n    ttlOrOptions: CacheTtl | Omit<LockOptions, \"driver\">,\r\n  ): {\r\n    ttl: CacheTtl;\r\n    owner?: string;\r\n  } {\r\n    if (typeof ttlOrOptions === \"number\" || typeof ttlOrOptions === \"string\") {\r\n      return { ttl: ttlOrOptions };\r\n    }\r\n\r\n    return { ttl: ttlOrOptions.ttl, owner: ttlOrOptions.owner };\r\n  }\r\n}\r\n"],"mappings":"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"}
+{"version":3,"file":"base-cache-driver.mjs","names":[],"sources":["../../../../../../../cache/src/drivers/base-cache-driver.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { log } from \"@warlock.js/logger\";\nimport { MemoryCacheList } from \"../list/memory-cache-list\";\nimport { TaggedCache } from \"../tagged-cache\";\nimport type {\n  CacheConflictPolicy,\n  CacheData,\n  CacheDriver,\n  CacheEventData,\n  CacheEventHandler,\n  CacheEventType,\n  CacheKey,\n  CacheListAccessor,\n  CacheOperationType,\n  CacheSetOptions,\n  CacheSetResult,\n  CacheSimilarHit,\n  CacheSimilarOptions,\n  CacheSwrOptions,\n  CacheTtl,\n  LockOptions,\n  LockOutcome,\n  RememberOptions,\n} from \"../types\";\nimport { CacheConfigurationError, CacheUnsupportedError } from \"../types\";\nimport {\n  normalizeToOptions,\n  parseCacheKey,\n  parseTtl,\n  resolveTtl,\n  safeErrorInfo,\n} from \"../utils\";\n\n/**\n * Normalized form of the 3rd `set` argument.\n *\n * All drivers operate on this shape internally regardless of whether the caller\n * passed a positional TTL, a duration string, or a rich options object.\n */\nexport type NormalizedSetOptions = {\n  /**\n   * Final TTL in seconds — already merged with the driver-level default\n   * (`this.options.ttl`). `Infinity` means \"no expiration\".\n   *\n   * Always populated. Drivers do NOT need to fall back to `this.ttl`\n   * themselves — `resolveSetOptions` does the merge centrally so that\n   * every driver respects the configured default without ceremony.\n   */\n  ttl: number;\n  /**\n   * Inline tag list, or undefined when none were provided.\n   */\n  tags?: string[];\n  /**\n   * Conflict policy. Defaults to `\"upsert\"`.\n   */\n  onConflict: CacheConflictPolicy;\n  /**\n   * Optional embedding vector for similarity retrieval. Drivers that do not\n   * support similarity must throw {@link CacheUnsupportedError} when this is\n   * present (rather than silently dropping it).\n   */\n  vector?: number[];\n  /**\n   * Optional freshness deadline as a millisecond timestamp. Set by `swr()`\n   * to mark when the entry stops being \"fresh\" and becomes\n   * \"stale-but-revalidatable.\" Drivers route this through\n   * `prepareDataForStorage` so it persists in the wrapper.\n   */\n  staleAt?: number;\n};\n\nconst messages = {\n  clearing: \"Clearing namespace\",\n  cleared: \"Namespace cleared\",\n  fetching: \"Fetching key\",\n  fetched: \"Key fetched\",\n  caching: \"Caching key\",\n  cached: \"Key cached\",\n  flushing: \"Flushing cache\",\n  flushed: \"Cache flushed\",\n  removing: \"Removing key\",\n  removed: \"Key removed\",\n  expired: \"Key expired\",\n  notFound: \"Key not found\",\n  connecting: \"Connecting to the cache engine.\",\n  connected: \"Connected to the cache engine.\",\n  disconnecting: \"Disconnecting from the cache engine.\",\n  disconnected: \"Disconnected from the cache engine.\",\n  connectionFailed: \"Failed to connect to the cache engine.\",\n  error: \"Error occurred\",\n};\n\nexport abstract class BaseCacheDriver<\n  ClientType,\n  Options extends Record<string, any>,\n> implements CacheDriver<ClientType, Options> {\n  /**\n   * CLient driver\n   */\n  protected clientDriver!: ClientType;\n\n  /**\n   * Determine whether to log or not\n   */\n  protected shouldLog: boolean = true;\n\n  /**\n   * {@inheritdoc}\n   */\n  public get client() {\n    return (this.clientDriver || this) as unknown as ClientType;\n  }\n\n  /**\n   * Set logging state\n   */\n  public setLoggingState(shouldLog: boolean) {\n    this.shouldLog = shouldLog;\n\n    return this;\n  }\n\n  /**\n   * Set client driver\n   */\n  public set client(client: ClientType) {\n    this.clientDriver = client;\n  }\n\n  /**\n   * Get the cache driver name\n   */\n  public abstract name: string;\n\n  /**\n   * Options list\n   */\n  public options!: Options;\n\n  /**\n   * Event listeners storage\n   */\n  protected eventListeners: Map<CacheEventType, Set<CacheEventHandler>> =\n    new Map();\n\n  /**\n   * {@inheritdoc}\n   */\n  public parseKey(key: CacheKey) {\n    return parseCacheKey(key, this.options);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public setOptions(options: Options) {\n    this.options = options || {};\n    return this;\n  }\n\n  /**\n   * Register an event listener\n   */\n  public on(event: CacheEventType, handler: CacheEventHandler): this {\n    if (!this.eventListeners.has(event)) {\n      this.eventListeners.set(event, new Set());\n    }\n    this.eventListeners.get(event)!.add(handler);\n    return this;\n  }\n\n  /**\n   * Remove an event listener\n   */\n  public off(event: CacheEventType, handler: CacheEventHandler): this {\n    const handlers = this.eventListeners.get(event);\n    if (handlers) {\n      handlers.delete(handler);\n    }\n    return this;\n  }\n\n  /**\n   * Register a one-time 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   * Emit an event to all registered listeners\n   */\n  protected async emit(\n    event: CacheEventType,\n    data: Partial<CacheEventData> = {},\n  ): Promise<void> {\n    const handlers = this.eventListeners.get(event);\n    if (!handlers || handlers.size === 0) return;\n\n    const eventData: CacheEventData = {\n      driver: this.name,\n      ...data,\n    };\n\n    // Execute all handlers\n    const promises: Promise<void>[] = [];\n    for (const handler of handlers) {\n      try {\n        const result = handler(eventData);\n        if (result instanceof Promise) {\n          promises.push(result);\n        }\n      } catch (error) {\n        this.logError(`Error in event handler for '${event}'`, error);\n      }\n    }\n\n    // Wait for all async handlers\n    if (promises.length > 0) {\n      await Promise.allSettled(promises);\n    }\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public abstract removeNamespace(namespace: string): Promise<any>;\n\n  /**\n   * {@inheritdoc}\n   */\n  public abstract set(\n    key: CacheKey,\n    value: any,\n    ttlOrOptions?: CacheTtl | CacheSetOptions,\n  ): Promise<any>;\n\n  /**\n   * Normalize the 3rd argument of a `set` call into a single shape every driver\n   * can act on. Handles TTL parsing (number | string | Infinity), `expiresAt` →\n   * relative TTL conversion, and mutual-exclusion validation.\n   *\n   * @throws {CacheConfigurationError} when `ttl` and `expiresAt` are passed together\n   * or an unparseable duration string is supplied.\n   */\n  protected resolveSetOptions(\n    ttlOrOptions?: CacheTtl | CacheSetOptions,\n  ): NormalizedSetOptions {\n    const options = normalizeToOptions(ttlOrOptions);\n\n    return {\n      ttl: resolveTtl(options.ttl, options.expiresAt, this.ttl),\n      tags: options.tags,\n      onConflict: options.onConflict ?? \"upsert\",\n      vector: options.vector,\n      staleAt: options.staleAt,\n    };\n  }\n\n  /**\n   * Resolve the union of cache keys associated with any of the given tags.\n   * Used by `similar()` to narrow the candidate pool before similarity ranking.\n   *\n   * Returns `null` when no tags are passed (callers should treat that as \"no filter\").\n   * Keys come back parsed (prefixed) — the index stores them un-prefixed, but\n   * callers match them against their own parsed storage keys.\n   */\n  protected async getKeysForTags(\n    tags: string[] | undefined,\n  ): Promise<Set<string> | null> {\n    if (!tags || tags.length === 0) {\n      return null;\n    }\n\n    const allKeys = new Set<string>();\n    for (const tag of tags) {\n      const keys = await this.tagMembers(`cache:tags:${tag}`);\n      for (const k of keys) {\n        allKeys.add(this.parseKey(k));\n      }\n    }\n\n    return allKeys;\n  }\n\n  // ============================================================\n  // Tag index primitives\n  // ============================================================\n\n  /**\n   * {@inheritdoc}\n   *\n   * Default implementation: the index is an ordinary entry holding a string\n   * array, read-modified-written under {@link runSerialized} — correct within\n   * THIS process only. Drivers with a native primitive override it (redis SET,\n   * pg atomic upsert, the in-process drivers' {@link InMemoryTagIndex}).\n   */\n  public async tagAdd(tagKey: CacheKey, members: string[]): Promise<void> {\n    if (members.length === 0) {\n      return;\n    }\n\n    await this.runSerialized(this.parseKey(tagKey), async () => {\n      const current = await this.readTagArray(tagKey);\n      const merged = new Set(current);\n\n      for (const member of members) {\n        merged.add(member);\n      }\n\n      if (merged.size !== current.length) {\n        await this.set(tagKey, [...merged], Infinity);\n      }\n    });\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async tagMembers(tagKey: CacheKey): Promise<string[]> {\n    return this.readTagArray(tagKey);\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Default implementation: serialized read-filter-write (process-local); an\n   * emptied index is removed.\n   */\n  public async tagRemove(tagKey: CacheKey, members: string[]): Promise<void> {\n    if (members.length === 0) {\n      return;\n    }\n\n    await this.runSerialized(this.parseKey(tagKey), async () => {\n      const current = await this.readTagArray(tagKey);\n      const dropped = new Set(members);\n      const kept = current.filter((member) => !dropped.has(member));\n\n      if (kept.length === current.length) {\n        return;\n      }\n\n      if (kept.length === 0) {\n        await this.remove(tagKey);\n      } else {\n        await this.set(tagKey, kept, Infinity);\n      }\n    });\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async tagDelete(tagKey: CacheKey): Promise<void> {\n    await this.runSerialized(this.parseKey(tagKey), () => this.remove(tagKey));\n  }\n\n  /**\n   * The index stored as a plain entry, or `[]`. Non-string members (a corrupted\n   * or foreign value) are ignored rather than trusted.\n   */\n  protected async readTagArray(tagKey: CacheKey): Promise<string[]> {\n    const value = await this.get(tagKey);\n\n    if (!Array.isArray(value)) {\n      return [];\n    }\n\n    return value.filter((member): member is string => typeof member === \"string\");\n  }\n\n  /**\n   * Apply tag relationships after a successful write. Called by drivers once\n   * the value is in storage.\n   *\n   * Pass the caller's key, not the parsed one: the tag index stores keys\n   * un-prefixed so `invalidate()` can delete them through `remove(key)`.\n   */\n  protected async applyTags(key: CacheKey, tags: string[]): Promise<void> {\n    if (tags.length === 0) {\n      return;\n    }\n\n    const tagged = this.tags(tags);\n    await (tagged as TaggedCache).storeTagRelationship(key);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public abstract get(key: CacheKey): Promise<any>;\n\n  /**\n   * {@inheritdoc}\n   */\n  public abstract remove(key: CacheKey): Promise<void>;\n\n  /**\n   * {@inheritdoc}\n   */\n  public abstract flush(): Promise<void>;\n\n  /**\n   * {@inheritdoc}\n   */\n  public async has(key: CacheKey): Promise<boolean> {\n    const value = await this.get(key);\n    // Event is emitted by get() method\n    return value !== null;\n  }\n\n  /**\n   * In-flight `remember()` computations, one per parsed key (stampede guard).\n   */\n  protected rememberInFlight: Map<string, Promise<any>> = new Map();\n\n  /**\n   * In-flight `swr()` cold-miss fetches, one per parsed key.\n   */\n  protected swrFetchInFlight: Map<string, Promise<any>> = new Map();\n\n  /**\n   * In-flight `swr()` stale-window background refreshes, one per parsed key.\n   */\n  protected swrRefreshes: Map<string, Promise<void>> = new Map();\n\n  /**\n   * Per-key serialization chains for the in-process read-modify-write\n   * operations (`update`, and the default `increment` / `pull`). Kept apart\n   * from the stampede maps so a `remember()` can never break an update chain,\n   * and never receives an unrelated promise.\n   */\n  protected updateChains: Map<string, Promise<any>> = new Map();\n\n  /**\n   * Run `task` once per key at a time: concurrent callers for the same\n   * `parsedKey` share the in-flight promise registered in `inFlight`.\n   */\n  protected singleFlight<T>(\n    inFlight: Map<string, Promise<any>>,\n    parsedKey: string,\n    task: () => Promise<T>,\n  ): Promise<T> {\n    const existing = inFlight.get(parsedKey);\n\n    if (existing) {\n      return existing as Promise<T>;\n    }\n\n    const promise: Promise<T> = task().finally(() => {\n      if (inFlight.get(parsedKey) === promise) {\n        inFlight.delete(parsedKey);\n      }\n    });\n\n    inFlight.set(parsedKey, promise);\n\n    return promise;\n  }\n\n  /**\n   * Chain `task` after every earlier serialized task for the same key, so\n   * read-modify-write callers in THIS process run one at a time. This is\n   * process-local: it does not coordinate with other servers.\n   */\n  protected runSerialized<T>(parsedKey: string, task: () => Promise<T>): Promise<T> {\n    const previous = this.updateChains.get(parsedKey) ?? Promise.resolve();\n\n    const next = previous.catch(() => undefined).then(task);\n\n    this.updateChains.set(parsedKey, next);\n\n    // Clean up the slot once this link finishes, but only if nobody chained a\n    // follow-up onto it meanwhile. The trailing catch keeps a rejected link\n    // from surfacing as an unhandled rejection here (the caller still sees it).\n    next\n      .finally(() => {\n        if (this.updateChains.get(parsedKey) === next) {\n          this.updateChains.delete(parsedKey);\n        }\n      })\n      .catch(() => undefined);\n\n    return next;\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async remember(\n    key: CacheKey,\n    ttlOrOptions: CacheTtl | RememberOptions,\n    callback: () => Promise<any>,\n  ): Promise<any> {\n    const parsedKey = this.parseKey(key);\n\n    // The options-form lets callers forward tags / driver-override through to\n    // the cache-miss write. Normalize both shapes into a single CacheSetOptions\n    // blob so there's one path from here on.\n    const setOptions = this.normalizeRememberOptions(ttlOrOptions);\n\n    // Only a real miss (`null`) recomputes: cached falsy values such as\n    // `0`, `false` and `\"\"` are returned as-is.\n    const cachedValue = await this.get(key);\n\n    if (cachedValue !== null && cachedValue !== undefined) {\n      return cachedValue;\n    }\n\n    return this.singleFlight(this.rememberInFlight, parsedKey, async () => {\n      const result = await callback();\n\n      await this.set(key, result, setOptions);\n\n      return result;\n    });\n  }\n\n  /**\n   * Resolve the TTL-or-options arg of `remember` into a `CacheSetOptions` object\n   * that can be passed straight to `set()`. Keeps the implementation unbranched.\n   */\n  protected normalizeRememberOptions(\n    ttlOrOptions: CacheTtl | RememberOptions,\n  ): CacheSetOptions {\n    if (typeof ttlOrOptions === \"number\" || typeof ttlOrOptions === \"string\") {\n      return { ttl: ttlOrOptions };\n    }\n\n    return {\n      ttl: ttlOrOptions.ttl,\n      tags: ttlOrOptions.tags,\n    };\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Default implementation: read raw entry, branch on freshness/staleness,\n   * trigger background refresh in the stale window, fall through to\n   * `callback` on miss/expiry. Concurrent cold-miss callers share one fetch\n   * ({@link swrFetchInFlight}); concurrent stale-window callers share one\n   * background refresh ({@link swrRefreshes}).\n   *\n   * Drivers without a real {@link getEntry} override degrade gracefully —\n   * the synthetic entry has no `staleAt`, which the freshness check treats\n   * as \"always fresh,\" so SWR behaves like a TTL-only cached read on those\n   * drivers (no background refresh, but no double-fetch either).\n   */\n  public async swr<T = any>(\n    key: CacheKey,\n    options: CacheSwrOptions,\n    callback: () => Promise<T>,\n  ): Promise<T> {\n    const parsedKey = this.parseKey(key);\n    const freshSeconds = parseTtl(options.freshTtl);\n    const staleSeconds = parseTtl(options.staleTtl);\n\n    if (staleSeconds <= freshSeconds) {\n      throw new Error(\n        `cache.swr: 'staleTtl' (${staleSeconds}s) must be greater than 'freshTtl' (${freshSeconds}s).`,\n      );\n    }\n\n    const entry = await this.getEntry(key);\n    const now = Date.now();\n\n    const isExpired = entry?.expiresAt !== undefined && entry.expiresAt <= now;\n\n    if (!entry || isExpired) {\n      return this.singleFlight(this.swrFetchInFlight, parsedKey, () =>\n        this.swrFetchAndStore<T>(key, options, callback, freshSeconds, staleSeconds),\n      );\n    }\n\n    const isFresh = entry.staleAt === undefined || entry.staleAt > now;\n\n    if (isFresh) {\n      return entry.data as T;\n    }\n\n    this.scheduleSwrRefresh<T>(\n      parsedKey,\n      key,\n      options,\n      callback,\n      freshSeconds,\n      staleSeconds,\n    );\n\n    return entry.data as T;\n  }\n\n  /**\n   * Read the raw {@link CacheData} wrapper for a key, including any\n   * `expiresAt` / `staleAt` metadata. Default implementation falls back to\n   * `get()` and synthesizes a metadata-less wrapper — drivers that store\n   * the wrapper directly (memory, lru, file, redis, pg, mock) override\n   * this to return real metadata so SWR can branch on freshness.\n   */\n  protected async getEntry(key: CacheKey): Promise<CacheData | null> {\n    const value = await this.get(key);\n\n    if (value === null) {\n      return null;\n    }\n\n    return { data: value };\n  }\n\n  /**\n   * Remaining lifetime of an existing entry, in seconds — used by TTL-preserving\n   * writes such as `update()` / `merge()` when the caller passes no explicit\n   * `ttl`.\n   *\n   * - `Infinity` — the entry exists with no expiry (preserve \"never expires\").\n   * - positive number — seconds left before the entry expires.\n   * - `undefined` — the key is missing or already past its deadline; the caller\n   *   should fall back to the driver default TTL.\n   *\n   * Default reads `expiresAt` from {@link getEntry}, which the metadata-aware\n   * drivers (memory, lru, mock, pg) populate. Drivers that track TTL natively\n   * and don't carry `expiresAt` in their payload (Redis) override this.\n   */\n  protected async getRemainingTtl(key: CacheKey): Promise<number | undefined> {\n    const entry = await this.getEntry(key);\n\n    if (!entry) {\n      return undefined;\n    }\n\n    if (!entry.expiresAt || entry.expiresAt === Infinity) {\n      return Infinity;\n    }\n\n    const remainingSeconds = Math.ceil((entry.expiresAt - Date.now()) / 1000);\n\n    return remainingSeconds > 0 ? remainingSeconds : undefined;\n  }\n\n  /**\n   * Block-and-fetch path of `swr()`: invoked on miss or past-`staleTtl`\n   * expiry. Writes through `set()` with the SWR options translated into\n   * standard `CacheSetOptions` (ttl = staleTtl, staleAt = now + freshTtl).\n   */\n  protected async swrFetchAndStore<T>(\n    key: CacheKey,\n    options: CacheSwrOptions,\n    callback: () => Promise<T>,\n    freshSeconds: number,\n    staleSeconds: number,\n  ): Promise<T> {\n    const result = await callback();\n\n    await this.set(key, result, {\n      ttl: staleSeconds,\n      staleAt: Date.now() + freshSeconds * 1000,\n      tags: options.tags,\n    });\n\n    return result;\n  }\n\n  /**\n   * Stale-window background refresh. Registers a single in-flight promise\n   * per parsed key so concurrent SWR callers share one refresh. Failed\n   * refreshes preserve the stale entry, log via `logError`, and emit on\n   * `error` — the stale-returning caller never sees the failure.\n   */\n  protected scheduleSwrRefresh<T>(\n    parsedKey: string,\n    key: CacheKey,\n    options: CacheSwrOptions,\n    callback: () => Promise<T>,\n    freshSeconds: number,\n    staleSeconds: number,\n  ): void {\n    if (this.swrRefreshes.has(parsedKey)) {\n      return;\n    }\n\n    let refresh!: Promise<void>;\n    refresh = (async () => {\n      try {\n        const result = await callback();\n\n        await this.set(key, result, {\n          ttl: staleSeconds,\n          staleAt: Date.now() + freshSeconds * 1000,\n          tags: options.tags,\n        });\n      } catch (error) {\n        this.logError(`SWR background refresh failed for ${parsedKey}`, error);\n        await this.emit(\"error\", { key: parsedKey, error });\n      } finally {\n        if (this.swrRefreshes.get(parsedKey) === refresh) {\n          this.swrRefreshes.delete(parsedKey);\n        }\n      }\n    })();\n\n    this.swrRefreshes.set(parsedKey, refresh);\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Default implementation: get-then-remove, serialized per key in THIS\n   * process. Drivers with a native primitive override it to be atomic across\n   * servers (redis `GETDEL`, pg `DELETE … RETURNING`) or process-atomic\n   * (memory, lru, mock).\n   */\n  public async pull(key: CacheKey): Promise<any | null> {\n    return this.runSerialized(this.parseKey(key), async () => {\n      // Events are emitted by get() and remove()\n      const value = await this.get(key);\n\n      if (value !== null) {\n        await this.remove(key);\n      }\n\n      return value;\n    });\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async forever(key: CacheKey, value: any): Promise<any> {\n    // Event is emitted by set() method\n    return this.set(key, value, Infinity);\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Default implementation: read-add-write serialized per key in THIS process,\n   * keeping the entry's remaining TTL (a missing key starts from 0 with the\n   * driver default TTL). Not atomic across servers: drivers with a native\n   * primitive override it (redis `INCRBY`, pg single-statement upsert).\n   */\n  public async increment(key: CacheKey, value: number = 1): Promise<number> {\n    const parsedKey = this.parseKey(key);\n\n    return this.runSerialized(parsedKey, async () => {\n      const current = await this.get(key);\n      const base = current === null || current === undefined ? 0 : current;\n\n      if (typeof base !== \"number\") {\n        throw new Error(`Cannot increment non-numeric value for key: ${parsedKey}`);\n      }\n\n      const newValue = base + value;\n      const remainingTtl = current === null ? undefined : await this.getRemainingTtl(key);\n\n      if (remainingTtl !== undefined) {\n        await this.set(key, newValue, { ttl: remainingTtl });\n      } else {\n        await this.set(key, newValue);\n      }\n\n      return newValue;\n    });\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async decrement(key: CacheKey, value: number = 1): Promise<number> {\n    return this.increment(key, -value);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async many(keys: CacheKey[]): Promise<any[]> {\n    return Promise.all(keys.map((key) => this.get(key)));\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async setMany(\n    items: Record<string, any>,\n    ttl?: number,\n  ): Promise<void> {\n    await Promise.all(\n      Object.entries(items).map(([key, value]) => this.set(key, value, ttl)),\n    );\n  }\n\n  /**\n   * Log the operation\n   */\n  protected log(operation: CacheOperationType, key?: string | any) {\n    if (!this.shouldLog) return;\n\n    if (typeof key === \"string\") {\n      // this will be likely used with file cache driver as it will convert the dot to slash\n      // to make it consistent and not to confuse developers we will output the key by making sure it's a dot\n      key = key.replace(/\\//g, \".\");\n    }\n\n    if (operation === \"connectionFailed\") {\n      log.fatal(`cache.${this.name}`, operation, key);\n    }\n\n    if (operation == \"notFound\" || operation == \"expired\") {\n      return log.info(\n        \"cache.\" + this.name,\n        operation,\n        (key ? key + \" \" : \"\") + messages[operation],\n      );\n    }\n\n    if (operation.endsWith(\"ed\")) {\n      return log.success(\n        \"cache.\" + this.name,\n        operation,\n        (key ? key + \" \" : \"\") + messages[operation],\n      );\n    }\n\n    log.info(\n      \"cache.\" + this.name,\n      operation,\n      (key ? key + \" \" : \"\") + messages[operation],\n    );\n  }\n\n  /**\n   * Log error message\n   *\n   * Never logs the raw `error` object — driver connection errors (Redis,\n   * Postgres, ...) can carry the connection string, including the password,\n   * in the message/cause. Only a redacted `{ message, code }` shape is\n   * passed to the structured logger.\n   */\n  protected logError(message: string, error?: any) {\n    if (error) {\n      log.error(\"cache.\" + this.name, \"error\", message, safeErrorInfo(error));\n    } else {\n      log.error(\"cache.\" + this.name, \"error\", message);\n    }\n  }\n\n  /**\n   * Get the default TTL in seconds. Parses human-readable strings (`\"1h\"`, `\"30m\"`)\n   * from driver options if present; falls back to `Infinity` when no default is set.\n   */\n  public get ttl() {\n    if (this.options.ttl === undefined) {\n      return Infinity;\n    }\n\n    return parseTtl(this.options.ttl);\n  }\n\n  /**\n   * Get time to live value in milliseconds\n   */\n  public getExpiresAt(ttl: number = this.ttl) {\n    if (ttl) {\n      return new Date().getTime() + ttl * 1000;\n    }\n  }\n\n  /**\n   * Wrap a value with TTL and optional freshness metadata for backend\n   * storage. `staleAt` persists alongside `expiresAt` when supplied — used\n   * by the SWR flow to mark when the entry stops being fresh.\n   */\n  protected prepareDataForStorage(data: any, ttl?: number, staleAt?: number) {\n    const preparedData: CacheData = {\n      data,\n    };\n\n    if (ttl) {\n      preparedData.ttl = ttl;\n      preparedData.expiresAt = this.getExpiresAt(ttl);\n    }\n\n    if (staleAt !== undefined) {\n      preparedData.staleAt = staleAt;\n    }\n\n    return preparedData;\n  }\n\n  /**\n   * Parse fetched data from cache\n   */\n  protected async parseCachedData(key: string, data: CacheData) {\n    this.log(\"fetched\", key);\n\n    if (data.expiresAt && data.expiresAt < Date.now()) {\n      this.remove(key);\n      return null;\n    }\n\n    const value = data.data;\n\n    // Skip cloning for primitives (immutable types)\n    if (value === null || value === undefined) {\n      return value;\n    }\n\n    const type = typeof value;\n    if (type === \"string\" || type === \"number\" || type === \"boolean\") {\n      return value;\n    }\n\n    // Deep clone objects/arrays to prevent cache mutation\n    try {\n      return structuredClone(value);\n    } catch (error) {\n      this.logError(\n        `Failed to clone cached value for ${key}, typeof value: ${typeof value}`,\n        error,\n      );\n      throw error;\n    }\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async connect() {\n    this.log(\"connecting\");\n    this.log(\"connected\");\n    await this.emit(\"connected\");\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async disconnect() {\n    this.log(\"disconnected\");\n    await this.emit(\"disconnected\");\n  }\n\n  /**\n   * Create a tagged cache instance for the given tags\n   */\n  public tags(tags: string[]): any {\n    return new TaggedCache(tags, this);\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Default implementation: read → transform → write, serialized per key in\n   * THIS process only. Drivers that can offer cross-server atomicity (redis,\n   * pg: compare-and-set with retries) override it.\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    // Chain each update onto the previous one for the same key so concurrent\n    // callers are serialized end-to-end, not merely awakened together.\n    return this.runSerialized(this.parseKey(key), async () => {\n      const current = (await this.get(key)) as T | null;\n      const result = await fn(current);\n\n      if (result === null) {\n        await this.remove(key);\n        return null;\n      }\n\n      if (options.ttl !== undefined) {\n        await this.set(key, result, { ttl: options.ttl });\n\n        return result;\n      }\n\n      // No explicit TTL → preserve the existing entry's remaining lifetime\n      // rather than resetting it to the driver default.\n      const remainingTtl = await this.getRemainingTtl(key);\n\n      if (remainingTtl !== undefined) {\n        await this.set(key, result, { ttl: remainingTtl });\n      } else {\n        await this.set(key, result);\n      }\n\n      return result;\n    });\n  }\n\n  /**\n   * {@inheritdoc}\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    const result = await this.update<T>(\n      key,\n      (current) => {\n        const base = (current ?? {}) as T;\n        return { ...base, ...partial } as T;\n      },\n      options,\n    );\n\n    return result as T;\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Default implementation: read-mutate-write array backed by the underlying\n   * cache entry. Concrete drivers (e.g. Redis) override with native commands.\n   */\n  public list<T = any>(key: CacheKey): CacheListAccessor<T> {\n    return new MemoryCacheList<T>(this, key);\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Built on top of `set({ onConflict: \"create\" })` — Redis-native `SET … NX EX`\n   * under the hood on Redis, emulated via key-existence check on other drivers.\n   * The lock value is the resolved `owner` (defaults to `pid.<process.pid>`).\n   *\n   * Always releases in `finally`, even if `fn` throws — the thrown error\n   * propagates to the caller unchanged, and a failed release is logged rather\n   * than replacing `fn`'s result or error. The ttl must be finite and\n   * positive; there is no renewal, so it must exceed the worst-case duration.\n   */\n  public async lock<T>(\n    key: CacheKey,\n    ttlOrOptions: CacheTtl | Omit<LockOptions, \"driver\">,\n    fn: () => Promise<T>,\n  ): Promise<LockOutcome<T>> {\n    const { ttl, owner } = this.normalizeLockOptions(ttlOrOptions);\n\n    // A lock with no expiry stays held forever if its holder crashes, on every\n    // server. Refuse it up front (parseTtl also rejects undefined / NaN).\n    const ttlSeconds = parseTtl(ttl);\n\n    if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) {\n      throw new CacheConfigurationError(\n        `cache.lock() requires a finite, positive ttl (got ${String(ttl)}). The ttl must exceed the worst-case duration of the locked work.`,\n      );\n    }\n    // The stored value is `<owner>#<token>`: the token makes it unique per\n    // acquisition so release can compare-and-delete instead of deleting blindly.\n    const lockValue = `${owner ?? `pid.${process.pid}`}#${randomUUID()}`;\n\n    const setResult = (await this.set(key, lockValue, {\n      onConflict: \"create\",\n      ttl,\n    })) as CacheSetResult | unknown;\n\n    // `onConflict` drivers return CacheSetResult. Drivers that no-op on set\n    // (e.g. the null driver) may return anything else — treat that as\n    // \"acquired\" since there's nothing to collide with.\n    const wasSet =\n      typeof setResult === \"object\" &&\n      setResult !== null &&\n      \"wasSet\" in setResult\n        ? (setResult as CacheSetResult).wasSet\n        : true;\n\n    if (!wasSet) {\n      return { acquired: false };\n    }\n\n    try {\n      const value = await fn();\n      return { acquired: true, value };\n    } finally {\n      // Only delete our own lock — if the TTL expired and a successor\n      // acquired the key, its value differs and it is left alone. A release\n      // failure (e.g. a Redis blip) is logged, never allowed to replace fn's\n      // outcome: the lock still expires by its TTL.\n      try {\n        await this.deleteIfEquals(key, lockValue);\n      } catch (error) {\n        this.logError(`lock release failed for ${this.parseKey(key)}`, error);\n      }\n    }\n  }\n\n  /**\n   * Compare-and-delete: remove `key` only when its current value equals\n   * `expected`. Returns whether a delete happened.\n   *\n   * This default is get-then-remove and is NOT atomic across processes; drivers\n   * with a real primitive (memory, redis, pg) override it.\n   */\n  protected async deleteIfEquals(key: CacheKey, expected: unknown): Promise<boolean> {\n    if ((await this.get(key)) !== expected) {\n      return false;\n    }\n\n    await this.remove(key);\n\n    return true;\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Default implementation throws {@link CacheUnsupportedError}. Drivers that\n   * support similarity retrieval (memory family, `pg`, `redis` w/ RediSearch)\n   * override this with a real impl.\n   */\n  public async similar<T = any>(\n    _vector: number[],\n    _options: CacheSimilarOptions,\n  ): Promise<CacheSimilarHit<T>[]> {\n    throw new CacheUnsupportedError(\n      `'${this.name}' driver does not support similarity retrieval. Use a memory driver, 'pg' (with pgvector), or 'redis' (with RediSearch).`,\n    );\n  }\n\n  /**\n   * Resolve the TTL-or-options arg of `lock` into a uniform shape.\n   */\n  protected normalizeLockOptions(\n    ttlOrOptions: CacheTtl | Omit<LockOptions, \"driver\">,\n  ): {\n    ttl: CacheTtl;\n    owner?: string;\n  } {\n    if (typeof ttlOrOptions === \"number\" || typeof ttlOrOptions === \"string\") {\n      return { ttl: ttlOrOptions };\n    }\n\n    return { ttl: ttlOrOptions.ttl, owner: ttlOrOptions.owner };\n  }\n}\n"],"mappings":"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"}

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

@@ -63,8 +63,23 @@ declare class FileCacheDriver extends BaseCacheDriver<FileCacheDriver, FileCache
   removeNamespace(namespace: string): Promise<this>;
   /**
    * {@inheritdoc}
+   *
+   * `onConflict: "create"` is exclusive (temp file + hard link, so `lock()`
+   * is safe across concurrent writers). `onConflict: "update"` is NOT atomic:
+   * the existence probe and the write are separate steps.
    */
   set(key: CacheKey, value: any, ttlOrOptions?: CacheTtl | CacheSetOptions): Promise<any>;
+  /**
+   * Create `filePath` only if it does not exist. Writes a temp file, then
+   * hard-links it to the target (EEXIST = already present). An existing but
+   * expired entry is removed (the file only, never the directory) and the
+   * link retried once.
+   *
+   * Returns `null` when written, or `{ existing }` on conflict.
+   */
+  protected writeExclusive(filePath: string, data: CacheData): Promise<{
+    existing: any;
+  } | null>;
   /**
    * {@inheritdoc}
    *

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

@@ -1 +1 @@
-{"version":3,"file":"file-cache-driver.d.mts","names":[],"sources":["../../../../../../../cache/src/drivers/file-cache-driver.ts"],"mappings":";;;;cAoBa,eAAA,SACH,eAAA,CAAgB,eAAA,EAAiB,gBAAA,aAC9B,WAAA,CAAY,eAAA,EAAiB,gBAAA;;AAF1C;;EAOS,IAAA;EANiB;;;EAWjB,UAAA,CAAW,OAAA,EAAS,gBAAA;EAAA;;;EAAA,IAahB,SAAA;EA2IiB;;;EAAA,IA5HjB,QAAA;EA0MmB;;;;;;;;;;EAAA,UAtLpB,YAAA,CAAa,SAAA;EA1DD;;;;EAAA,UAkEZ,gBAAA,CAAiB,SAAA;EAlEhB;;;;;;;EAAA,UAgFD,gBAAA,CAAiB,OAAA;EA1ChB;;;;;EAAA,UAsDD,aAAA,CAAc,OAAA;EAZG;;;;;;;;;;;EAyCd,eAAA,CAAgB,SAAA,WAAiB,OAAA;EAyC5C;;;EAHW,GAAA,CACX,GAAA,EAAK,QAAA,EACL,KAAA,OACA,YAAA,GAAe,QAAA,GAAW,eAAA,GACzB,OAAA;EAkEU;;;;;;;;EATA,MAAA,IAAU,OAAA;EA8CN;;;EArCJ,KAAA,IAAS,OAAA;EA0EF;;;;;EAAA,UA/DJ,QAAA,CAAS,GAAA,EAAK,QAAA,GAAW,OAAA,CAAQ,SAAA;EAqG7B;AAAA;;EA3EP,GAAA,CAAI,GAAA,EAAK,QAAA,GAAQ,OAAA;;;;EAqCjB,MAAA,CAAO,GAAA,EAAK,QAAA,GAAQ,OAAA;;;;EAoBpB,KAAA,IAAK,OAAA;;;;EAkBL,OAAA,IAAO,OAAA;AAAA"}
+{"version":3,"file":"file-cache-driver.d.mts","names":[],"sources":["../../../../../../../cache/src/drivers/file-cache-driver.ts"],"mappings":";;;;cAsBa,eAAA,SACH,eAAA,CAAgB,eAAA,EAAiB,gBAAA,aAC9B,WAAA,CAAY,eAAA,EAAiB,gBAAA;;AAF1C;;EAOS,IAAA;EANiB;;;EAWjB,UAAA,CAAW,OAAA,EAAS,gBAAA;EAAA;;;EAAA,IAahB,SAAA;EAqJiB;;;EAAA,IAtIjB,QAAA;EA+PY;;;;;;;;;;EAAA,UA3Ob,YAAA,CAAa,SAAA;EA3Df;;;;EAAA,UAyEE,gBAAA,CAAiB,SAAA;EAzEH;;;;;;;EAAA,UAuFd,gBAAA,CAAiB,OAAA;EA5ET;;;;;EAAA,UAwFR,aAAA,CAAc,OAAA;EA1BG;;;;;;;;;;;EAuDd,eAAA,CAAgB,SAAA,WAAiB,OAAA;EA6C7B;;;;;;;EAHJ,GAAA,CACX,GAAA,EAAK,QAAA,EACL,KAAA,OACA,YAAA,GAAe,QAAA,GAAW,eAAA,GACzB,OAAA;EAkEA;;;;;;;;EAAA,UAHa,cAAA,CACd,QAAA,UACA,IAAA,EAAM,SAAA,GACL,OAAA;IAAU,QAAA;EAAA;EAoGA;;;;;;;;EA9CA,MAAA,IAAU,OAAA;EA2GL;;;EAlGL,KAAA,IAAS,OAAA;EAoHF;;;;;EAAA,UAzGJ,QAAA,CAAS,GAAA,EAAK,QAAA,GAAW,OAAA,CAAQ,SAAA;;;;EA0BpC,GAAA,CAAI,GAAA,EAAK,QAAA,GAAQ,OAAA;;;;EAyCjB,MAAA,CAAO,GAAA,EAAK,QAAA,GAAQ,OAAA;;;;EAoBpB,KAAA,IAAK,OAAA;;;;EAkBL,OAAA,IAAO,OAAA;AAAA"}