@warlock.js/cache 5.19.1 → 5.21.0

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

@@ -1,6 +1,8 @@
 import { CacheConfigurationError, CacheError, CacheUnsupportedError } from "../types.mjs";
 import { BaseCacheDriver } from "./base-cache-driver.mjs";
-import { ensureDirectoryAsync, getJsonFileAsync, listDirectoriesAsync, putJsonFileAsync, removeDirectoryAsync } from "@warlock.js/fs";
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import { atomicWriteJsonAsync, ensureDirectoryAsync, getJsonFileAsync, listDirectoriesAsync, removeDirectoryAsync } from "@warlock.js/fs";
 import path from "path";
 
 //#region ../cache/src/drivers/file-cache-driver.ts
@@ -43,6 +45,7 @@ var FileCacheDriver = class extends BaseCacheDriver {
 	* only ever produces a single filesystem component here.
 	*/
 	keyDirectory(parsedKey) {
+		if (parsedKey === "") throw new CacheConfigurationError("Cache key must not be empty.");
 		return this.containedPath(this.encodeKeySegment(parsedKey));
 	}
 	/**
@@ -107,18 +110,17 @@ var FileCacheDriver = class extends BaseCacheDriver {
 	}
 	/**
 	* {@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.
 	*/
 	async set(key, value, ttlOrOptions) {
 		const parsedKey = this.parseKey(key);
 		const { ttl, tags, onConflict, vector, staleAt } = this.resolveSetOptions(ttlOrOptions);
 		if (vector) throw new CacheUnsupportedError("'file' driver does not support similarity retrieval — use a memory driver, 'pg' (with pgvector), or 'redis' (with RediSearch).");
 		this.log("caching", parsedKey);
-		const existing = onConflict === "upsert" ? null : await this.get(key);
-		const exists = existing !== null;
-		if (onConflict === "create" && exists) return {
-			wasSet: false,
-			existing
-		};
+		const exists = (onConflict === "upsert" || onConflict === "create" ? null : await this.get(key)) !== null;
 		if (onConflict === "update" && !exists) return {
 			wasSet: false,
 			existing: null
@@ -126,7 +128,14 @@ var FileCacheDriver = class extends BaseCacheDriver {
 		const data = this.prepareDataForStorage(value, ttl, staleAt);
 		const fileDirectory = this.keyDirectory(parsedKey);
 		await ensureDirectoryAsync(fileDirectory);
-		await putJsonFileAsync(path.resolve(fileDirectory, this.fileName), data);
+		const filePath = path.resolve(fileDirectory, this.fileName);
+		if (onConflict === "create") {
+			const conflict = await this.writeExclusive(filePath, data);
+			if (conflict) return {
+				wasSet: false,
+				existing: conflict.existing
+			};
+		} else await atomicWriteJsonAsync(filePath, data);
 		if (tags && tags.length > 0) await this.applyTags(key, tags);
 		this.log("cached", parsedKey);
 		await this.emit("set", {
@@ -141,6 +150,44 @@ var FileCacheDriver = class extends BaseCacheDriver {
 		return this;
 	}
 	/**
+	* 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.
+	*/
+	async writeExclusive(filePath, data) {
+		const tempPath = `${filePath}.${randomBytes(6).toString("hex")}.tmp`;
+		try {
+			await fs.promises.writeFile(tempPath, JSON.stringify(data, null, 2));
+			for (let attempt = 0; attempt < 2; attempt++) {
+				try {
+					await fs.promises.link(tempPath, filePath);
+					return null;
+				} catch (error) {
+					if (error?.code !== "EEXIST") throw error;
+				}
+				let current;
+				try {
+					current = await getJsonFileAsync(filePath);
+				} catch {
+					current = void 0;
+				}
+				const expired = current?.expiresAt !== void 0 && current.expiresAt !== null && current.expiresAt <= Date.now();
+				if (current && !expired) return { existing: current.data ?? null };
+				if (attempt === 0 && expired) {
+					await fs.promises.rm(filePath, { force: true });
+					continue;
+				}
+				return { existing: null };
+			}
+			return { existing: null };
+		} finally {
+			await fs.promises.unlink(tempPath).catch(() => void 0);
+		}
+	}
+	/**
 	* {@inheritdoc}
 	*
 	* File driver does not yet ship with a file-lock primitive, so concurrent
@@ -181,21 +228,24 @@ var FileCacheDriver = class extends BaseCacheDriver {
 		const parsedKey = this.parseKey(key);
 		this.log("fetching", parsedKey);
 		const fileDirectory = this.keyDirectory(parsedKey);
+		let value;
 		try {
-			const value = await getJsonFileAsync(path.resolve(fileDirectory, this.fileName));
-			const result = await this.parseCachedData(parsedKey, value);
-			if (result === null) await this.emit("miss", { key: parsedKey });
-			else await this.emit("hit", {
-				key: parsedKey,
-				value: result
-			});
-			return result;
-		} catch (error) {
+			value = await getJsonFileAsync(path.resolve(fileDirectory, this.fileName));
+		} catch {
+			value = void 0;
+		}
+		if (value === void 0 || value === null || typeof value !== "object") {
 			this.log("notFound", parsedKey);
 			await this.emit("miss", { key: parsedKey });
-			await this.remove(key);
 			return null;
 		}
+		const result = await this.parseCachedData(parsedKey, value);
+		if (result === null) await this.emit("miss", { key: parsedKey });
+		else await this.emit("hit", {
+			key: parsedKey,
+			value: result
+		});
+		return result;
 	}
 	/**
 	* {@inheritdoc}

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

@@ -1 +1 @@
-{"version":3,"file":"file-cache-driver.mjs","names":[],"sources":["../../../../../../../cache/src/drivers/file-cache-driver.ts"],"sourcesContent":["import {\n  ensureDirectoryAsync,\n  getJsonFileAsync,\n  listDirectoriesAsync,\n  putJsonFileAsync,\n  removeDirectoryAsync,\n} from \"@warlock.js/fs\";\nimport path from \"path\";\nimport type {\n  CacheData,\n  CacheDriver,\n  CacheKey,\n  CacheSetOptions,\n  CacheSetResult,\n  CacheTtl,\n  FileCacheOptions,\n} from \"../types\";\nimport { CacheConfigurationError, CacheError, CacheUnsupportedError } from \"../types\";\nimport { BaseCacheDriver } from \"./base-cache-driver\";\n\nexport class FileCacheDriver\n  extends BaseCacheDriver<FileCacheDriver, FileCacheOptions>\n  implements CacheDriver<FileCacheDriver, FileCacheOptions>\n{\n  /**\n   * {@inheritdoc}\n   */\n  public name = \"file\";\n\n  /**\n   * {@inheritdoc}\n   */\n  public setOptions(options: FileCacheOptions) {\n    if (!options.directory) {\n      throw new CacheConfigurationError(\n        \"File driver requires 'directory' option to be configured.\",\n      );\n    }\n\n    return super.setOptions(options);\n  }\n\n  /**\n   * Get the cache directory\n   */\n  public get directory() {\n    const directory = this.options.directory;\n\n    if (typeof directory === \"function\") {\n      return directory();\n    }\n\n    throw new CacheConfigurationError(\n      \"Cache directory is not defined, please define it in the file driver options\",\n    );\n  }\n\n  /**\n   * Get file name\n   */\n  public get fileName() {\n    const fileName = this.options.fileName;\n\n    if (typeof fileName === \"function\") {\n      return fileName();\n    }\n\n    return \"cache.json\";\n  }\n\n  /**\n   * Map a parsed cache key (or namespace) to its on-disk directory.\n   *\n   * The key must become exactly one directory component: `%` and the path\n   * separators are percent-encoded so a hostile key (`../../etc`,\n   * `..\\\\..\\\\evil`) turns into an inert directory name instead of a path\n   * traversal, while distinct keys can never collide after encoding. Dots are\n   * left untouched — the `.`-delimited namespace scheme is purely logical and\n   * only ever produces a single filesystem component here.\n   */\n  protected keyDirectory(parsedKey: string): string {\n    return this.containedPath(this.encodeKeySegment(parsedKey));\n  }\n\n  /**\n   * Percent-encode a parsed key into an inert, single-component directory\n   * name. Dots are left untouched — see {@link keyDirectory}.\n   */\n  protected encodeKeySegment(parsedKey: string): string {\n    return parsedKey\n      .replace(/%/g, \"%25\")\n      .replace(/\\//g, \"%2F\")\n      .replace(/\\\\/g, \"%5C\");\n  }\n\n  /**\n   * Reverse of {@link encodeKeySegment} — recovers the logical, dot-delimited\n   * parsed key from an on-disk directory name. Used by {@link removeNamespace}\n   * to test which sibling directories logically belong to a namespace, since\n   * dotted keys (`ns.a`) are stored as sibling directories rather than nested\n   * ones (see {@link keyDirectory}'s doc comment).\n   */\n  protected decodeKeySegment(encoded: string): string {\n    return encoded\n      .replace(/%2F/g, \"/\")\n      .replace(/%5C/g, \"\\\\\")\n      .replace(/%25/g, \"%\");\n  }\n\n  /**\n   * Resolve `segment` against the cache root and throw when the result lands\n   * outside it — the last line of defense against path traversal, independent\n   * of how the key was encoded.\n   */\n  protected containedPath(segment: string): string {\n    const base = path.resolve(this.directory);\n    const resolved = path.resolve(base, segment);\n    const relative = path.relative(base, resolved);\n\n    if (\n      relative === \"..\" ||\n      relative.startsWith(`..${path.sep}`) ||\n      path.isAbsolute(relative)\n    ) {\n      throw new CacheError(\n        `Cache key resolves outside the cache directory: \"${segment}\"`,\n      );\n    }\n\n    return resolved;\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Dotted keys (`ns.a`) are stored as sibling directories, not nested ones\n   * (see {@link keyDirectory}) — a directory literally named `<namespace>`\n   * rarely exists on its own. Namespace removal therefore has to scan the\n   * cache root's immediate children and remove every directory whose\n   * *logical* (decoded) name equals the namespace or starts with\n   * `<namespace>.`, mirroring the `key = $1 OR key LIKE $2` boundary\n   * semantics the `pg` driver already uses for the same contract.\n   */\n  public async removeNamespace(namespace: string) {\n    const parsedNamespace = this.parseKey(namespace);\n\n    this.log(\"clearing\", namespace);\n\n    try {\n      const root = this.containedPath(\"\");\n\n      if (parsedNamespace === \"\") {\n        await removeDirectoryAsync(root);\n        this.log(\"cleared\", namespace);\n        return this;\n      }\n\n      const prefix = `${parsedNamespace}.`;\n      const entries = await listDirectoriesAsync(root).catch(() => [] as string[]);\n\n      await Promise.all(\n        entries.map(async (entryPath) => {\n          const decoded = this.decodeKeySegment(path.basename(entryPath));\n\n          if (decoded === parsedNamespace || decoded.startsWith(prefix)) {\n            await removeDirectoryAsync(entryPath);\n          }\n        }),\n      );\n\n      this.log(\"cleared\", namespace);\n    } catch (error) {\n      //\n    }\n\n    return this;\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async set(\n    key: CacheKey,\n    value: any,\n    ttlOrOptions?: CacheTtl | CacheSetOptions,\n  ): Promise<any> {\n    const parsedKey = this.parseKey(key);\n    const { ttl, tags, onConflict, vector, staleAt } = this.resolveSetOptions(ttlOrOptions);\n\n    if (vector) {\n      throw new CacheUnsupportedError(\n        \"'file' driver does not support similarity retrieval — use a memory driver, 'pg' (with pgvector), or 'redis' (with RediSearch).\",\n      );\n    }\n\n    this.log(\"caching\", parsedKey);\n\n    const existing = onConflict === \"upsert\" ? null : await this.get(key);\n    const exists = existing !== null;\n\n    if (onConflict === \"create\" && exists) {\n      const result: CacheSetResult = { wasSet: false, existing };\n      return result;\n    }\n\n    if (onConflict === \"update\" && !exists) {\n      const result: CacheSetResult = { wasSet: false, existing: null };\n      return result;\n    }\n\n    const data = this.prepareDataForStorage(value, ttl, staleAt);\n\n    const fileDirectory = this.keyDirectory(parsedKey);\n\n    await ensureDirectoryAsync(fileDirectory);\n\n    await putJsonFileAsync(path.resolve(fileDirectory, this.fileName), data);\n\n    if (tags && tags.length > 0) {\n      await this.applyTags(key, tags);\n    }\n\n    this.log(\"cached\", parsedKey);\n\n    await this.emit(\"set\", { key: parsedKey, value, ttl });\n\n    if (onConflict === \"create\" || onConflict === \"update\") {\n      const result: CacheSetResult = { wasSet: true, existing: null };\n      return result;\n    }\n\n    return this;\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * File driver does not yet ship with a file-lock primitive, so concurrent\n   * writers could clobber each other. Rather than ship an unsafe default, we\n   * throw — consumers can fall back to memory/redis for `update` until a\n   * proper file lock lands (tracked in `domains/cache/backlog.md`).\n   */\n  public async update(): Promise<never> {\n    throw new CacheUnsupportedError(\n      \"`update()` is not supported on the file driver. Use the memory or redis driver, or wait for the file-lock primitive (see domains/cache/backlog.md).\",\n    );\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async merge(): Promise<never> {\n    throw new CacheUnsupportedError(\n      \"`merge()` is not supported on the file driver. Use the memory or redis driver.\",\n    );\n  }\n\n  /**\n   * Read the raw {@link CacheData} wrapper from disk, including `staleAt`\n   * metadata. Returns `null` for missing or expired files — `swr()`\n   * consumes this to branch on freshness.\n   */\n  protected async getEntry(key: CacheKey): Promise<CacheData | null> {\n    const parsedKey = this.parseKey(key);\n    const fileDirectory = this.keyDirectory(parsedKey);\n\n    try {\n      const entry = (await getJsonFileAsync(path.resolve(fileDirectory, this.fileName))) as\n        | CacheData\n        | undefined;\n\n      if (!entry) {\n        return null;\n      }\n\n      if (entry.expiresAt !== undefined && entry.expiresAt <= Date.now()) {\n        return null;\n      }\n\n      return entry;\n    } catch {\n      return null;\n    }\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async get(key: CacheKey) {\n    const parsedKey = this.parseKey(key);\n\n    this.log(\"fetching\", parsedKey);\n\n    const fileDirectory = this.keyDirectory(parsedKey);\n\n    try {\n      const value = await getJsonFileAsync(path.resolve(fileDirectory, this.fileName));\n\n      const result = await this.parseCachedData(parsedKey, value as CacheData);\n\n      if (result === null) {\n        // Expired\n        await this.emit(\"miss\", { key: parsedKey });\n      } else {\n        // Emit hit event\n        await this.emit(\"hit\", { key: parsedKey, value: result });\n      }\n\n      return result;\n    } catch (error) {\n      this.log(\"notFound\", parsedKey);\n      // Emit miss event\n      await this.emit(\"miss\", { key: parsedKey });\n      // Await the cleanup so it fully settles before returning. Leaving this\n      // fire-and-forget let the async directory removal race a follow-up write\n      // to the same key (e.g. the existence probe inside a `set({ onConflict })`\n      // call), surfacing as an ENOENT mkdir/rm collision on Windows.\n      await this.remove(key);\n      return null;\n    }\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async remove(key: CacheKey) {\n    const parsedKey = this.parseKey(key);\n    this.log(\"removing\", parsedKey);\n\n    const fileDirectory = this.keyDirectory(parsedKey);\n\n    try {\n      await removeDirectoryAsync(fileDirectory);\n\n      this.log(\"removed\", parsedKey);\n      // Emit removed event\n      await this.emit(\"removed\", { key: parsedKey });\n    } catch (error) {\n      //\n    }\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async flush() {\n    this.log(\"flushing\");\n\n    if (this.options.globalPrefix) {\n      await this.removeNamespace(\"\");\n    } else {\n      await removeDirectoryAsync(this.directory);\n    }\n\n    this.log(\"flushed\");\n\n    // Emit flushed event\n    await this.emit(\"flushed\");\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async connect() {\n    this.log(\"connecting\");\n    await ensureDirectoryAsync(this.directory);\n    this.log(\"connected\");\n    await this.emit(\"connected\");\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"file-cache-driver.mjs","names":[],"sources":["../../../../../../../cache/src/drivers/file-cache-driver.ts"],"sourcesContent":["import { randomBytes } from \"node:crypto\";\nimport fs from \"node:fs\";\nimport {\n  atomicWriteJsonAsync,\n  ensureDirectoryAsync,\n  getJsonFileAsync,\n  listDirectoriesAsync,\n  removeDirectoryAsync,\n} from \"@warlock.js/fs\";\nimport path from \"path\";\nimport type {\n  CacheData,\n  CacheDriver,\n  CacheKey,\n  CacheSetOptions,\n  CacheSetResult,\n  CacheTtl,\n  FileCacheOptions,\n} from \"../types\";\nimport { CacheConfigurationError, CacheError, CacheUnsupportedError } from \"../types\";\nimport { BaseCacheDriver } from \"./base-cache-driver\";\n\nexport class FileCacheDriver\n  extends BaseCacheDriver<FileCacheDriver, FileCacheOptions>\n  implements CacheDriver<FileCacheDriver, FileCacheOptions>\n{\n  /**\n   * {@inheritdoc}\n   */\n  public name = \"file\";\n\n  /**\n   * {@inheritdoc}\n   */\n  public setOptions(options: FileCacheOptions) {\n    if (!options.directory) {\n      throw new CacheConfigurationError(\n        \"File driver requires 'directory' option to be configured.\",\n      );\n    }\n\n    return super.setOptions(options);\n  }\n\n  /**\n   * Get the cache directory\n   */\n  public get directory() {\n    const directory = this.options.directory;\n\n    if (typeof directory === \"function\") {\n      return directory();\n    }\n\n    throw new CacheConfigurationError(\n      \"Cache directory is not defined, please define it in the file driver options\",\n    );\n  }\n\n  /**\n   * Get file name\n   */\n  public get fileName() {\n    const fileName = this.options.fileName;\n\n    if (typeof fileName === \"function\") {\n      return fileName();\n    }\n\n    return \"cache.json\";\n  }\n\n  /**\n   * Map a parsed cache key (or namespace) to its on-disk directory.\n   *\n   * The key must become exactly one directory component: `%` and the path\n   * separators are percent-encoded so a hostile key (`../../etc`,\n   * `..\\\\..\\\\evil`) turns into an inert directory name instead of a path\n   * traversal, while distinct keys can never collide after encoding. Dots are\n   * left untouched — the `.`-delimited namespace scheme is purely logical and\n   * only ever produces a single filesystem component here.\n   */\n  protected keyDirectory(parsedKey: string): string {\n    // An empty key would resolve to the cache root — `remove(\"{}\")` must never\n    // be able to wipe it.\n    if (parsedKey === \"\") {\n      throw new CacheConfigurationError(\"Cache key must not be empty.\");\n    }\n\n    return this.containedPath(this.encodeKeySegment(parsedKey));\n  }\n\n  /**\n   * Percent-encode a parsed key into an inert, single-component directory\n   * name. Dots are left untouched — see {@link keyDirectory}.\n   */\n  protected encodeKeySegment(parsedKey: string): string {\n    return parsedKey\n      .replace(/%/g, \"%25\")\n      .replace(/\\//g, \"%2F\")\n      .replace(/\\\\/g, \"%5C\");\n  }\n\n  /**\n   * Reverse of {@link encodeKeySegment} — recovers the logical, dot-delimited\n   * parsed key from an on-disk directory name. Used by {@link removeNamespace}\n   * to test which sibling directories logically belong to a namespace, since\n   * dotted keys (`ns.a`) are stored as sibling directories rather than nested\n   * ones (see {@link keyDirectory}'s doc comment).\n   */\n  protected decodeKeySegment(encoded: string): string {\n    return encoded\n      .replace(/%2F/g, \"/\")\n      .replace(/%5C/g, \"\\\\\")\n      .replace(/%25/g, \"%\");\n  }\n\n  /**\n   * Resolve `segment` against the cache root and throw when the result lands\n   * outside it — the last line of defense against path traversal, independent\n   * of how the key was encoded.\n   */\n  protected containedPath(segment: string): string {\n    const base = path.resolve(this.directory);\n    const resolved = path.resolve(base, segment);\n    const relative = path.relative(base, resolved);\n\n    if (\n      relative === \"..\" ||\n      relative.startsWith(`..${path.sep}`) ||\n      path.isAbsolute(relative)\n    ) {\n      throw new CacheError(\n        `Cache key resolves outside the cache directory: \"${segment}\"`,\n      );\n    }\n\n    return resolved;\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Dotted keys (`ns.a`) are stored as sibling directories, not nested ones\n   * (see {@link keyDirectory}) — a directory literally named `<namespace>`\n   * rarely exists on its own. Namespace removal therefore has to scan the\n   * cache root's immediate children and remove every directory whose\n   * *logical* (decoded) name equals the namespace or starts with\n   * `<namespace>.`, mirroring the `key = $1 OR key LIKE $2` boundary\n   * semantics the `pg` driver already uses for the same contract.\n   */\n  public async removeNamespace(namespace: string) {\n    const parsedNamespace = this.parseKey(namespace);\n\n    this.log(\"clearing\", namespace);\n\n    try {\n      const root = this.containedPath(\"\");\n\n      if (parsedNamespace === \"\") {\n        await removeDirectoryAsync(root);\n        this.log(\"cleared\", namespace);\n        return this;\n      }\n\n      const prefix = `${parsedNamespace}.`;\n      const entries = await listDirectoriesAsync(root).catch(() => [] as string[]);\n\n      await Promise.all(\n        entries.map(async (entryPath) => {\n          const decoded = this.decodeKeySegment(path.basename(entryPath));\n\n          if (decoded === parsedNamespace || decoded.startsWith(prefix)) {\n            await removeDirectoryAsync(entryPath);\n          }\n        }),\n      );\n\n      this.log(\"cleared\", namespace);\n    } catch (error) {\n      //\n    }\n\n    return this;\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * `onConflict: \"create\"` is exclusive (temp file + hard link, so `lock()`\n   * is safe across concurrent writers). `onConflict: \"update\"` is NOT atomic:\n   * the existence probe and the write are separate steps.\n   */\n  public async set(\n    key: CacheKey,\n    value: any,\n    ttlOrOptions?: CacheTtl | CacheSetOptions,\n  ): Promise<any> {\n    const parsedKey = this.parseKey(key);\n    const { ttl, tags, onConflict, vector, staleAt } = this.resolveSetOptions(ttlOrOptions);\n\n    if (vector) {\n      throw new CacheUnsupportedError(\n        \"'file' driver does not support similarity retrieval — use a memory driver, 'pg' (with pgvector), or 'redis' (with RediSearch).\",\n      );\n    }\n\n    this.log(\"caching\", parsedKey);\n\n    const existing = onConflict === \"upsert\" || onConflict === \"create\" ? null : await this.get(key);\n    const exists = existing !== null;\n\n    if (onConflict === \"update\" && !exists) {\n      const result: CacheSetResult = { wasSet: false, existing: null };\n      return result;\n    }\n\n    const data = this.prepareDataForStorage(value, ttl, staleAt);\n\n    const fileDirectory = this.keyDirectory(parsedKey);\n\n    await ensureDirectoryAsync(fileDirectory);\n\n    const filePath = path.resolve(fileDirectory, this.fileName);\n\n    if (onConflict === \"create\") {\n      const conflict = await this.writeExclusive(filePath, data);\n\n      if (conflict) {\n        const result: CacheSetResult = { wasSet: false, existing: conflict.existing };\n        return result;\n      }\n    } else {\n      await atomicWriteJsonAsync(filePath, data);\n    }\n\n    if (tags && tags.length > 0) {\n      await this.applyTags(key, tags);\n    }\n\n    this.log(\"cached\", parsedKey);\n\n    await this.emit(\"set\", { key: parsedKey, value, ttl });\n\n    if (onConflict === \"create\" || onConflict === \"update\") {\n      const result: CacheSetResult = { wasSet: true, existing: null };\n      return result;\n    }\n\n    return this;\n  }\n\n  /**\n   * Create `filePath` only if it does not exist. Writes a temp file, then\n   * hard-links it to the target (EEXIST = already present). An existing but\n   * expired entry is removed (the file only, never the directory) and the\n   * link retried once.\n   *\n   * Returns `null` when written, or `{ existing }` on conflict.\n   */\n  protected async writeExclusive(\n    filePath: string,\n    data: CacheData,\n  ): Promise<{ existing: any } | null> {\n    const tempPath = `${filePath}.${randomBytes(6).toString(\"hex\")}.tmp`;\n\n    try {\n      await fs.promises.writeFile(tempPath, JSON.stringify(data, null, 2));\n\n      for (let attempt = 0; attempt < 2; attempt++) {\n        try {\n          await fs.promises.link(tempPath, filePath);\n          return null;\n        } catch (error: any) {\n          if (error?.code !== \"EEXIST\") {\n            throw error;\n          }\n        }\n\n        let current: CacheData | undefined;\n\n        try {\n          current = (await getJsonFileAsync(filePath)) as CacheData | undefined;\n        } catch {\n          current = undefined;\n        }\n\n        const expired =\n          current?.expiresAt !== undefined && current.expiresAt !== null && current.expiresAt <= Date.now();\n\n        if (current && !expired) {\n          return { existing: current.data ?? null };\n        }\n\n        if (attempt === 0 && expired) {\n          await fs.promises.rm(filePath, { force: true });\n          continue;\n        }\n\n        // Unreadable (corrupt) file: treat as held, never delete it.\n        return { existing: null };\n      }\n\n      return { existing: null };\n    } finally {\n      await fs.promises.unlink(tempPath).catch(() => undefined);\n    }\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * File driver does not yet ship with a file-lock primitive, so concurrent\n   * writers could clobber each other. Rather than ship an unsafe default, we\n   * throw — consumers can fall back to memory/redis for `update` until a\n   * proper file lock lands (tracked in `domains/cache/backlog.md`).\n   */\n  public async update(): Promise<never> {\n    throw new CacheUnsupportedError(\n      \"`update()` is not supported on the file driver. Use the memory or redis driver, or wait for the file-lock primitive (see domains/cache/backlog.md).\",\n    );\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async merge(): Promise<never> {\n    throw new CacheUnsupportedError(\n      \"`merge()` is not supported on the file driver. Use the memory or redis driver.\",\n    );\n  }\n\n  /**\n   * Read the raw {@link CacheData} wrapper from disk, including `staleAt`\n   * metadata. Returns `null` for missing or expired files — `swr()`\n   * consumes this to branch on freshness.\n   */\n  protected async getEntry(key: CacheKey): Promise<CacheData | null> {\n    const parsedKey = this.parseKey(key);\n    const fileDirectory = this.keyDirectory(parsedKey);\n\n    try {\n      const entry = (await getJsonFileAsync(path.resolve(fileDirectory, this.fileName))) as\n        | CacheData\n        | undefined;\n\n      if (!entry) {\n        return null;\n      }\n\n      if (entry.expiresAt !== undefined && entry.expiresAt <= Date.now()) {\n        return null;\n      }\n\n      return entry;\n    } catch {\n      return null;\n    }\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async get(key: CacheKey) {\n    const parsedKey = this.parseKey(key);\n\n    this.log(\"fetching\", parsedKey);\n\n    const fileDirectory = this.keyDirectory(parsedKey);\n\n    let value: CacheData | undefined;\n\n    try {\n      value = (await getJsonFileAsync(path.resolve(fileDirectory, this.fileName))) as\n        | CacheData\n        | undefined;\n    } catch {\n      // Missing file (ENOENT) or corrupt JSON: a plain miss. Never remove the\n      // directory here — it may be mid-write by another process.\n      value = undefined;\n    }\n\n    if (value === undefined || value === null || typeof value !== \"object\") {\n      this.log(\"notFound\", parsedKey);\n      await this.emit(\"miss\", { key: parsedKey });\n      return null;\n    }\n\n    // Only a successfully parsed but expired entry is removed (inside\n    // parseCachedData).\n    const result = await this.parseCachedData(parsedKey, value);\n\n    if (result === null) {\n      await this.emit(\"miss\", { key: parsedKey });\n    } else {\n      await this.emit(\"hit\", { key: parsedKey, value: result });\n    }\n\n    return result;\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async remove(key: CacheKey) {\n    const parsedKey = this.parseKey(key);\n    this.log(\"removing\", parsedKey);\n\n    const fileDirectory = this.keyDirectory(parsedKey);\n\n    try {\n      await removeDirectoryAsync(fileDirectory);\n\n      this.log(\"removed\", parsedKey);\n      // Emit removed event\n      await this.emit(\"removed\", { key: parsedKey });\n    } catch (error) {\n      //\n    }\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async flush() {\n    this.log(\"flushing\");\n\n    if (this.options.globalPrefix) {\n      await this.removeNamespace(\"\");\n    } else {\n      await removeDirectoryAsync(this.directory);\n    }\n\n    this.log(\"flushed\");\n\n    // Emit flushed event\n    await this.emit(\"flushed\");\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async connect() {\n    this.log(\"connecting\");\n    await ensureDirectoryAsync(this.directory);\n    this.log(\"connected\");\n    await this.emit(\"connected\");\n  }\n}\n"],"mappings":"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"}

package/esm/drivers/in-memory-tag-index.d.mts

@@ -0,0 +1,44 @@
+//#region ../cache/src/drivers/in-memory-tag-index.d.ts
+/**
+ * Tag index for the in-process drivers (memory, memoryExtended, lru, mock).
+ *
+ * Lives beside the driver's entry storage, never inside it: index sets are not
+ * entries, so they are never subject to `maxSize` / LRU eviction or TTL
+ * sweeps, and every operation is synchronous — concurrent tagged writes in one
+ * process can never drop a member.
+ *
+ * Keys are the driver-parsed tag keys (`<prefix>.cache.tags.<tag>`); members
+ * are the caller's normalized, un-prefixed cache keys.
+ */
+declare class InMemoryTagIndex {
+  protected readonly sets: Map<string, Set<string>>;
+  /**
+   * Add members to a tag set, creating it on first use.
+   */
+  add(tagKey: string, members: readonly string[]): void;
+  /**
+   * The members of a tag set (a copy; empty when the set does not exist).
+   */
+  members(tagKey: string): string[];
+  /**
+   * Remove members from a tag set; an emptied set is dropped.
+   */
+  remove(tagKey: string, members: readonly string[]): void;
+  /**
+   * Drop a whole tag set.
+   */
+  delete(tagKey: string): void;
+  /**
+   * Drop every tag set whose key equals `namespace` or sits under
+   * `namespace.` — the same rule the drivers use for entries. An empty
+   * namespace clears everything.
+   */
+  removeNamespace(namespace: string): void;
+  /**
+   * Drop every tag set.
+   */
+  clear(): void;
+}
+//#endregion
+export { InMemoryTagIndex };
+//# sourceMappingURL=in-memory-tag-index.d.mts.map

package/esm/drivers/in-memory-tag-index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-tag-index.d.mts","names":[],"sources":["../../../../../../../cache/src/drivers/in-memory-tag-index.ts"],"mappings":";;AAWA;;;;;;;;;;cAAa,gBAAA;EAAA,mBACQ,IAAA,EAAM,GAAG,SAAS,GAAA;EAgC9B;;;EA3BA,GAAA,CAAI,MAAA,UAAgB,OAAA;EA8Cb;;;EA1BP,OAAA,CAAQ,MAAA;EAsDH;AAAA;;EA/CL,MAAA,CAAO,MAAA,UAAgB,OAAA;;;;EAmBvB,MAAA,CAAO,MAAA;;;;;;EASP,eAAA,CAAgB,SAAA;;;;EAmBhB,KAAA;AAAA"}

package/esm/drivers/in-memory-tag-index.mjs

@@ -0,0 +1,73 @@
+//#region ../cache/src/drivers/in-memory-tag-index.ts
+/**
+* Tag index for the in-process drivers (memory, memoryExtended, lru, mock).
+*
+* Lives beside the driver's entry storage, never inside it: index sets are not
+* entries, so they are never subject to `maxSize` / LRU eviction or TTL
+* sweeps, and every operation is synchronous — concurrent tagged writes in one
+* process can never drop a member.
+*
+* Keys are the driver-parsed tag keys (`<prefix>.cache.tags.<tag>`); members
+* are the caller's normalized, un-prefixed cache keys.
+*/
+var InMemoryTagIndex = class {
+	constructor() {
+		this.sets = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Add members to a tag set, creating it on first use.
+	*/
+	add(tagKey, members) {
+		if (members.length === 0) return;
+		let set = this.sets.get(tagKey);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.sets.set(tagKey, set);
+		}
+		for (const member of members) set.add(member);
+	}
+	/**
+	* The members of a tag set (a copy; empty when the set does not exist).
+	*/
+	members(tagKey) {
+		return [...this.sets.get(tagKey) ?? []];
+	}
+	/**
+	* Remove members from a tag set; an emptied set is dropped.
+	*/
+	remove(tagKey, members) {
+		const set = this.sets.get(tagKey);
+		if (!set) return;
+		for (const member of members) set.delete(member);
+		if (set.size === 0) this.sets.delete(tagKey);
+	}
+	/**
+	* Drop a whole tag set.
+	*/
+	delete(tagKey) {
+		this.sets.delete(tagKey);
+	}
+	/**
+	* Drop every tag set whose key equals `namespace` or sits under
+	* `namespace.` — the same rule the drivers use for entries. An empty
+	* namespace clears everything.
+	*/
+	removeNamespace(namespace) {
+		if (namespace === "") {
+			this.sets.clear();
+			return;
+		}
+		const prefix = namespace + ".";
+		for (const key of [...this.sets.keys()]) if (key === namespace || key.startsWith(prefix)) this.sets.delete(key);
+	}
+	/**
+	* Drop every tag set.
+	*/
+	clear() {
+		this.sets.clear();
+	}
+};
+
+//#endregion
+export { InMemoryTagIndex };
+//# sourceMappingURL=in-memory-tag-index.mjs.map

package/esm/drivers/in-memory-tag-index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-tag-index.mjs","names":[],"sources":["../../../../../../../cache/src/drivers/in-memory-tag-index.ts"],"sourcesContent":["/**\n * Tag index for the in-process drivers (memory, memoryExtended, lru, mock).\n *\n * Lives beside the driver's entry storage, never inside it: index sets are not\n * entries, so they are never subject to `maxSize` / LRU eviction or TTL\n * sweeps, and every operation is synchronous — concurrent tagged writes in one\n * process can never drop a member.\n *\n * Keys are the driver-parsed tag keys (`<prefix>.cache.tags.<tag>`); members\n * are the caller's normalized, un-prefixed cache keys.\n */\nexport class InMemoryTagIndex {\n  protected readonly sets: Map<string, Set<string>> = new Map();\n\n  /**\n   * Add members to a tag set, creating it on first use.\n   */\n  public add(tagKey: string, members: readonly string[]): void {\n    if (members.length === 0) {\n      return;\n    }\n\n    let set = this.sets.get(tagKey);\n\n    if (!set) {\n      set = new Set();\n      this.sets.set(tagKey, set);\n    }\n\n    for (const member of members) {\n      set.add(member);\n    }\n  }\n\n  /**\n   * The members of a tag set (a copy; empty when the set does not exist).\n   */\n  public members(tagKey: string): string[] {\n    return [...(this.sets.get(tagKey) ?? [])];\n  }\n\n  /**\n   * Remove members from a tag set; an emptied set is dropped.\n   */\n  public remove(tagKey: string, members: readonly string[]): void {\n    const set = this.sets.get(tagKey);\n\n    if (!set) {\n      return;\n    }\n\n    for (const member of members) {\n      set.delete(member);\n    }\n\n    if (set.size === 0) {\n      this.sets.delete(tagKey);\n    }\n  }\n\n  /**\n   * Drop a whole tag set.\n   */\n  public delete(tagKey: string): void {\n    this.sets.delete(tagKey);\n  }\n\n  /**\n   * Drop every tag set whose key equals `namespace` or sits under\n   * `namespace.` — the same rule the drivers use for entries. An empty\n   * namespace clears everything.\n   */\n  public removeNamespace(namespace: string): void {\n    if (namespace === \"\") {\n      this.sets.clear();\n\n      return;\n    }\n\n    const prefix = namespace + \".\";\n\n    for (const key of [...this.sets.keys()]) {\n      if (key === namespace || key.startsWith(prefix)) {\n        this.sets.delete(key);\n      }\n    }\n  }\n\n  /**\n   * Drop every tag set.\n   */\n  public clear(): void {\n    this.sets.clear();\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAWA,IAAa,mBAAb,MAA8B;;8BACwB,IAAI,IAAI;;;;;CAK5D,AAAO,IAAI,QAAgB,SAAkC;EAC3D,IAAI,QAAQ,WAAW,GACrB;EAGF,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM;EAE9B,IAAI,CAAC,KAAK;GACR,sBAAM,IAAI,IAAI;GACd,KAAK,KAAK,IAAI,QAAQ,GAAG;EAC3B;EAEA,KAAK,MAAM,UAAU,SACnB,IAAI,IAAI,MAAM;CAElB;;;;CAKA,AAAO,QAAQ,QAA0B;EACvC,OAAO,CAAC,GAAI,KAAK,KAAK,IAAI,MAAM,KAAK,CAAC,CAAE;CAC1C;;;;CAKA,AAAO,OAAO,QAAgB,SAAkC;EAC9D,MAAM,MAAM,KAAK,KAAK,IAAI,MAAM;EAEhC,IAAI,CAAC,KACH;EAGF,KAAK,MAAM,UAAU,SACnB,IAAI,OAAO,MAAM;EAGnB,IAAI,IAAI,SAAS,GACf,KAAK,KAAK,OAAO,MAAM;CAE3B;;;;CAKA,AAAO,OAAO,QAAsB;EAClC,KAAK,KAAK,OAAO,MAAM;CACzB;;;;;;CAOA,AAAO,gBAAgB,WAAyB;EAC9C,IAAI,cAAc,IAAI;GACpB,KAAK,KAAK,MAAM;GAEhB;EACF;EAEA,MAAM,SAAS,YAAY;EAE3B,KAAK,MAAM,OAAO,CAAC,GAAG,KAAK,KAAK,KAAK,CAAC,GACpC,IAAI,QAAQ,aAAa,IAAI,WAAW,MAAM,GAC5C,KAAK,KAAK,OAAO,GAAG;CAG1B;;;;CAKA,AAAO,QAAc;EACnB,KAAK,KAAK,MAAM;CAClB;AACF"}

package/esm/drivers/index.d.mts

@@ -6,4 +6,4 @@ import { MemoryExtendedCacheDriver } from "./memory-extended-cache-driver.mjs";
 import { MockCacheDriver } from "./mock-cache-driver.mjs";
 import { NullCacheDriver } from "./null-cache-driver.mjs";
 import { PgCacheDriver } from "./pg-cache-driver.mjs";
-import { RedisCacheDriver } from "./redis-cache-driver.mjs";
+import { REDIS_CAS_SET_SCRIPT, REDIS_COMPARE_DELETE_SCRIPT, REDIS_GET_DEL_SCRIPT, RedisCacheDriver } from "./redis-cache-driver.mjs";

package/esm/drivers/index.mjs

@@ -6,6 +6,6 @@ import { MemoryExtendedCacheDriver } from "./memory-extended-cache-driver.mjs";
 import { MockCacheDriver } from "./mock-cache-driver.mjs";
 import { NullCacheDriver } from "./null-cache-driver.mjs";
 import { PgCacheDriver } from "./pg-cache-driver.mjs";
-import { RedisCacheDriver } from "./redis-cache-driver.mjs";
+import { REDIS_CAS_SET_SCRIPT, REDIS_COMPARE_DELETE_SCRIPT, REDIS_GET_DEL_SCRIPT, RedisCacheDriver } from "./redis-cache-driver.mjs";
 
 export {  };

package/esm/drivers/lru-memory-cache-driver.d.mts

@@ -1,4 +1,5 @@
 import { BaseCacheDriver } from "./base-cache-driver.mjs";
+import { InMemoryTagIndex } from "./in-memory-tag-index.mjs";
 import { CacheData, CacheDriver, CacheKey, CacheSetOptions, CacheSimilarHit, CacheSimilarOptions, CacheTtl, LRUMemoryCacheOptions } from "../types.mjs";
 
 //#region ../cache/src/drivers/lru-memory-cache-driver.d.ts
@@ -36,6 +37,10 @@ declare class LRUMemoryCacheDriver extends BaseCacheDriver<LRUMemoryCacheDriver,
    * Cache map
    */
   protected cache: Map<string, CacheNode>;
+  /**
+   * Tag index, kept out of the LRU list so capacity pressure can never evict it.
+   */
+  protected tagIndex: InMemoryTagIndex;
   /**
    * Head of the cache
    */
@@ -96,6 +101,26 @@ declare class LRUMemoryCacheDriver extends BaseCacheDriver<LRUMemoryCacheDriver,
    * path.
    */
   protected getEntry(key: CacheKey): Promise<CacheData | null>;
+  /**
+   * Live node for `parsedKey`, or `undefined` when missing / expired (an
+   * expired node is unlinked). Synchronous.
+   */
+  protected liveNode(parsedKey: string): CacheNode | undefined;
+  /**
+   * {@inheritdoc}
+   *
+   * Read, add and write run synchronously (no `await` in between), so
+   * concurrent increments in this process never lose an update. An existing
+   * node keeps its expiry; a missing key starts from 0 with the default TTL.
+   */
+  increment(key: CacheKey, value?: number): Promise<number>;
+  /**
+   * {@inheritdoc}
+   *
+   * Read and unlink run synchronously, so a value is handed out exactly once
+   * even when concurrent callers pull the same key.
+   */
+  pull(key: CacheKey): Promise<any | null>;
   /**
    * {@inheritdoc}
    */
@@ -104,6 +129,24 @@ declare class LRUMemoryCacheDriver extends BaseCacheDriver<LRUMemoryCacheDriver,
    * {@inheritdoc}
    */
   remove(key: CacheKey): Promise<void>;
+  /**
+   * {@inheritdoc}
+   *
+   * Synchronous in-process set, never evicted or expired with the entries.
+   */
+  tagAdd(tagKey: CacheKey, members: string[]): Promise<void>;
+  /**
+   * {@inheritdoc}
+   */
+  tagMembers(tagKey: CacheKey): Promise<string[]>;
+  /**
+   * {@inheritdoc}
+   */
+  tagRemove(tagKey: CacheKey, members: string[]): Promise<void>;
+  /**
+   * {@inheritdoc}
+   */
+  tagDelete(tagKey: CacheKey): Promise<void>;
   /**
    * {@inheritdoc}
    *

package/esm/drivers/lru-memory-cache-driver.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"lru-memory-cache-driver.d.mts","names":[],"sources":["../../../../../../../cache/src/drivers/lru-memory-cache-driver.ts"],"mappings":";;;;cAcM,SAAA;EAeK,GAAA;EACA,KAAA;EAfF,IAAA,EAAM,SAAA;EACN,IAAA,EAAM,SAAS;EACf,SAAA;EAYE;;;;EAPF,OAAA;EANM;;;;EAWN,MAAA;cAEE,GAAA,UACA,KAAA,OACP,GAAA;EAAA,IAOS,SAAA;AAAA;;;AAAS;AAWtB;;;cAAa,oBAAA,SACH,eAAA,CAAgB,oBAAA,EAAsB,qBAAA,aACnC,WAAA,CAAY,oBAAA,EAAsB,qBAAA;EADC;;;EAMvC,IAAA;EAKU;;;EAAA,UAAP,KAAA,EAAO,GAAA,SAAY,SAAA;EA8EiB;;;EAAA,UAzEpC,IAAA,EAAM,SAAA;EAmHb;;;EAAA,UA9GO,IAAA,EAAM,SAAA;EAoOc;;;EAAA,UA/NpB,eAAA,GAAkB,MAAA,CAAO,OAAA;EAiPL;;;;EA6GnB;;;EA/UJ,IAAA;EA+XgB;;;EAvXhB,YAAA;EAhDe;;;;;;;;EAwFT,eAAA,CAAgB,SAAA,WAAiB,OAAA;EA9E7B;;;EAoHJ,GAAA,CACX,GAAA,EAAK,QAAA,EACL,KAAA,OACA,YAAA,GAAe,QAAA,GAAW,eAAA,GACzB,OAAA;EA9GO;;;EAAA,UA4LA,QAAA,CAAS,IAAA,EAAM,SAAA;EAvLU;;;EAAA,UA+LzB,UAAA,CAAW,IAAA,EAAM,SAAA;EAhId;;;EAAA,UAwIH,OAAA,CAAQ,IAAA,EAAM,SAAA;EAjGjB;;;EAAA,UA2GG,UAAA;EAzGkB;;;;;;EAAA,UAuHZ,QAAA,CAAS,GAAA,EAAK,QAAA,GAAW,OAAA,CAAQ,SAAA;EAhCtB;;;EAkDd,GAAA,CAAI,GAAA,EAAK,QAAA,GAAQ,OAAA;EA1CZ;;;EAoGL,MAAA,CAAO,GAAA,EAAK,QAAA,GAAQ,OAAA;EA5ER;;;;;;;EAqGZ,KAAA,IAAK,OAAA;EAzBO;;;;;;;;;EAiDZ,OAAA,UACX,MAAA,YACA,OAAA,EAAS,mBAAA,GACR,OAAA,CAAQ,eAAA,CAAgB,CAAA;EAAxB;;;EAAA,IAwCQ,QAAA;EAOE;;;EAAA,UAAA,IAAU,OAAA;AAAA"}
+{"version":3,"file":"lru-memory-cache-driver.d.mts","names":[],"sources":["../../../../../../../cache/src/drivers/lru-memory-cache-driver.ts"],"mappings":";;;;;cAeM,SAAA;EAeK,GAAA;EACA,KAAA;EAfF,IAAA,EAAM,SAAA;EACN,IAAA,EAAM,SAAS;EACf,SAAA;EAYE;;;;EAPF,OAAA;EANM;;;;EAWN,MAAA;cAEE,GAAA,UACA,KAAA,OACP,GAAA;EAAA,IAOS,SAAA;AAAA;;;AAAS;AAWtB;;;cAAa,oBAAA,SACH,eAAA,CAAgB,oBAAA,EAAsB,qBAAA,aACnC,WAAA,CAAY,oBAAA,EAAsB,qBAAA;EADC;;;EAMvC,IAAA;EAKU;;;EAAA,UAAP,KAAA,EAAO,GAAA,SAAY,SAAA;EAoBD;;;EAAA,UAflB,QAAA,EAAU,gBAAA;EAyHQ;;;EAAA,UApHlB,IAAA,EAAM,SAAA;EAmNQ;;;EAAA,UA9Md,IAAA,EAAM,SAAA;EAyPuB;;;EAAA,UApP7B,eAAA,GAAkB,MAAA,CAAO,OAAA;EAgTD;;;;EAqFD;;;EAtX1B,IAAA;EAoZoC;;;EA5YpC,YAAA;EA0ZmC;;;;;;;;EAlX7B,eAAA,CAAgB,SAAA,WAAiB,OAAA;EA7FxB;;;EAqIT,GAAA,CACX,GAAA,EAAK,QAAA,EACL,KAAA,OACA,YAAA,GAAe,QAAA,GAAW,eAAA,GACzB,OAAA;EA1I2C;;;EAAA,UAwNpC,QAAA,CAAS,IAAA,EAAM,SAAA;EAlNlB;;;EAAA,UA0NG,UAAA,CAAW,IAAA,EAAM,SAAA;EAhNjB;;;EAAA,UAwNA,OAAA,CAAQ,IAAA,EAAM,SAAA;EA9Md;;;EAAA,UAwNA,UAAA;EAnNyB;;;;;;EAAA,UAiOnB,QAAA,CAAS,GAAA,EAAK,QAAA,GAAW,OAAA,CAAQ,SAAA;EA1HpC;;;;EAAA,UA6IH,QAAA,CAAS,SAAA,WAAoB,SAAA;EA1IX;;;;;;;EAkKf,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAoB,OAAA;EA3ErC;;;;;;EA+GR,IAAA,CAAK,GAAA,EAAK,QAAA,GAAW,OAAA;EA/ET;;;EA0GZ,GAAA,CAAI,GAAA,EAAK,QAAA,GAAQ,OAAA;EAvFX;;;EAiJN,MAAA,CAAO,GAAA,EAAK,QAAA,GAAQ,OAAA;EAzHV;;;;;EAgJV,MAAA,CAAO,MAAA,EAAQ,QAAA,EAAU,OAAA,aAAoB,OAAA;EA5GxB;;;EAmHrB,UAAA,CAAW,MAAA,EAAQ,QAAA,GAAW,OAAA;EAxFb;;;EA+FjB,SAAA,CAAU,MAAA,EAAQ,QAAA,EAAU,OAAA,aAAoB,OAAA;EArC5B;;;EA4CpB,SAAA,CAAU,MAAA,EAAQ,QAAA,GAAW,OAAA;EArBJ;;;;;;;EAgCzB,KAAA,IAAK,OAAA;EAlBK;;;;;;;;;EA2CV,OAAA,UACX,MAAA,YACA,OAAA,EAAS,mBAAA,GACR,OAAA,CAAQ,eAAA,CAAgB,CAAA;EAHN;;;EAAA,IA2CV,QAAA;EAxCR;;;EA+CU,UAAA,IAAU,OAAA;AAAA"}

package/esm/drivers/lru-memory-cache-driver.mjs

@@ -1,5 +1,6 @@
 import { cosineSimilarity } from "../utils.mjs";
 import { BaseCacheDriver } from "./base-cache-driver.mjs";
+import { InMemoryTagIndex } from "./in-memory-tag-index.mjs";
 
 //#region ../cache/src/drivers/lru-memory-cache-driver.ts
 var CacheNode = class {
@@ -28,6 +29,7 @@ var LRUMemoryCacheDriver = class extends BaseCacheDriver {
 		super();
 		this.name = "lru";
 		this.cache = /* @__PURE__ */ new Map();
+		this.tagIndex = new InMemoryTagIndex();
 		this.head = new CacheNode("", null);
 		this.tail = new CacheNode("", null);
 		this.init();
@@ -73,6 +75,7 @@ var LRUMemoryCacheDriver = class extends BaseCacheDriver {
 		const parsedNamespace = this.parseKey(namespace);
 		this.log("clearing", parsedNamespace || "(all)");
 		const removed = [];
+		this.tagIndex.removeNamespace(parsedNamespace);
 		if (parsedNamespace === "") for (const key of this.cache.keys()) removed.push(key);
 		else {
 			const prefix = parsedNamespace + ".";
@@ -187,6 +190,72 @@ var LRUMemoryCacheDriver = class extends BaseCacheDriver {
 		};
 	}
 	/**
+	* Live node for `parsedKey`, or `undefined` when missing / expired (an
+	* expired node is unlinked). Synchronous.
+	*/
+	liveNode(parsedKey) {
+		const node = this.cache.get(parsedKey);
+		if (!node) return;
+		if (node.isExpired) {
+			this.removeNode(node);
+			this.cache.delete(parsedKey);
+			return;
+		}
+		return node;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Read, add and write run synchronously (no `await` in between), so
+	* concurrent increments in this process never lose an update. An existing
+	* node keeps its expiry; a missing key starts from 0 with the default TTL.
+	*/
+	async increment(key, value = 1) {
+		const parsedKey = this.parseKey(key);
+		const node = this.liveNode(parsedKey);
+		const current = node ? node.value : 0;
+		if (typeof current !== "number") throw new Error(`Cannot increment non-numeric value for key: ${parsedKey}`);
+		const newValue = current + value;
+		if (node) {
+			node.value = newValue;
+			this.moveHead(node);
+		} else {
+			const newNode = new CacheNode(parsedKey, newValue, this.ttl);
+			this.cache.set(parsedKey, newNode);
+			this.addNode(newNode);
+			if (this.cache.size > this.capacity) this.removeTail();
+		}
+		await this.emit("set", {
+			key: parsedKey,
+			value: newValue,
+			ttl: this.ttl
+		});
+		return newValue;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Read and unlink run synchronously, so a value is handed out exactly once
+	* even when concurrent callers pull the same key.
+	*/
+	async pull(key) {
+		const parsedKey = this.parseKey(key);
+		const node = this.liveNode(parsedKey);
+		if (!node) {
+			await this.emit("miss", { key: parsedKey });
+			return null;
+		}
+		this.removeNode(node);
+		this.cache.delete(parsedKey);
+		const value = node.value !== null && typeof node.value === "object" ? structuredClone(node.value) : node.value;
+		await this.emit("hit", {
+			key: parsedKey,
+			value
+		});
+		await this.emit("removed", { key: parsedKey });
+		return value;
+	}
+	/**
 	* {@inheritdoc}
 	*/
 	async get(key) {
@@ -247,6 +316,32 @@ var LRUMemoryCacheDriver = class extends BaseCacheDriver {
 	/**
 	* {@inheritdoc}
 	*
+	* Synchronous in-process set, never evicted or expired with the entries.
+	*/
+	async tagAdd(tagKey, members) {
+		this.tagIndex.add(this.parseKey(tagKey), members);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async tagMembers(tagKey) {
+		return this.tagIndex.members(this.parseKey(tagKey));
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async tagRemove(tagKey, members) {
+		this.tagIndex.remove(this.parseKey(tagKey), members);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async tagDelete(tagKey) {
+		this.tagIndex.delete(this.parseKey(tagKey));
+	}
+	/**
+	* {@inheritdoc}
+	*
 	* When a `globalPrefix` is configured, `flush` scopes itself to that prefix
 	* so multi-tenant caches don't accidentally wipe sibling tenants. Without
 	* a prefix, clears everything.
@@ -256,6 +351,7 @@ var LRUMemoryCacheDriver = class extends BaseCacheDriver {
 		if (this.options.globalPrefix) await this.removeNamespace("");
 		else {
 			this.cache.clear();
+			this.tagIndex.clear();
 			this.init();
 		}
 		this.log("flushed");