@warlock.js/cache 4.0.171 → 4.1.1

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

@@ -0,0 +1,174 @@
+import { CacheConfigurationError, CacheUnsupportedError } from "../types.mjs";
+import { BaseCacheDriver } from "./base-cache-driver.mjs";
+import { ensureDirectoryAsync, getJsonFileAsync, putJsonFileAsync, removeDirectoryAsync } from "@warlock.js/fs";
+import path from "path";
+
+//#region ../../@warlock.js/cache/src/drivers/file-cache-driver.ts
+var FileCacheDriver = class extends BaseCacheDriver {
+	constructor(..._args) {
+		super(..._args);
+		this.name = "file";
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	setOptions(options) {
+		if (!options.directory) throw new CacheConfigurationError("File driver requires 'directory' option to be configured.");
+		return super.setOptions(options);
+	}
+	/**
+	* Get the cache directory
+	*/
+	get directory() {
+		const directory = this.options.directory;
+		if (typeof directory === "function") return directory();
+		throw new CacheConfigurationError("Cache directory is not defined, please define it in the file driver options");
+	}
+	/**
+	* Get file name
+	*/
+	get fileName() {
+		const fileName = this.options.fileName;
+		if (typeof fileName === "function") return fileName();
+		return "cache.json";
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async removeNamespace(namespace) {
+		this.log("clearing", namespace);
+		try {
+			await removeDirectoryAsync(path.resolve(this.directory, namespace));
+			this.log("cleared", namespace);
+		} catch (error) {}
+		return this;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	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
+		};
+		if (onConflict === "update" && !exists) return {
+			wasSet: false,
+			existing: null
+		};
+		const data = this.prepareDataForStorage(value, ttl, staleAt);
+		const fileDirectory = path.resolve(this.directory, parsedKey);
+		await ensureDirectoryAsync(fileDirectory);
+		await putJsonFileAsync(path.resolve(fileDirectory, this.fileName), data);
+		if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+		this.log("cached", parsedKey);
+		await this.emit("set", {
+			key: parsedKey,
+			value,
+			ttl
+		});
+		if (onConflict === "create" || onConflict === "update") return {
+			wasSet: true,
+			existing: null
+		};
+		return this;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* File driver does not yet ship with a file-lock primitive, so concurrent
+	* writers could clobber each other. Rather than ship an unsafe default, we
+	* throw — consumers can fall back to memory/redis for `update` until a
+	* proper file lock lands (tracked in `domains/cache/backlog.md`).
+	*/
+	async update() {
+		throw new CacheUnsupportedError("`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).");
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async merge() {
+		throw new CacheUnsupportedError("`merge()` is not supported on the file driver. Use the memory or redis driver.");
+	}
+	/**
+	* Read the raw {@link CacheData} wrapper from disk, including `staleAt`
+	* metadata. Returns `null` for missing or expired files — `swr()`
+	* consumes this to branch on freshness.
+	*/
+	async getEntry(key) {
+		const parsedKey = this.parseKey(key);
+		const fileDirectory = path.resolve(this.directory, parsedKey);
+		try {
+			const entry = await getJsonFileAsync(path.resolve(fileDirectory, this.fileName));
+			if (!entry) return null;
+			if (entry.expiresAt !== void 0 && entry.expiresAt <= Date.now()) return null;
+			return entry;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async get(key) {
+		const parsedKey = this.parseKey(key);
+		this.log("fetching", parsedKey);
+		const fileDirectory = path.resolve(this.directory, parsedKey);
+		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) {
+			this.log("notFound", parsedKey);
+			await this.emit("miss", { key: parsedKey });
+			await this.remove(key);
+			return null;
+		}
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async remove(key) {
+		const parsedKey = this.parseKey(key);
+		this.log("removing", parsedKey);
+		const fileDirectory = path.resolve(this.directory, parsedKey);
+		try {
+			await removeDirectoryAsync(fileDirectory);
+			this.log("removed", parsedKey);
+			await this.emit("removed", { key: parsedKey });
+		} catch (error) {}
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async flush() {
+		this.log("flushing");
+		if (this.options.globalPrefix) await this.removeNamespace("");
+		else await removeDirectoryAsync(this.directory);
+		this.log("flushed");
+		await this.emit("flushed");
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async connect() {
+		this.log("connecting");
+		await ensureDirectoryAsync(this.directory);
+		this.log("connected");
+		await this.emit("connected");
+	}
+};
+
+//#endregion
+export { FileCacheDriver };
+//# sourceMappingURL=file-cache-driver.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-cache-driver.mjs","names":[],"sources":["../../../../../../@warlock.js/cache/src/drivers/file-cache-driver.ts"],"sourcesContent":["import {\r\n  ensureDirectoryAsync,\r\n  getJsonFileAsync,\r\n  putJsonFileAsync,\r\n  removeDirectoryAsync,\r\n} from \"@warlock.js/fs\";\r\nimport path from \"path\";\r\nimport type {\r\n  CacheData,\r\n  CacheDriver,\r\n  CacheKey,\r\n  CacheSetOptions,\r\n  CacheSetResult,\r\n  CacheTtl,\r\n  FileCacheOptions,\r\n} from \"../types\";\r\nimport { CacheConfigurationError, CacheUnsupportedError } from \"../types\";\r\nimport { BaseCacheDriver } from \"./base-cache-driver\";\r\n\r\nexport class FileCacheDriver\r\n  extends BaseCacheDriver<FileCacheDriver, FileCacheOptions>\r\n  implements CacheDriver<FileCacheDriver, FileCacheOptions>\r\n{\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public name = \"file\";\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public setOptions(options: FileCacheOptions) {\r\n    if (!options.directory) {\r\n      throw new CacheConfigurationError(\r\n        \"File driver requires 'directory' option to be configured.\",\r\n      );\r\n    }\r\n\r\n    return super.setOptions(options);\r\n  }\r\n\r\n  /**\r\n   * Get the cache directory\r\n   */\r\n  public get directory() {\r\n    const directory = this.options.directory;\r\n\r\n    if (typeof directory === \"function\") {\r\n      return directory();\r\n    }\r\n\r\n    throw new CacheConfigurationError(\r\n      \"Cache directory is not defined, please define it in the file driver options\",\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Get file name\r\n   */\r\n  public get fileName() {\r\n    const fileName = this.options.fileName;\r\n\r\n    if (typeof fileName === \"function\") {\r\n      return fileName();\r\n    }\r\n\r\n    return \"cache.json\";\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async removeNamespace(namespace: string) {\r\n    this.log(\"clearing\", namespace);\r\n\r\n    try {\r\n      await removeDirectoryAsync(path.resolve(this.directory, namespace));\r\n\r\n      this.log(\"cleared\", namespace);\r\n    } catch (error) {\r\n      //\r\n    }\r\n\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async set(\r\n    key: CacheKey,\r\n    value: any,\r\n    ttlOrOptions?: CacheTtl | CacheSetOptions,\r\n  ): Promise<any> {\r\n    const parsedKey = this.parseKey(key);\r\n    const { ttl, tags, onConflict, vector, staleAt } = this.resolveSetOptions(ttlOrOptions);\r\n\r\n    if (vector) {\r\n      throw new CacheUnsupportedError(\r\n        \"'file' 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    this.log(\"caching\", parsedKey);\r\n\r\n    const existing = onConflict === \"upsert\" ? null : await this.get(key);\r\n    const exists = existing !== null;\r\n\r\n    if (onConflict === \"create\" && exists) {\r\n      const result: CacheSetResult = { wasSet: false, existing };\r\n      return result;\r\n    }\r\n\r\n    if (onConflict === \"update\" && !exists) {\r\n      const result: CacheSetResult = { wasSet: false, existing: null };\r\n      return result;\r\n    }\r\n\r\n    const data = this.prepareDataForStorage(value, ttl, staleAt);\r\n\r\n    const fileDirectory = path.resolve(this.directory, parsedKey);\r\n\r\n    await ensureDirectoryAsync(fileDirectory);\r\n\r\n    await putJsonFileAsync(path.resolve(fileDirectory, this.fileName), data);\r\n\r\n    if (tags && tags.length > 0) {\r\n      await this.applyTags(parsedKey, tags);\r\n    }\r\n\r\n    this.log(\"cached\", parsedKey);\r\n\r\n    await this.emit(\"set\", { key: parsedKey, value, ttl });\r\n\r\n    if (onConflict === \"create\" || onConflict === \"update\") {\r\n      const result: CacheSetResult = { wasSet: true, existing: null };\r\n      return result;\r\n    }\r\n\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   *\r\n   * File driver does not yet ship with a file-lock primitive, so concurrent\r\n   * writers could clobber each other. Rather than ship an unsafe default, we\r\n   * throw — consumers can fall back to memory/redis for `update` until a\r\n   * proper file lock lands (tracked in `domains/cache/backlog.md`).\r\n   */\r\n  public async update(): Promise<never> {\r\n    throw new CacheUnsupportedError(\r\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).\",\r\n    );\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async merge(): Promise<never> {\r\n    throw new CacheUnsupportedError(\r\n      \"`merge()` is not supported on the file driver. Use the memory or redis driver.\",\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Read the raw {@link CacheData} wrapper from disk, including `staleAt`\r\n   * metadata. Returns `null` for missing or expired files — `swr()`\r\n   * consumes this to branch on freshness.\r\n   */\r\n  protected async getEntry(key: CacheKey): Promise<CacheData | null> {\r\n    const parsedKey = this.parseKey(key);\r\n    const fileDirectory = path.resolve(this.directory, parsedKey);\r\n\r\n    try {\r\n      const entry = (await getJsonFileAsync(path.resolve(fileDirectory, this.fileName))) as\r\n        | CacheData\r\n        | undefined;\r\n\r\n      if (!entry) {\r\n        return null;\r\n      }\r\n\r\n      if (entry.expiresAt !== undefined && entry.expiresAt <= Date.now()) {\r\n        return null;\r\n      }\r\n\r\n      return entry;\r\n    } catch {\r\n      return null;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async get(key: CacheKey) {\r\n    const parsedKey = this.parseKey(key);\r\n\r\n    this.log(\"fetching\", parsedKey);\r\n\r\n    const fileDirectory = path.resolve(this.directory, parsedKey);\r\n\r\n    try {\r\n      const value = await getJsonFileAsync(path.resolve(fileDirectory, this.fileName));\r\n\r\n      const result = await this.parseCachedData(parsedKey, value as CacheData);\r\n\r\n      if (result === null) {\r\n        // Expired\r\n        await this.emit(\"miss\", { key: parsedKey });\r\n      } else {\r\n        // Emit hit event\r\n        await this.emit(\"hit\", { key: parsedKey, value: result });\r\n      }\r\n\r\n      return result;\r\n    } catch (error) {\r\n      this.log(\"notFound\", parsedKey);\r\n      // Emit miss event\r\n      await this.emit(\"miss\", { key: parsedKey });\r\n      // Await the cleanup so it fully settles before returning. Leaving this\r\n      // fire-and-forget let the async directory removal race a follow-up write\r\n      // to the same key (e.g. the existence probe inside a `set({ onConflict })`\r\n      // call), surfacing as an ENOENT mkdir/rm collision on Windows.\r\n      await this.remove(key);\r\n      return null;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async remove(key: CacheKey) {\r\n    const parsedKey = this.parseKey(key);\r\n    this.log(\"removing\", parsedKey);\r\n\r\n    const fileDirectory = path.resolve(this.directory, parsedKey);\r\n\r\n    try {\r\n      await removeDirectoryAsync(fileDirectory);\r\n\r\n      this.log(\"removed\", parsedKey);\r\n      // Emit removed event\r\n      await this.emit(\"removed\", { key: parsedKey });\r\n    } catch (error) {\r\n      //\r\n    }\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async flush() {\r\n    this.log(\"flushing\");\r\n\r\n    if (this.options.globalPrefix) {\r\n      await this.removeNamespace(\"\");\r\n    } else {\r\n      await removeDirectoryAsync(this.directory);\r\n    }\r\n\r\n    this.log(\"flushed\");\r\n\r\n    // Emit flushed event\r\n    await this.emit(\"flushed\");\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async connect() {\r\n    this.log(\"connecting\");\r\n    await ensureDirectoryAsync(this.directory);\r\n    this.log(\"connected\");\r\n    await this.emit(\"connected\");\r\n  }\r\n}\r\n"],"mappings":"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"}

package/esm/drivers/index.d.mts

@@ -0,0 +1,9 @@
+import { BaseCacheDriver, NormalizedSetOptions } from "./base-cache-driver.mjs";
+import { FileCacheDriver } from "./file-cache-driver.mjs";
+import { LRUMemoryCacheDriver } from "./lru-memory-cache-driver.mjs";
+import { MemoryCacheDriver } from "./memory-cache-driver.mjs";
+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";

package/esm/drivers/index.mjs

@@ -0,0 +1,11 @@
+import { BaseCacheDriver } from "./base-cache-driver.mjs";
+import { FileCacheDriver } from "./file-cache-driver.mjs";
+import { LRUMemoryCacheDriver } from "./lru-memory-cache-driver.mjs";
+import { MemoryCacheDriver } from "./memory-cache-driver.mjs";
+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";
+
+export {  };

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

@@ -0,0 +1,136 @@
+import { BaseCacheDriver } from "./base-cache-driver.mjs";
+import { CacheData, CacheDriver, CacheKey, CacheSetOptions, CacheSimilarHit, CacheSimilarOptions, CacheTtl, LRUMemoryCacheOptions } from "../types.mjs";
+
+//#region ../../@warlock.js/cache/src/drivers/lru-memory-cache-driver.d.ts
+declare class CacheNode {
+  key: string;
+  value: any;
+  next: CacheNode | null;
+  prev: CacheNode | null;
+  expiresAt?: number;
+  /**
+   * Freshness deadline (ms timestamp) — populated by `swr()`. Within
+   * `expiresAt > now > staleAt` the entry is "stale-but-revalidatable."
+   */
+  staleAt?: number;
+  /**
+   * Optional embedding vector — populated when the entry was written with
+   * `set({ vector })`. Scanned by `similar()`.
+   */
+  vector?: number[];
+  constructor(key: string, value: any, ttl?: number);
+  get isExpired(): boolean;
+}
+/**
+ * LRU Memory Cache Driver
+ * The concept of LRU is to remove the least recently used data
+ * whenever the cache is full
+ * The question that resides here is how to tell the cache is full?
+ */
+declare class LRUMemoryCacheDriver extends BaseCacheDriver<LRUMemoryCacheDriver, LRUMemoryCacheOptions> implements CacheDriver<LRUMemoryCacheDriver, LRUMemoryCacheOptions> {
+  /**
+   * {@inheritdoc}
+   */
+  name: string;
+  /**
+   * Cache map
+   */
+  protected cache: Map<string, CacheNode>;
+  /**
+   * Head of the cache
+   */
+  protected head: CacheNode;
+  /**
+   * Tail of the cache
+   */
+  protected tail: CacheNode;
+  /**
+   * Cleanup interval reference
+   */
+  protected cleanupInterval?: NodeJS.Timeout;
+  /**
+   * {@inheritdoc}
+   */
+  constructor();
+  /**
+   * Initialize the cache
+   */
+  init(): void;
+  /**
+   * Start the cleanup process for expired items
+   */
+  startCleanup(): void;
+  /**
+   * {@inheritdoc}
+   *
+   * Clears every entry whose key starts with the parsed namespace (followed
+   * by a dot) or equals it exactly. Called with an empty namespace while a
+   * `globalPrefix` is configured, clears everything under the prefix — which
+   * is how `flush()` scopes cleanup per tenant.
+   */
+  removeNamespace(namespace: string): Promise<string[]>;
+  /**
+   * {@inheritdoc}
+   */
+  set(key: CacheKey, value: any, ttlOrOptions?: CacheTtl | CacheSetOptions): Promise<any>;
+  /**
+   * Move the node to the head
+   */
+  protected moveHead(node: CacheNode): void;
+  /**
+   * Remove the node from the cache
+   */
+  protected removeNode(node: CacheNode): void;
+  /**
+   * Add the node to the head
+   */
+  protected addNode(node: CacheNode): void;
+  /**
+   * Remove the tail node
+   */
+  protected removeTail(): void;
+  /**
+   * Read the raw {@link CacheData} wrapper, including `staleAt` metadata.
+   * Returns `null` for missing or expired nodes — `swr()` consumes this
+   * to branch on freshness without going through `get()`'s clone-and-emit
+   * path.
+   */
+  protected getEntry(key: CacheKey): Promise<CacheData | null>;
+  /**
+   * {@inheritdoc}
+   */
+  get(key: CacheKey): Promise<any>;
+  /**
+   * {@inheritdoc}
+   */
+  remove(key: CacheKey): Promise<void>;
+  /**
+   * {@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.
+   */
+  flush(): Promise<void>;
+  /**
+   * {@inheritdoc}
+   *
+   * Brute-force O(N) cosine similarity over every cached node that carries a
+   * vector. Suitable for development and small in-memory knowledge bases —
+   * not for production beyond ~10k entries.
+   *
+   * @warning Dev-only — O(N) per query.
+   */
+  similar<T = any>(vector: number[], options: CacheSimilarOptions): Promise<CacheSimilarHit<T>[]>;
+  /**
+   * Get lru capacity
+   */
+  get capacity(): number;
+  /**
+   * {@inheritdoc}
+   */
+  disconnect(): Promise<void>;
+}
+//#endregion
+export { LRUMemoryCacheDriver };
+//# sourceMappingURL=lru-memory-cache-driver.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lru-memory-cache-driver.d.mts","names":[],"sources":["../../../../../../@warlock.js/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,CAAA;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,CAAA;EA+XgB;;;EAvXhB,YAAA,CAAA;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,CAAA;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,CAAA,GAAK,OAAA;EAzBO;;;;;;;;;EAiDZ,OAAA,SAAA,CACX,MAAA,YACA,OAAA,EAAS,mBAAA,GACR,OAAA,CAAQ,eAAA,CAAgB,CAAA;EAAxB;;;EAAA,IAwCQ,QAAA,CAAA;EAOE;;;EAAA,UAAA,CAAA,GAAU,OAAA;AAAA"}

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

@@ -0,0 +1,317 @@
+import { cosineSimilarity } from "../utils.mjs";
+import { BaseCacheDriver } from "./base-cache-driver.mjs";
+
+//#region ../../@warlock.js/cache/src/drivers/lru-memory-cache-driver.ts
+var CacheNode = class {
+	constructor(key, value, ttl) {
+		this.key = key;
+		this.value = value;
+		this.next = null;
+		this.prev = null;
+		if (ttl && ttl !== Infinity) this.expiresAt = Date.now() + ttl * 1e3;
+	}
+	get isExpired() {
+		return this.expiresAt !== void 0 && this.expiresAt < Date.now();
+	}
+};
+/**
+* LRU Memory Cache Driver
+* The concept of LRU is to remove the least recently used data
+* whenever the cache is full
+* The question that resides here is how to tell the cache is full?
+*/
+var LRUMemoryCacheDriver = class extends BaseCacheDriver {
+	/**
+	* {@inheritdoc}
+	*/
+	constructor() {
+		super();
+		this.name = "lru";
+		this.cache = /* @__PURE__ */ new Map();
+		this.head = new CacheNode("", null);
+		this.tail = new CacheNode("", null);
+		this.init();
+		this.startCleanup();
+	}
+	/**
+	* Initialize the cache
+	*/
+	init() {
+		this.head.next = this.tail;
+		this.tail.prev = this.head;
+	}
+	/**
+	* Start the cleanup process for expired items
+	*/
+	startCleanup() {
+		if (this.cleanupInterval) clearInterval(this.cleanupInterval);
+		this.cleanupInterval = setInterval(async () => {
+			const now = Date.now();
+			const expiredKeys = [];
+			for (const [key, node] of this.cache) if (node.expiresAt && node.expiresAt <= now) expiredKeys.push(key);
+			for (const key of expiredKeys) {
+				const node = this.cache.get(key);
+				if (node) {
+					this.removeNode(node);
+					this.cache.delete(key);
+					this.log("expired", key);
+					await this.emit("expired", { key });
+				}
+			}
+		}, 1e3);
+		this.cleanupInterval.unref();
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Clears every entry whose key starts with the parsed namespace (followed
+	* by a dot) or equals it exactly. Called with an empty namespace while a
+	* `globalPrefix` is configured, clears everything under the prefix — which
+	* is how `flush()` scopes cleanup per tenant.
+	*/
+	async removeNamespace(namespace) {
+		const parsedNamespace = this.parseKey(namespace);
+		this.log("clearing", parsedNamespace || "(all)");
+		const removed = [];
+		if (parsedNamespace === "") for (const key of this.cache.keys()) removed.push(key);
+		else {
+			const prefix = parsedNamespace + ".";
+			for (const key of this.cache.keys()) if (key === parsedNamespace || key.startsWith(prefix)) removed.push(key);
+		}
+		for (const key of removed) {
+			const node = this.cache.get(key);
+			if (node) {
+				this.removeNode(node);
+				this.cache.delete(key);
+			}
+			await this.emit("removed", { key });
+		}
+		this.log("cleared", parsedNamespace || "(all)");
+		return removed;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async set(key, value, ttlOrOptions) {
+		const parsedKey = this.parseKey(key);
+		const { ttl, tags, onConflict, vector, staleAt } = this.resolveSetOptions(ttlOrOptions);
+		this.log("caching", parsedKey);
+		let existingNode = this.cache.get(parsedKey);
+		if (existingNode && existingNode.isExpired) {
+			this.removeNode(existingNode);
+			this.cache.delete(parsedKey);
+			existingNode = void 0;
+		}
+		const exists = Boolean(existingNode);
+		if (onConflict === "create" && exists) return {
+			wasSet: false,
+			existing: existingNode.value
+		};
+		if (onConflict === "update" && !exists) return {
+			wasSet: false,
+			existing: null
+		};
+		if (existingNode) {
+			existingNode.value = value;
+			if (ttl && ttl !== Infinity) existingNode.expiresAt = Date.now() + ttl * 1e3;
+			else existingNode.expiresAt = void 0;
+			existingNode.staleAt = staleAt;
+			if (vector) existingNode.vector = vector.slice();
+			this.moveHead(existingNode);
+		} else {
+			const newNode = new CacheNode(parsedKey, value, ttl);
+			newNode.staleAt = staleAt;
+			if (vector) newNode.vector = vector.slice();
+			this.cache.set(parsedKey, newNode);
+			this.addNode(newNode);
+			if (this.cache.size > this.capacity) this.removeTail();
+		}
+		if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+		this.log("cached", parsedKey);
+		await this.emit("set", {
+			key: parsedKey,
+			value,
+			ttl
+		});
+		if (onConflict === "create" || onConflict === "update") return {
+			wasSet: true,
+			existing: null
+		};
+		return this;
+	}
+	/**
+	* Move the node to the head
+	*/
+	moveHead(node) {
+		this.removeNode(node);
+		this.addNode(node);
+	}
+	/**
+	* Remove the node from the cache
+	*/
+	removeNode(node) {
+		node.prev.next = node.next;
+		node.next.prev = node.prev;
+	}
+	/**
+	* Add the node to the head
+	*/
+	addNode(node) {
+		node.next = this.head.next;
+		node.prev = this.head;
+		this.head.next.prev = node;
+		this.head.next = node;
+	}
+	/**
+	* Remove the tail node
+	*/
+	removeTail() {
+		const node = this.tail.prev;
+		this.removeNode(node);
+		this.cache.delete(node.key);
+	}
+	/**
+	* Read the raw {@link CacheData} wrapper, including `staleAt` metadata.
+	* Returns `null` for missing or expired nodes — `swr()` consumes this
+	* to branch on freshness without going through `get()`'s clone-and-emit
+	* path.
+	*/
+	async getEntry(key) {
+		const parsedKey = this.parseKey(key);
+		const node = this.cache.get(parsedKey);
+		if (!node || node.isExpired) return null;
+		return {
+			data: node.value,
+			expiresAt: node.expiresAt,
+			staleAt: node.staleAt
+		};
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async get(key) {
+		const parsedKey = this.parseKey(key);
+		this.log("fetching", parsedKey);
+		const node = this.cache.get(parsedKey);
+		if (!node) {
+			this.log("notFound", parsedKey);
+			await this.emit("miss", { key: parsedKey });
+			return null;
+		}
+		if (node.isExpired) {
+			this.removeNode(node);
+			this.cache.delete(parsedKey);
+			this.log("expired", parsedKey);
+			await this.emit("expired", { key: parsedKey });
+			await this.emit("miss", { key: parsedKey });
+			return null;
+		}
+		this.moveHead(node);
+		this.log("fetched", parsedKey);
+		const value = node.value;
+		if (value === null || value === void 0) return value;
+		const type = typeof value;
+		if (type === "string" || type === "number" || type === "boolean") {
+			await this.emit("hit", {
+				key: parsedKey,
+				value
+			});
+			return value;
+		}
+		try {
+			const clonedValue = structuredClone(value);
+			await this.emit("hit", {
+				key: parsedKey,
+				value: clonedValue
+			});
+			return clonedValue;
+		} catch (error) {
+			this.logError(`Failed to clone cached value for ${parsedKey}`, error);
+			throw error;
+		}
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async remove(key) {
+		const parsedKey = this.parseKey(key);
+		this.log("removing", parsedKey);
+		const node = this.cache.get(parsedKey);
+		if (node) {
+			this.removeNode(node);
+			this.cache.delete(parsedKey);
+		}
+		this.log("removed", parsedKey);
+		await this.emit("removed", { key: parsedKey });
+	}
+	/**
+	* {@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.
+	*/
+	async flush() {
+		this.log("flushing");
+		if (this.options.globalPrefix) await this.removeNamespace("");
+		else {
+			this.cache.clear();
+			this.init();
+		}
+		this.log("flushed");
+		await this.emit("flushed");
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Brute-force O(N) cosine similarity over every cached node that carries a
+	* vector. Suitable for development and small in-memory knowledge bases —
+	* not for production beyond ~10k entries.
+	*
+	* @warning Dev-only — O(N) per query.
+	*/
+	async similar(vector, options) {
+		const tagFilter = await this.getKeysForTags(options.tags);
+		const hits = [];
+		for (const [parsedKey, node] of this.cache) {
+			if (!node.vector) continue;
+			if (node.isExpired) continue;
+			if (tagFilter && !tagFilter.has(parsedKey)) continue;
+			const score = cosineSimilarity(vector, node.vector);
+			if (options.threshold !== void 0 && score < options.threshold) continue;
+			let value = node.value;
+			if (value !== null && value !== void 0) {
+				const t = typeof value;
+				if (t !== "string" && t !== "number" && t !== "boolean") value = structuredClone(value);
+			}
+			hits.push({
+				key: parsedKey,
+				value,
+				score
+			});
+		}
+		hits.sort((a, b) => b.score - a.score);
+		if (options.topK >= 0 && hits.length > options.topK) hits.length = options.topK;
+		return hits;
+	}
+	/**
+	* Get lru capacity
+	*/
+	get capacity() {
+		return this.options.capacity || 1e3;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async disconnect() {
+		if (this.cleanupInterval) {
+			clearInterval(this.cleanupInterval);
+			this.cleanupInterval = void 0;
+		}
+		await super.disconnect();
+	}
+};
+
+//#endregion
+export { LRUMemoryCacheDriver };
+//# sourceMappingURL=lru-memory-cache-driver.mjs.map