@warlock.js/cache 4.0.171 → 4.1.1

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

@@ -0,0 +1,312 @@
+import { CacheConfigurationError, CacheUnsupportedError } from "../types.mjs";
+import { BaseCacheDriver } from "./base-cache-driver.mjs";
+import { log } from "@warlock.js/logger";
+
+//#region ../../@warlock.js/cache/src/drivers/redis-cache-driver.ts
+/**
+* Cached Redis module (loaded once, reused)
+*/
+let RedisClient;
+let isModuleExists = null;
+/**
+* Installation instructions for Redis package
+*/
+const REDIS_INSTALL_INSTRUCTIONS = `
+Redis cache driver requires the redis package.
+Install it with:
+
+  npm install redis
+
+Or with your preferred package manager:
+
+  pnpm add redis
+  yarn add redis
+`.trim();
+/**
+* Load Redis module
+*/
+async function loadRedis() {
+	try {
+		RedisClient = await import("redis");
+		isModuleExists = true;
+	} catch {
+		isModuleExists = false;
+	}
+}
+loadRedis();
+var RedisCacheDriver = class extends BaseCacheDriver {
+	constructor(..._args) {
+		super(..._args);
+		this.name = "redis";
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	setOptions(options) {
+		if (!options.url && !options.host) throw new CacheConfigurationError("Redis driver requires either 'url' or 'host' option to be configured.");
+		return super.setOptions(options);
+	}
+	/**
+	* {@inheritDoc}
+	*/
+	async removeNamespace(namespace) {
+		namespace = this.parseKey(namespace);
+		this.log("clearing", namespace);
+		const keys = await this.client?.keys(`${namespace}*`);
+		if (!keys || keys.length === 0) {
+			this.log("notFound", namespace);
+			return;
+		}
+		await this.client?.del(keys);
+		this.log("cleared", namespace);
+		return keys;
+	}
+	/**
+	* {@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("'redis' driver does not yet support similarity retrieval. Phase 2 (RediSearch) is on the backlog — use a memory driver or the 'pg' driver (with pgvector) for now.");
+		this.log("caching", parsedKey);
+		const serialized = JSON.stringify(value);
+		const hasExpiry = Boolean(ttl) && ttl !== Infinity;
+		let reply;
+		if (onConflict === "create") {
+			const options = { NX: true };
+			if (hasExpiry) options.EX = ttl;
+			reply = await this.client?.set(parsedKey, serialized, options);
+		} else if (onConflict === "update") {
+			const options = { XX: true };
+			if (hasExpiry) options.EX = ttl;
+			reply = await this.client?.set(parsedKey, serialized, options);
+		} else if (hasExpiry) reply = await this.client?.set(parsedKey, serialized, { EX: ttl });
+		else reply = await this.client?.set(parsedKey, serialized);
+		if ((onConflict === "create" || onConflict === "update") && !(reply === "OK")) return {
+			wasSet: false,
+			existing: onConflict === "create" ? await this.get(key) : null
+		};
+		if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+		if (staleAt !== void 0) {
+			const sidecarOptions = {};
+			if (hasExpiry) sidecarOptions.EX = ttl;
+			await this.client?.set(this.swrMetaKey(parsedKey), String(staleAt), sidecarOptions);
+		}
+		this.log("cached", parsedKey);
+		await this.emit("set", {
+			key: parsedKey,
+			value,
+			ttl
+		});
+		if (onConflict === "create" || onConflict === "update") return {
+			wasSet: true,
+			existing: null
+		};
+		return value;
+	}
+	/**
+	* Build the sidecar key Redis uses to track SWR freshness without
+	* wrapping the main value JSON.
+	*/
+	swrMetaKey(parsedKey) {
+		return `__swrmeta:${parsedKey}`;
+	}
+	/**
+	* Read the raw {@link CacheData} wrapper, fetching the value and the
+	* SWR sidecar in parallel. Returns `null` when the main key is missing
+	* or expired (Redis handles expiry natively, so the absence of the
+	* value alone tells us).
+	*/
+	async getEntry(key) {
+		const parsedKey = this.parseKey(key);
+		const [valueRaw, staleAtRaw] = await Promise.all([this.client?.get(parsedKey), this.client?.get(this.swrMetaKey(parsedKey))]);
+		if (!valueRaw) return null;
+		const data = JSON.parse(valueRaw);
+		const staleAt = staleAtRaw ? Number(staleAtRaw) : void 0;
+		return staleAt !== void 0 ? {
+			data,
+			staleAt
+		} : { data };
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Redis tracks expiry natively (the payload carries no `expiresAt`), so read
+	* the remaining lifetime with the `TTL` command. Redis returns `-2` for a
+	* missing key and `-1` for a key with no expiry.
+	*/
+	async getRemainingTtl(key) {
+		const parsedKey = this.parseKey(key);
+		const ttl = await this.client?.ttl(parsedKey);
+		if (ttl === void 0 || ttl === -2) return;
+		if (ttl === -1) return Infinity;
+		return ttl;
+	}
+	/**
+	* {@inheritDoc}
+	*/
+	async get(key) {
+		key = this.parseKey(key);
+		this.log("fetching", key);
+		const value = await this.client?.get(key);
+		if (!value) {
+			this.log("notFound", key);
+			await this.emit("miss", { key });
+			return null;
+		}
+		this.log("fetched", key);
+		const parsedValue = JSON.parse(value);
+		if (parsedValue === null || parsedValue === void 0) {
+			await this.emit("hit", {
+				key,
+				value: parsedValue
+			});
+			return parsedValue;
+		}
+		const type = typeof parsedValue;
+		if (type === "string" || type === "number" || type === "boolean") {
+			await this.emit("hit", {
+				key,
+				value: parsedValue
+			});
+			return parsedValue;
+		}
+		try {
+			const clonedValue = structuredClone(parsedValue);
+			await this.emit("hit", {
+				key,
+				value: clonedValue
+			});
+			return clonedValue;
+		} catch (error) {
+			this.logError(`Failed to clone cached value for ${key}`, error);
+			throw error;
+		}
+	}
+	/**
+	* {@inheritDoc}
+	*/
+	async remove(key) {
+		key = this.parseKey(key);
+		this.log("removing", key);
+		await this.client?.del([key, this.swrMetaKey(key)]);
+		this.log("removed", key);
+		await this.emit("removed", { key });
+	}
+	/**
+	* {@inheritDoc}
+	*/
+	async flush() {
+		this.log("flushing");
+		if (this.options.globalPrefix) await this.removeNamespace("");
+		else await this.client?.flushAll();
+		this.log("flushed");
+		await this.emit("flushed");
+	}
+	/**
+	* {@inheritDoc}
+	*/
+	async connect() {
+		if (this.clientDriver) return;
+		if (!isModuleExists) throw new Error(REDIS_INSTALL_INSTRUCTIONS);
+		const options = this.options;
+		if (options && !options.url && options.host) {
+			const auth = options.password || options.username ? `${options.username}:${options.password}@` : "";
+			if (!options.url) options.url = `redis://${auth}${options.host || "localhost"}:${options.port || 6379}`;
+		}
+		const clientOptions = {
+			...options,
+			...this.options.clientOptions || {}
+		};
+		this.log("connecting");
+		const { createClient } = RedisClient;
+		this.client = createClient(clientOptions);
+		this.client.on("error", (error) => {
+			this.log("error", error.message);
+		});
+		try {
+			await this.client.connect();
+			this.log("connected");
+			await this.emit("connected");
+		} catch (error) {
+			log.error("cache", "redis", error);
+			await this.emit("error", { error });
+		}
+	}
+	/**
+	* {@inheritDoc}
+	*
+	* Guards against disconnecting when the client was never created. The base
+	* `client` getter falls back to `this` when no client is set, so we check
+	* the backing `clientDriver` directly — using `this.client` for this guard
+	* would always be truthy and crash with "this.quit is not a function".
+	*/
+	async disconnect() {
+		if (!this.clientDriver) return;
+		this.log("disconnecting");
+		await this.clientDriver.quit();
+		this.log("disconnected");
+		await this.emit("disconnected");
+	}
+	/**
+	* Atomic increment using Redis native INCRBY command
+	* {@inheritdoc}
+	*/
+	async increment(key, value = 1) {
+		const parsedKey = this.parseKey(key);
+		this.log("caching", parsedKey);
+		const result = await this.client?.incrBy(parsedKey, value);
+		this.log("cached", parsedKey);
+		await this.emit("set", {
+			key: parsedKey,
+			value: result,
+			ttl: void 0
+		});
+		return result || 0;
+	}
+	/**
+	* Atomic decrement using Redis native DECRBY command
+	* {@inheritdoc}
+	*/
+	async decrement(key, value = 1) {
+		const parsedKey = this.parseKey(key);
+		this.log("caching", parsedKey);
+		const result = await this.client?.decrBy(parsedKey, value);
+		this.log("cached", parsedKey);
+		await this.emit("set", {
+			key: parsedKey,
+			value: result,
+			ttl: void 0
+		});
+		return result || 0;
+	}
+	/**
+	* Set if not exists (atomic operation)
+	* Returns true if key was set, false if key already existed
+	*/
+	async setNX(key, value, ttl) {
+		const parsedKey = this.parseKey(key);
+		this.log("caching", parsedKey);
+		if (ttl === void 0) ttl = this.ttl;
+		let result;
+		if (ttl && ttl !== Infinity) result = await this.client?.set(parsedKey, JSON.stringify(value), {
+			NX: true,
+			EX: ttl
+		});
+		else result = await this.client?.set(parsedKey, JSON.stringify(value), { NX: true });
+		const wasSet = result === "OK";
+		if (wasSet) {
+			this.log("cached", parsedKey);
+			await this.emit("set", {
+				key: parsedKey,
+				value,
+				ttl
+			});
+		} else this.log("notFound", parsedKey);
+		return wasSet;
+	}
+};
+
+//#endregion
+export { RedisCacheDriver };
+//# sourceMappingURL=redis-cache-driver.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache-driver.mjs","names":[],"sources":["../../../../../../@warlock.js/cache/src/drivers/redis-cache-driver.ts"],"sourcesContent":["import { log } from \"@warlock.js/logger\";\r\nimport type { createClient } from \"redis\";\r\nimport type {\r\n  CacheData,\r\n  CacheDriver,\r\n  CacheKey,\r\n  CacheSetOptions,\r\n  CacheSetResult,\r\n  CacheTtl,\r\n  RedisOptions,\r\n} from \"../types\";\r\nimport { CacheConfigurationError, CacheUnsupportedError } from \"../types\";\r\nimport { BaseCacheDriver } from \"./base-cache-driver\";\r\n\r\n// ============================================================\r\n// Lazy-loaded Redis SDK Types\r\n// ============================================================\r\n\r\n/**\r\n * Cached Redis module (loaded once, reused)\r\n */\r\nlet RedisClient: typeof import(\"redis\");\r\n\r\nlet isModuleExists: boolean | null = null;\r\n\r\n/**\r\n * Installation instructions for Redis package\r\n */\r\nconst REDIS_INSTALL_INSTRUCTIONS = `\r\nRedis cache driver requires the redis package.\r\nInstall it with:\r\n\r\n  npm install redis\r\n\r\nOr with your preferred package manager:\r\n\r\n  pnpm add redis\r\n  yarn add redis\r\n`.trim();\r\n\r\n/**\r\n * Load Redis module\r\n */\r\nasync function loadRedis() {\r\n  try {\r\n    RedisClient = await import(\"redis\");\r\n    isModuleExists = true;\r\n  } catch {\r\n    isModuleExists = false;\r\n  }\r\n}\r\n\r\nloadRedis();\r\n\r\n// ============================================================\r\n// RedisCacheDriver Class\r\n// ============================================================\r\n\r\nexport class RedisCacheDriver\r\n  extends BaseCacheDriver<ReturnType<typeof createClient>, RedisOptions>\r\n  implements CacheDriver<ReturnType<typeof createClient>, RedisOptions>\r\n{\r\n  /**\r\n   * Cache driver name\r\n   */\r\n  public name = \"redis\";\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public setOptions(options: RedisOptions) {\r\n    if (!options.url && !options.host) {\r\n      throw new CacheConfigurationError(\r\n        \"Redis driver requires either 'url' or 'host' option to be configured.\",\r\n      );\r\n    }\r\n\r\n    return super.setOptions(options);\r\n  }\r\n\r\n  /**\r\n   * {@inheritDoc}\r\n   */\r\n  public async removeNamespace(namespace: string) {\r\n    namespace = this.parseKey(namespace);\r\n\r\n    this.log(\"clearing\", namespace);\r\n\r\n    const keys = await this.client?.keys(`${namespace}*`);\r\n\r\n    if (!keys || keys.length === 0) {\r\n      this.log(\"notFound\", namespace);\r\n      return;\r\n    }\r\n\r\n    await this.client?.del(keys);\r\n\r\n    this.log(\"cleared\", namespace);\r\n\r\n    return keys;\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        \"'redis' driver does not yet support similarity retrieval. Phase 2 (RediSearch) is on the backlog — use a memory driver or the 'pg' driver (with pgvector) for now.\",\r\n      );\r\n    }\r\n\r\n    this.log(\"caching\", parsedKey);\r\n\r\n    const serialized = JSON.stringify(value);\r\n    const hasExpiry = Boolean(ttl) && ttl !== Infinity;\r\n\r\n    let reply: string | null | undefined;\r\n\r\n    if (onConflict === \"create\") {\r\n      const options: { NX: true; EX?: number } = { NX: true };\r\n      if (hasExpiry) {\r\n        options.EX = ttl as number;\r\n      }\r\n      reply = await this.client?.set(parsedKey, serialized, options);\r\n    } else if (onConflict === \"update\") {\r\n      const options: { XX: true; EX?: number } = { XX: true };\r\n      if (hasExpiry) {\r\n        options.EX = ttl as number;\r\n      }\r\n      reply = await this.client?.set(parsedKey, serialized, options);\r\n    } else if (hasExpiry) {\r\n      reply = await this.client?.set(parsedKey, serialized, { EX: ttl as number });\r\n    } else {\r\n      reply = await this.client?.set(parsedKey, serialized);\r\n    }\r\n\r\n    const wasSet = reply === \"OK\";\r\n\r\n    if ((onConflict === \"create\" || onConflict === \"update\") && !wasSet) {\r\n      const existing = onConflict === \"create\" ? ((await this.get(key)) as any) : null;\r\n      return { wasSet: false, existing } satisfies CacheSetResult;\r\n    }\r\n\r\n    if (tags && tags.length > 0) {\r\n      await this.applyTags(parsedKey, tags);\r\n    }\r\n\r\n    if (staleAt !== undefined) {\r\n      // Sidecar key for SWR freshness — keeps the main value JSON\r\n      // backwards-compatible with entries written before SWR landed.\r\n      const sidecarOptions: { EX?: number } = {};\r\n\r\n      if (hasExpiry) {\r\n        sidecarOptions.EX = ttl as number;\r\n      }\r\n\r\n      await this.client?.set(this.swrMetaKey(parsedKey), String(staleAt), sidecarOptions);\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      return { wasSet: true, existing: null } satisfies CacheSetResult;\r\n    }\r\n\r\n    return value;\r\n  }\r\n\r\n  /**\r\n   * Build the sidecar key Redis uses to track SWR freshness without\r\n   * wrapping the main value JSON.\r\n   */\r\n  protected swrMetaKey(parsedKey: string): string {\r\n    return `__swrmeta:${parsedKey}`;\r\n  }\r\n\r\n  /**\r\n   * Read the raw {@link CacheData} wrapper, fetching the value and the\r\n   * SWR sidecar in parallel. Returns `null` when the main key is missing\r\n   * or expired (Redis handles expiry natively, so the absence of the\r\n   * value alone tells us).\r\n   */\r\n  protected async getEntry(key: CacheKey): Promise<CacheData | null> {\r\n    const parsedKey = this.parseKey(key);\r\n\r\n    const [valueRaw, staleAtRaw] = await Promise.all([\r\n      this.client?.get(parsedKey),\r\n      this.client?.get(this.swrMetaKey(parsedKey)),\r\n    ]);\r\n\r\n    if (!valueRaw) {\r\n      return null;\r\n    }\r\n\r\n    const data = JSON.parse(valueRaw);\r\n    const staleAt = staleAtRaw ? Number(staleAtRaw) : undefined;\r\n\r\n    return staleAt !== undefined ? { data, staleAt } : { data };\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   *\r\n   * Redis tracks expiry natively (the payload carries no `expiresAt`), so read\r\n   * the remaining lifetime with the `TTL` command. Redis returns `-2` for a\r\n   * missing key and `-1` for a key with no expiry.\r\n   */\r\n  protected async getRemainingTtl(key: CacheKey): Promise<number | undefined> {\r\n    const parsedKey = this.parseKey(key);\r\n    const ttl = await this.client?.ttl(parsedKey);\r\n\r\n    if (ttl === undefined || ttl === -2) {\r\n      return undefined;\r\n    }\r\n\r\n    if (ttl === -1) {\r\n      return Infinity;\r\n    }\r\n\r\n    return ttl;\r\n  }\r\n\r\n  /**\r\n   * {@inheritDoc}\r\n   */\r\n  public async get(key: CacheKey) {\r\n    key = this.parseKey(key);\r\n\r\n    this.log(\"fetching\", key);\r\n\r\n    const value = await this.client?.get(key);\r\n\r\n    if (!value) {\r\n      this.log(\"notFound\", key);\r\n      // Emit miss event\r\n      await this.emit(\"miss\", { key });\r\n      return null;\r\n    }\r\n\r\n    this.log(\"fetched\", key);\r\n\r\n    // Parse and return the value directly (Redis handles expiration natively)\r\n    const parsedValue = JSON.parse(value);\r\n\r\n    // Apply cloning for immutability protection\r\n    if (parsedValue === null || parsedValue === undefined) {\r\n      // Emit hit event\r\n      await this.emit(\"hit\", { key, value: parsedValue });\r\n      return parsedValue;\r\n    }\r\n\r\n    const type = typeof parsedValue;\r\n    if (type === \"string\" || type === \"number\" || type === \"boolean\") {\r\n      // Emit hit event\r\n      await this.emit(\"hit\", { key, value: parsedValue });\r\n      return parsedValue;\r\n    }\r\n\r\n    try {\r\n      const clonedValue = structuredClone(parsedValue);\r\n      // Emit hit event\r\n      await this.emit(\"hit\", { key, value: clonedValue });\r\n      return clonedValue;\r\n    } catch (error) {\r\n      this.logError(`Failed to clone cached value for ${key}`, error);\r\n      throw error;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * {@inheritDoc}\r\n   */\r\n  public async remove(key: CacheKey) {\r\n    key = this.parseKey(key);\r\n\r\n    this.log(\"removing\", key);\r\n\r\n    // Drop the SWR sidecar alongside the main key — keeps metadata from\r\n    // surviving a `remove` and confusing a later `swr` read.\r\n    await this.client?.del([key, this.swrMetaKey(key)]);\r\n\r\n    this.log(\"removed\", key);\r\n\r\n    await this.emit(\"removed\", { key });\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 this.client?.flushAll();\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    if (this.clientDriver) return;\r\n\r\n    if (!isModuleExists) {\r\n      throw new Error(REDIS_INSTALL_INSTRUCTIONS);\r\n    }\r\n\r\n    const options = this.options;\r\n\r\n    if (options && !options.url && options.host) {\r\n      const auth =\r\n        options.password || options.username ? `${options.username}:${options.password}@` : \"\";\r\n\r\n      if (!options.url) {\r\n        const host = options.host || \"localhost\";\r\n        const port = options.port || 6379;\r\n        options.url = `redis://${auth}${host}:${port}`;\r\n      }\r\n    }\r\n\r\n    const clientOptions = {\r\n      ...options,\r\n      ...(this.options.clientOptions || {}),\r\n    };\r\n\r\n    this.log(\"connecting\");\r\n    const { createClient } = RedisClient;\r\n\r\n    this.client = createClient(clientOptions);\r\n\r\n    this.client.on(\"error\", (error: Error) => {\r\n      this.log(\"error\", error.message);\r\n    });\r\n    try {\r\n      await this.client.connect();\r\n\r\n      this.log(\"connected\");\r\n      await this.emit(\"connected\");\r\n    } catch (error) {\r\n      log.error(\"cache\", \"redis\", error);\r\n      await this.emit(\"error\", { error });\r\n    }\r\n  }\r\n\r\n  /**\r\n   * {@inheritDoc}\r\n   *\r\n   * Guards against disconnecting when the client was never created. The base\r\n   * `client` getter falls back to `this` when no client is set, so we check\r\n   * the backing `clientDriver` directly — using `this.client` for this guard\r\n   * would always be truthy and crash with \"this.quit is not a function\".\r\n   */\r\n  public async disconnect() {\r\n    if (!this.clientDriver) {\r\n      return;\r\n    }\r\n\r\n    this.log(\"disconnecting\");\r\n\r\n    await this.clientDriver.quit();\r\n\r\n    this.log(\"disconnected\");\r\n    await this.emit(\"disconnected\");\r\n  }\r\n\r\n  /**\r\n   * Atomic increment using Redis native INCRBY command\r\n   * {@inheritdoc}\r\n   */\r\n  public async increment(key: CacheKey, value: number = 1): Promise<number> {\r\n    const parsedKey = this.parseKey(key);\r\n\r\n    this.log(\"caching\", parsedKey);\r\n\r\n    const result = await this.client?.incrBy(parsedKey, value);\r\n\r\n    this.log(\"cached\", parsedKey);\r\n\r\n    // Emit set event\r\n    await this.emit(\"set\", { key: parsedKey, value: result, ttl: undefined });\r\n\r\n    return result || 0;\r\n  }\r\n\r\n  /**\r\n   * Atomic decrement using Redis native DECRBY command\r\n   * {@inheritdoc}\r\n   */\r\n  public async decrement(key: CacheKey, value: number = 1): Promise<number> {\r\n    const parsedKey = this.parseKey(key);\r\n\r\n    this.log(\"caching\", parsedKey);\r\n\r\n    const result = await this.client?.decrBy(parsedKey, value);\r\n\r\n    this.log(\"cached\", parsedKey);\r\n\r\n    // Emit set event\r\n    await this.emit(\"set\", { key: parsedKey, value: result, ttl: undefined });\r\n\r\n    return result || 0;\r\n  }\r\n\r\n  /**\r\n   * Set if not exists (atomic operation)\r\n   * Returns true if key was set, false if key already existed\r\n   */\r\n  public async setNX(key: CacheKey, value: any, ttl?: number): Promise<boolean> {\r\n    const parsedKey = this.parseKey(key);\r\n\r\n    this.log(\"caching\", parsedKey);\r\n\r\n    if (ttl === undefined) {\r\n      ttl = this.ttl;\r\n    }\r\n\r\n    let result: string | null;\r\n\r\n    // Use Redis native SET with NX option\r\n    if (ttl && ttl !== Infinity) {\r\n      result = await this.client?.set(parsedKey, JSON.stringify(value), {\r\n        NX: true,\r\n        EX: ttl,\r\n      });\r\n    } else {\r\n      result = await this.client?.set(parsedKey, JSON.stringify(value), {\r\n        NX: true,\r\n      });\r\n    }\r\n\r\n    const wasSet = result === \"OK\";\r\n\r\n    if (wasSet) {\r\n      this.log(\"cached\", parsedKey);\r\n      // Emit set event\r\n      await this.emit(\"set\", { key: parsedKey, value, ttl });\r\n    } else {\r\n      this.log(\"notFound\", parsedKey);\r\n    }\r\n\r\n    return wasSet;\r\n  }\r\n}\r\n"],"mappings":"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"}

package/esm/index.d.mts

@@ -0,0 +1,21 @@
+import { BaseCacheDriver, NormalizedSetOptions } from "./drivers/base-cache-driver.mjs";
+import { FileCacheDriver } from "./drivers/file-cache-driver.mjs";
+import { LRUMemoryCacheDriver } from "./drivers/lru-memory-cache-driver.mjs";
+import { MemoryCacheDriver } from "./drivers/memory-cache-driver.mjs";
+import { MemoryExtendedCacheDriver } from "./drivers/memory-extended-cache-driver.mjs";
+import { MockCacheDriver } from "./drivers/mock-cache-driver.mjs";
+import { NullCacheDriver } from "./drivers/null-cache-driver.mjs";
+import { PgCacheDriver } from "./drivers/pg-cache-driver.mjs";
+import { RedisCacheDriver } from "./drivers/redis-cache-driver.mjs";
+import { CacheCall, CacheConcurrencyError, CacheConfigurationError, CacheConfigurations, CacheConflictPolicy, CacheConnectionError, CacheData, CacheDriver, CacheDriverNotInitializedError, CacheError, CacheEventData, CacheEventHandler, CacheEventType, CacheKey, CacheListAccessor, CacheMetricsSnapshot, CacheNamespaceOptions, CacheOperationType, CacheSetOptions, CacheSetResult, CacheSimilarHit, CacheSimilarOptions, CacheSwrOptions, CacheTtl, CacheUnsupportedError, DriverClass, FileCacheOptions, LRUMemoryCacheOptions, LockOptions, LockOutcome, MemoryCacheOptions, MemoryExtendedCacheOptions, MockCacheOptions, NullCacheDriverOptions, PgCacheOptions, PgClientLike, RedisOptions, RememberOptions, ScopedCacheContract, TaggedCacheDriver, TaggedScopedCacheContract } from "./types.mjs";
+import { CacheMetricsCollector } from "./metrics.mjs";
+import { CacheManager, cache } from "./cache-manager.mjs";
+import { deriveAutoKey } from "./cached/auto-key.mjs";
+import { CachedOptions, NormalizedCachedConfig, normalizeCachedArgs } from "./cached/normalize-args.mjs";
+import { CachedFn, cached } from "./cached/cached.mjs";
+import { MemoryCacheList } from "./list/memory-cache-list.mjs";
+import { ScopedCache } from "./scoped-cache.mjs";
+import { TaggedCache } from "./tagged-cache.mjs";
+import { TaggedScopedCache } from "./tagged-scoped-cache.mjs";
+import { CACHE_FOR, cosineSimilarity, expiresAtToTtl, injectTags, mergeTagSets, normalizeToOptions, normalizeToRememberOptions, parseCacheKey, parseTtl, resolveTtl } from "./utils.mjs";
+export { BaseCacheDriver, CACHE_FOR, CacheCall, CacheConcurrencyError, CacheConfigurationError, CacheConfigurations, CacheConflictPolicy, CacheConnectionError, CacheData, CacheDriver, CacheDriverNotInitializedError, CacheError, CacheEventData, CacheEventHandler, CacheEventType, CacheKey, CacheListAccessor, CacheManager, CacheMetricsCollector, CacheMetricsSnapshot, CacheNamespaceOptions, CacheOperationType, CacheSetOptions, CacheSetResult, CacheSimilarHit, CacheSimilarOptions, CacheSwrOptions, CacheTtl, CacheUnsupportedError, CachedFn, CachedOptions, DriverClass, FileCacheDriver, FileCacheOptions, LRUMemoryCacheDriver, LRUMemoryCacheOptions, LockOptions, LockOutcome, MemoryCacheDriver, MemoryCacheList, MemoryCacheOptions, MemoryExtendedCacheDriver, MemoryExtendedCacheOptions, MockCacheDriver, MockCacheOptions, NormalizedCachedConfig, NormalizedSetOptions, NullCacheDriver, NullCacheDriverOptions, PgCacheDriver, PgCacheOptions, PgClientLike, RedisCacheDriver, RedisOptions, RememberOptions, ScopedCache, ScopedCacheContract, TaggedCache, TaggedCacheDriver, TaggedScopedCache, TaggedScopedCacheContract, cache, cached, cosineSimilarity, deriveAutoKey, expiresAtToTtl, injectTags, mergeTagSets, normalizeCachedArgs, normalizeToOptions, normalizeToRememberOptions, parseCacheKey, parseTtl, resolveTtl };

package/esm/index.mjs

@@ -0,0 +1,24 @@
+import { CacheMetricsCollector } from "./metrics.mjs";
+import { CacheConcurrencyError, CacheConfigurationError, CacheConnectionError, CacheDriverNotInitializedError, CacheError, CacheUnsupportedError } from "./types.mjs";
+import { CACHE_FOR, cosineSimilarity, expiresAtToTtl, injectTags, mergeTagSets, normalizeToOptions, normalizeToRememberOptions, parseCacheKey, parseTtl, resolveTtl } from "./utils.mjs";
+import { TaggedScopedCache } from "./tagged-scoped-cache.mjs";
+import { ScopedCache } from "./scoped-cache.mjs";
+import { CacheManager, cache } from "./cache-manager.mjs";
+import { deriveAutoKey } from "./cached/auto-key.mjs";
+import { normalizeCachedArgs } from "./cached/normalize-args.mjs";
+import { cached } from "./cached/cached.mjs";
+import "./cached/index.mjs";
+import { MemoryCacheList } from "./list/memory-cache-list.mjs";
+import { TaggedCache } from "./tagged-cache.mjs";
+import { BaseCacheDriver } from "./drivers/base-cache-driver.mjs";
+import { FileCacheDriver } from "./drivers/file-cache-driver.mjs";
+import { LRUMemoryCacheDriver } from "./drivers/lru-memory-cache-driver.mjs";
+import { MemoryCacheDriver } from "./drivers/memory-cache-driver.mjs";
+import { MemoryExtendedCacheDriver } from "./drivers/memory-extended-cache-driver.mjs";
+import { MockCacheDriver } from "./drivers/mock-cache-driver.mjs";
+import { NullCacheDriver } from "./drivers/null-cache-driver.mjs";
+import { PgCacheDriver } from "./drivers/pg-cache-driver.mjs";
+import { RedisCacheDriver } from "./drivers/redis-cache-driver.mjs";
+import "./drivers/index.mjs";
+
+export { BaseCacheDriver, CACHE_FOR, CacheConcurrencyError, CacheConfigurationError, CacheConnectionError, CacheDriverNotInitializedError, CacheError, CacheManager, CacheMetricsCollector, CacheUnsupportedError, FileCacheDriver, LRUMemoryCacheDriver, MemoryCacheDriver, MemoryCacheList, MemoryExtendedCacheDriver, MockCacheDriver, NullCacheDriver, PgCacheDriver, RedisCacheDriver, ScopedCache, TaggedCache, TaggedScopedCache, cache, cached, cosineSimilarity, deriveAutoKey, expiresAtToTtl, injectTags, mergeTagSets, normalizeCachedArgs, normalizeToOptions, normalizeToRememberOptions, parseCacheKey, parseTtl, resolveTtl };

package/esm/list/index.d.mts

@@ -0,0 +1 @@
+import { MemoryCacheList } from "./memory-cache-list.mjs";

package/esm/list/memory-cache-list.d.mts

@@ -0,0 +1,77 @@
+import { CacheDriver, CacheKey, CacheListAccessor } from "../types.mjs";
+
+//#region ../../@warlock.js/cache/src/list/memory-cache-list.d.ts
+/**
+ * Generic array-backed {@link CacheListAccessor}.
+ *
+ * Stores the full list as a single cache entry and performs read-mutate-write
+ * for every operation. Correct for any driver, but O(n) per op. The Redis
+ * driver overrides `list()` to return a native-command accessor instead.
+ *
+ * **Role.** Fallback list accessor bound to a driver + key. Every mutation
+ * fetches the array, transforms it in memory, and writes it back.
+ *
+ * **Responsibility.**
+ * - Owns: translating list operations into array mutations + driver writes.
+ * - Does NOT own: concurrency control (callers should wrap in a distributed
+ *   lock when multi-process writers are possible), TTL preservation across
+ *   ops (writes use driver defaults), or tagging of list entries.
+ *
+ * @example
+ * // Never constructed directly — obtained via driver.list():
+ * const list = cache.list<Event>("recent-events");
+ * await list.push(event);
+ */
+declare class MemoryCacheList<T> implements CacheListAccessor<T> {
+  private readonly driver;
+  private readonly key;
+  constructor(driver: CacheDriver<any, any>, key: CacheKey);
+  /**
+   * Read the backing array from the driver. Returns an empty array on miss.
+   */
+  private read;
+  /**
+   * Persist the backing array. Removes the entry when empty to keep the
+   * store clean.
+   */
+  private write;
+  /**
+   * {@inheritdoc}
+   */
+  push(...items: T[]): Promise<number>;
+  /**
+   * {@inheritdoc}
+   */
+  unshift(...items: T[]): Promise<number>;
+  /**
+   * {@inheritdoc}
+   */
+  pop(): Promise<T | null>;
+  /**
+   * {@inheritdoc}
+   */
+  shift(): Promise<T | null>;
+  /**
+   * {@inheritdoc}
+   */
+  slice(start?: number, end?: number): Promise<T[]>;
+  /**
+   * {@inheritdoc}
+   */
+  all(): Promise<T[]>;
+  /**
+   * {@inheritdoc}
+   */
+  length(): Promise<number>;
+  /**
+   * {@inheritdoc}
+   */
+  trim(start: number, end: number): Promise<void>;
+  /**
+   * {@inheritdoc}
+   */
+  clear(): Promise<void>;
+}
+//#endregion
+export { MemoryCacheList };
+//# sourceMappingURL=memory-cache-list.d.mts.map

package/esm/list/memory-cache-list.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-cache-list.d.mts","names":[],"sources":["../../../../../../@warlock.js/cache/src/list/memory-cache-list.ts"],"mappings":";;;;;AAuBA;;;;;;;;;;;;;;;;;;;cAAa,eAAA,eAA8B,iBAAA,CAAkB,CAAA;EAAA,iBAExC,MAAA;EAAA,iBACA,GAAA;cADA,MAAA,EAAQ,WAAA,YACR,GAAA,EAAK,QAAA;EAHkC;;;EAAA,QAS5C,IAAA;EAPK;;;;EAAA,QAgBL,KAAA;EAfU;;;EA2BX,IAAA,CAAA,GAAQ,KAAA,EAAO,CAAA,KAAM,OAAA;EAArB;;;EAWA,OAAA,CAAA,GAAW,KAAA,EAAO,CAAA,KAAM,OAAA;EAAxB;;;EAWA,GAAA,CAAA,GAAO,OAAA,CAAQ,CAAA;EAAf;;;EAgBA,KAAA,CAAA,GAAS,OAAA,CAAQ,CAAA;EAAR;;;EAgBT,KAAA,CAAM,KAAA,WAAgB,GAAA,YAAe,OAAA,CAAQ,CAAA;EAAvB;;;EAQtB,GAAA,CAAA,GAAO,OAAA,CAAQ,CAAA;EAAR;;;EAOP,MAAA,CAAA,GAAU,OAAA;EAQV;;;EAAA,IAAA,CAAK,KAAA,UAAe,GAAA,WAAc,OAAA;EASlC;;;EAAA,KAAA,CAAA,GAAS,OAAA;AAAA"}

package/esm/list/memory-cache-list.mjs

@@ -0,0 +1,119 @@
+//#region ../../@warlock.js/cache/src/list/memory-cache-list.ts
+/**
+* Generic array-backed {@link CacheListAccessor}.
+*
+* Stores the full list as a single cache entry and performs read-mutate-write
+* for every operation. Correct for any driver, but O(n) per op. The Redis
+* driver overrides `list()` to return a native-command accessor instead.
+*
+* **Role.** Fallback list accessor bound to a driver + key. Every mutation
+* fetches the array, transforms it in memory, and writes it back.
+*
+* **Responsibility.**
+* - Owns: translating list operations into array mutations + driver writes.
+* - Does NOT own: concurrency control (callers should wrap in a distributed
+*   lock when multi-process writers are possible), TTL preservation across
+*   ops (writes use driver defaults), or tagging of list entries.
+*
+* @example
+* // Never constructed directly — obtained via driver.list():
+* const list = cache.list<Event>("recent-events");
+* await list.push(event);
+*/
+var MemoryCacheList = class {
+	constructor(driver, key) {
+		this.driver = driver;
+		this.key = key;
+	}
+	/**
+	* Read the backing array from the driver. Returns an empty array on miss.
+	*/
+	async read() {
+		const current = await this.driver.get(this.key);
+		return Array.isArray(current) ? [...current] : [];
+	}
+	/**
+	* Persist the backing array. Removes the entry when empty to keep the
+	* store clean.
+	*/
+	async write(items) {
+		if (items.length === 0) {
+			await this.driver.remove(this.key);
+			return;
+		}
+		await this.driver.set(this.key, items);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async push(...items) {
+		const current = await this.read();
+		current.push(...items);
+		await this.write(current);
+		return current.length;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async unshift(...items) {
+		const current = await this.read();
+		current.unshift(...items);
+		await this.write(current);
+		return current.length;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async pop() {
+		const current = await this.read();
+		if (current.length === 0) return null;
+		const value = current.pop();
+		await this.write(current);
+		return value;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async shift() {
+		const current = await this.read();
+		if (current.length === 0) return null;
+		const value = current.shift();
+		await this.write(current);
+		return value;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async slice(start, end) {
+		return (await this.read()).slice(start, end);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async all() {
+		return this.read();
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async length() {
+		return (await this.read()).length;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async trim(start, end) {
+		const trimmed = (await this.read()).slice(start, end + 1);
+		await this.write(trimmed);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async clear() {
+		await this.driver.remove(this.key);
+	}
+};
+
+//#endregion
+export { MemoryCacheList };
+//# sourceMappingURL=memory-cache-list.mjs.map

package/esm/list/memory-cache-list.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-cache-list.mjs","names":[],"sources":["../../../../../../@warlock.js/cache/src/list/memory-cache-list.ts"],"sourcesContent":["import type { CacheDriver, CacheKey, CacheListAccessor } from \"../types\";\n\n/**\n * Generic array-backed {@link CacheListAccessor}.\n *\n * Stores the full list as a single cache entry and performs read-mutate-write\n * for every operation. Correct for any driver, but O(n) per op. The Redis\n * driver overrides `list()` to return a native-command accessor instead.\n *\n * **Role.** Fallback list accessor bound to a driver + key. Every mutation\n * fetches the array, transforms it in memory, and writes it back.\n *\n * **Responsibility.**\n * - Owns: translating list operations into array mutations + driver writes.\n * - Does NOT own: concurrency control (callers should wrap in a distributed\n *   lock when multi-process writers are possible), TTL preservation across\n *   ops (writes use driver defaults), or tagging of list entries.\n *\n * @example\n * // Never constructed directly — obtained via driver.list():\n * const list = cache.list<Event>(\"recent-events\");\n * await list.push(event);\n */\nexport class MemoryCacheList<T> implements CacheListAccessor<T> {\n  public constructor(\n    private readonly driver: CacheDriver<any, any>,\n    private readonly key: CacheKey,\n  ) {}\n\n  /**\n   * Read the backing array from the driver. Returns an empty array on miss.\n   */\n  private async read(): Promise<T[]> {\n    const current = (await this.driver.get(this.key)) as T[] | null;\n    return Array.isArray(current) ? [...current] : [];\n  }\n\n  /**\n   * Persist the backing array. Removes the entry when empty to keep the\n   * store clean.\n   */\n  private async write(items: T[]): Promise<void> {\n    if (items.length === 0) {\n      await this.driver.remove(this.key);\n      return;\n    }\n\n    await this.driver.set(this.key, items);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async push(...items: T[]): Promise<number> {\n    const current = await this.read();\n    current.push(...items);\n    await this.write(current);\n\n    return current.length;\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async unshift(...items: T[]): Promise<number> {\n    const current = await this.read();\n    current.unshift(...items);\n    await this.write(current);\n\n    return current.length;\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async pop(): Promise<T | null> {\n    const current = await this.read();\n\n    if (current.length === 0) {\n      return null;\n    }\n\n    const value = current.pop() as T;\n    await this.write(current);\n\n    return value;\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async shift(): Promise<T | null> {\n    const current = await this.read();\n\n    if (current.length === 0) {\n      return null;\n    }\n\n    const value = current.shift() as T;\n    await this.write(current);\n\n    return value;\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async slice(start?: number, end?: number): Promise<T[]> {\n    const current = await this.read();\n    return current.slice(start, end);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async all(): Promise<T[]> {\n    return this.read();\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async length(): Promise<number> {\n    const current = await this.read();\n    return current.length;\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async trim(start: number, end: number): Promise<void> {\n    const current = await this.read();\n    const trimmed = current.slice(start, end + 1);\n    await this.write(trimmed);\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async clear(): Promise<void> {\n    await this.driver.remove(this.key);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAuBA,IAAa,kBAAb,MAAgE;CAC9D,AAAO,YACL,AAAiB,QACjB,AAAiB,KACjB;EAFiB;EACA;CAChB;;;;CAKH,MAAc,OAAqB;EACjC,MAAM,UAAW,MAAM,KAAK,OAAO,IAAI,KAAK,GAAG;EAC/C,OAAO,MAAM,QAAQ,OAAO,IAAI,CAAC,GAAG,OAAO,IAAI,CAAC;CAClD;;;;;CAMA,MAAc,MAAM,OAA2B;EAC7C,IAAI,MAAM,WAAW,GAAG;GACtB,MAAM,KAAK,OAAO,OAAO,KAAK,GAAG;GACjC;EACF;EAEA,MAAM,KAAK,OAAO,IAAI,KAAK,KAAK,KAAK;CACvC;;;;CAKA,MAAa,KAAK,GAAG,OAA6B;EAChD,MAAM,UAAU,MAAM,KAAK,KAAK;EAChC,QAAQ,KAAK,GAAG,KAAK;EACrB,MAAM,KAAK,MAAM,OAAO;EAExB,OAAO,QAAQ;CACjB;;;;CAKA,MAAa,QAAQ,GAAG,OAA6B;EACnD,MAAM,UAAU,MAAM,KAAK,KAAK;EAChC,QAAQ,QAAQ,GAAG,KAAK;EACxB,MAAM,KAAK,MAAM,OAAO;EAExB,OAAO,QAAQ;CACjB;;;;CAKA,MAAa,MAAyB;EACpC,MAAM,UAAU,MAAM,KAAK,KAAK;EAEhC,IAAI,QAAQ,WAAW,GACrB,OAAO;EAGT,MAAM,QAAQ,QAAQ,IAAI;EAC1B,MAAM,KAAK,MAAM,OAAO;EAExB,OAAO;CACT;;;;CAKA,MAAa,QAA2B;EACtC,MAAM,UAAU,MAAM,KAAK,KAAK;EAEhC,IAAI,QAAQ,WAAW,GACrB,OAAO;EAGT,MAAM,QAAQ,QAAQ,MAAM;EAC5B,MAAM,KAAK,MAAM,OAAO;EAExB,OAAO;CACT;;;;CAKA,MAAa,MAAM,OAAgB,KAA4B;EAE7D,QAAO,MADe,KAAK,KAAK,GACjB,MAAM,OAAO,GAAG;CACjC;;;;CAKA,MAAa,MAAoB;EAC/B,OAAO,KAAK,KAAK;CACnB;;;;CAKA,MAAa,SAA0B;EAErC,QAAO,MADe,KAAK,KAAK,GACjB;CACjB;;;;CAKA,MAAa,KAAK,OAAe,KAA4B;EAE3D,MAAM,WAAU,MADM,KAAK,KAAK,GACR,MAAM,OAAO,MAAM,CAAC;EAC5C,MAAM,KAAK,MAAM,OAAO;CAC1B;;;;CAKA,MAAa,QAAuB;EAClC,MAAM,KAAK,OAAO,OAAO,KAAK,GAAG;CACnC;AACF"}