@warlock.js/cache 5.19.1 → 5.21.0

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

@@ -1,7 +1,10 @@
-import { CacheConfigurationError, CacheUnsupportedError } from "../types.mjs";
+import { CacheConfigurationError, CacheError, CacheUnsupportedError } from "../types.mjs";
+import { parseTtl } from "../utils.mjs";
 import { BaseCacheDriver } from "./base-cache-driver.mjs";
 
 //#region ../cache/src/drivers/pg-cache-driver.ts
+/** Compare-and-set attempts before `update()` gives up under contention. */
+const PG_UPDATE_MAX_ATTEMPTS = 10;
 /**
 * Allowed characters in a Postgres identifier (table name). We accept the
 * conservative ASCII subset and reject anything else — interpolating an
@@ -97,12 +100,94 @@ var PgCacheDriver = class extends BaseCacheDriver {
 		return this.options.client;
 	}
 	/**
-	* Compute an absolute `expires_at` Date for the given relative TTL in seconds,
-	* or `null` when the entry should not expire (`Infinity` / 0 / undefined).
+	* {@inheritdoc}
+	*
+	* Single `DELETE … WHERE key AND value` — atomic in Postgres.
+	*/
+	async deleteIfEquals(key, expected) {
+		const parsedKey = this.parseKey(key);
+		if ((await this.pgClient.query(`DELETE FROM ${this.table}
+       WHERE key = $1 AND value = $2::jsonb AND (expires_at IS NULL OR expires_at > now())
+       RETURNING 1`, [parsedKey, JSON.stringify(expected)])).rows.length === 0) return false;
+		await this.emit("removed", { key: parsedKey });
+		return true;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* One `INSERT … ON CONFLICT DO UPDATE` that unions the stored JSON array with
+	* `members`. Postgres row-locks the conflicting row, so concurrent adders on
+	* any number of servers serialize and none is lost.
+	*
+	* The index stays a row of the main table holding a JSON array — the same
+	* shape earlier versions wrote — so no schema change or migration is needed
+	* and existing indexes keep working. (The `tags` column only records tags
+	* passed inline to `set()`, not relationships added afterwards, so it can't
+	* serve as the invalidation index.)
+	*/
+	async tagAdd(tagKey, members) {
+		if (members.length === 0) return;
+		const t = this.table;
+		await this.pgClient.query(`/* cache:tag-add */ INSERT INTO ${t} (key, value)
+       VALUES ($1, to_jsonb($2::text[]))
+       ON CONFLICT (key) DO UPDATE
+         SET value = (
+           SELECT COALESCE(jsonb_agg(u.member), '[]'::jsonb)
+           FROM (
+             SELECT x.member FROM jsonb_array_elements_text(
+               CASE WHEN jsonb_typeof(${t}.value) = 'array' THEN ${t}.value ELSE '[]'::jsonb END
+             ) AS x(member)
+             UNION
+             SELECT y.member FROM unnest($2::text[]) AS y(member)
+           ) AS u
+         ),
+         expires_at = NULL`, [this.parseKey(tagKey), members]);
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* One `UPDATE` that filters `members` out of the stored array (members added
+	* concurrently are kept), then a conditional `DELETE` of the row if it ended
+	* up empty.
+	*/
+	async tagRemove(tagKey, members) {
+		if (members.length === 0) return;
+		const t = this.table;
+		const parsedKey = this.parseKey(tagKey);
+		await this.pgClient.query(`/* cache:tag-remove */ UPDATE ${t}
+       SET value = (
+         SELECT COALESCE(jsonb_agg(x.member), '[]'::jsonb)
+         FROM jsonb_array_elements_text(
+           CASE WHEN jsonb_typeof(${t}.value) = 'array' THEN ${t}.value ELSE '[]'::jsonb END
+         ) AS x(member)
+         WHERE x.member <> ALL($2::text[])
+       )
+       WHERE key = $1`, [parsedKey, members]);
+		await this.pgClient.query(`/* cache:tag-drop-empty */ DELETE FROM ${t} WHERE key = $1 AND value = '[]'::jsonb`, [parsedKey]);
+	}
+	/**
+	* TTL in seconds bound to `now() + make_interval(secs => $n)`, so expiry is
+	* computed on the DB clock (immune to app/DB clock skew). `null` — from
+	* `Infinity` / 0 / undefined — yields a NULL `expires_at` (never expires).
 	*/
-	ttlToExpiresAt(ttl) {
+	ttlToSeconds(ttl) {
 		if (!ttl || ttl === Infinity) return null;
-		return new Date(Date.now() + ttl * 1e3);
+		return ttl;
+	}
+	/**
+	* Delete expired rows in batches of `limit`. Returns how many were removed.
+	* Also invoked opportunistically (~1 in 200 writes) by `set()`.
+	*/
+	async prune(limit = 1e3) {
+		const t = this.table;
+		return (await this.pgClient.query(`DELETE FROM ${t} WHERE ctid IN (SELECT ctid FROM ${t} WHERE expires_at < now() LIMIT $1)`, [limit])).rowCount ?? 0;
+	}
+	/**
+	* Fire-and-forget `prune()` on roughly 1 in 200 writes; errors are logged.
+	*/
+	maybePrune() {
+		if (Math.random() >= 1 / 200) return;
+		this.prune().catch((error) => this.logError("prune failed", error));
 	}
 	/**
 	* Return the SQL needed to provision the cache table + index. Run once via
@@ -168,7 +253,7 @@ var PgCacheDriver = class extends BaseCacheDriver {
 			await this.ensureVectorReady();
 		}
 		this.log("caching", parsedKey);
-		const expiresAt = this.ttlToExpiresAt(ttl);
+		const expiresAt = this.ttlToSeconds(ttl);
 		const staleAtDate = staleAt !== void 0 ? new Date(staleAt) : null;
 		const tagsArr = tags ?? [];
 		const serialized = JSON.stringify(value);
@@ -184,7 +269,7 @@ var PgCacheDriver = class extends BaseCacheDriver {
 		const placeholders = [
 			"$1",
 			"$2::jsonb",
-			"$3",
+			"now() + make_interval(secs => $3::double precision)",
 			"$4",
 			"$5"
 		];
@@ -217,6 +302,7 @@ var PgCacheDriver = class extends BaseCacheDriver {
 			};
 			if (tags && tags.length > 0) await this.applyTags(key, tags);
 			this.log("cached", parsedKey);
+			this.maybePrune();
 			await this.emit("set", {
 				key: parsedKey,
 				value,
@@ -238,6 +324,7 @@ var PgCacheDriver = class extends BaseCacheDriver {
 			};
 			if (tags && tags.length > 0) await this.applyTags(key, tags);
 			this.log("cached", parsedKey);
+			this.maybePrune();
 			await this.emit("set", {
 				key: parsedKey,
 				value,
@@ -254,6 +341,7 @@ var PgCacheDriver = class extends BaseCacheDriver {
          SET ${setClause}`, params);
 		if (tags && tags.length > 0) await this.applyTags(key, tags);
 		this.log("cached", parsedKey);
+		this.maybePrune();
 		await this.emit("set", {
 			key: parsedKey,
 			value,
@@ -330,6 +418,140 @@ var PgCacheDriver = class extends BaseCacheDriver {
 		return entry;
 	}
 	/**
+	* Decode a JSONB column value (node-postgres usually parses it already;
+	* some pools hand back a string).
+	*/
+	decodeJson(value) {
+		if (typeof value === "string") try {
+			return JSON.parse(value);
+		} catch {
+			return value;
+		}
+		return value;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* One atomic `INSERT … ON CONFLICT DO UPDATE` statement, so concurrent
+	* increments from any number of servers never lose an update. A live row
+	* keeps its `expires_at`; a missing or expired row restarts from `value`
+	* with the driver default TTL. A non-numeric live value is rejected.
+	*/
+	async increment(key, value = 1) {
+		const parsedKey = this.parseKey(key);
+		const t = this.table;
+		const expired = `${t}.expires_at IS NOT NULL AND ${t}.expires_at <= now()`;
+		const { rows } = await this.pgClient.query(`/* cache:increment */ INSERT INTO ${t}(key, value, expires_at)
+       VALUES ($1, to_jsonb($2::numeric), now() + make_interval(secs => $3::double precision))
+       ON CONFLICT (key) DO UPDATE
+         SET value = CASE WHEN ${expired} THEN EXCLUDED.value
+                          ELSE to_jsonb((${t}.value #>> '{}')::numeric + $2::numeric) END,
+             expires_at = CASE WHEN ${expired} THEN EXCLUDED.expires_at ELSE ${t}.expires_at END,
+             stale_at = CASE WHEN ${expired} THEN NULL ELSE ${t}.stale_at END
+         WHERE (${expired}) OR jsonb_typeof(${t}.value) = 'number'
+       RETURNING value`, [
+			parsedKey,
+			value,
+			this.ttlToSeconds(this.ttl)
+		]);
+		if (rows.length === 0) throw new Error(`Cannot increment non-numeric value for key: ${parsedKey}`);
+		const newValue = Number(this.decodeJson(rows[0].value));
+		await this.emit("set", {
+			key: parsedKey,
+			value: newValue,
+			ttl: this.ttl
+		});
+		return newValue;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* One atomic `DELETE … RETURNING`, so a value is handed out exactly once
+	* across servers. Expired rows count as missing.
+	*/
+	async pull(key) {
+		const parsedKey = this.parseKey(key);
+		const { rows } = await this.pgClient.query(`/* cache:pull */ DELETE FROM ${this.table}
+       WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())
+       RETURNING value`, [parsedKey]);
+		if (rows.length === 0) {
+			await this.emit("miss", { key: parsedKey });
+			return null;
+		}
+		const value = this.decodeJson(rows[0].value);
+		await this.emit("hit", {
+			key: parsedKey,
+			value
+		});
+		await this.emit("removed", { key: parsedKey });
+		return value;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Atomic across servers via optimistic compare-and-set: read the live value,
+	* run `fn`, then write with `UPDATE … WHERE value = <what was read>` (or a
+	* create-only insert for a missing key), retrying when another writer got
+	* there first. `fn` may run more than once under contention; after
+	* {@link PG_UPDATE_MAX_ATTEMPTS} lost races it throws {@link CacheError}.
+	*
+	* Without an explicit `ttl` the row keeps its `expires_at`; a new key gets
+	* the driver default TTL. Returning `null` deletes the key (compare-and-delete).
+	*/
+	async update(key, fn, options = {}) {
+		const parsedKey = this.parseKey(key);
+		const t = this.table;
+		const live = `(expires_at IS NULL OR expires_at > now())`;
+		const explicitTtl = options.ttl !== void 0 ? parseTtl(options.ttl) : void 0;
+		for (let attempt = 0; attempt < PG_UPDATE_MAX_ATTEMPTS; attempt++) {
+			const read = await this.pgClient.query(`SELECT value FROM ${t}
+         WHERE key = $1 AND ${live}`, [parsedKey]);
+			const exists = read.rows.length > 0;
+			const current = exists ? this.decodeJson(read.rows[0].value) : null;
+			const expected = exists ? JSON.stringify(current) : null;
+			const result = await fn(current);
+			if (result === null) {
+				if (!exists) return null;
+				if ((await this.pgClient.query(`/* cache:cas-delete */ DELETE FROM ${t}
+           WHERE key = $1 AND value = $2::jsonb AND ${live}
+           RETURNING 1`, [parsedKey, expected])).rows.length > 0) {
+					await this.emit("removed", { key: parsedKey });
+					return null;
+				}
+				continue;
+			}
+			if (!exists) {
+				if ((await this.set(key, result, {
+					onConflict: "create",
+					...explicitTtl !== void 0 ? { ttl: explicitTtl } : {}
+				})).wasSet) return result;
+				continue;
+			}
+			const params = [
+				parsedKey,
+				JSON.stringify(result),
+				expected
+			];
+			let expirySql = "";
+			if (explicitTtl !== void 0) {
+				params.push(this.ttlToSeconds(explicitTtl));
+				expirySql = `, expires_at = now() + make_interval(secs => $4::double precision)`;
+			}
+			if ((await this.pgClient.query(`/* cache:cas-update */ UPDATE ${t}
+         SET value = $2::jsonb, stale_at = NULL${expirySql}
+         WHERE key = $1 AND value = $3::jsonb AND ${live}
+         RETURNING 1`, params)).rows.length > 0) {
+				await this.emit("set", {
+					key: parsedKey,
+					value: result,
+					ttl: explicitTtl
+				});
+				return result;
+			}
+		}
+		throw new CacheError(`cache.update(): '${parsedKey}' changed on every attempt (${PG_UPDATE_MAX_ATTEMPTS} tries) — too much write contention.`);
+	}
+	/**
 	* {@inheritdoc}
 	*/
 	async remove(key) {

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

@@ -1 +1 @@
-{"version":3,"file":"pg-cache-driver.mjs","names":[],"sources":["../../../../../../../cache/src/drivers/pg-cache-driver.ts"],"sourcesContent":["import type {\n  CacheData,\n  CacheDriver,\n  CacheKey,\n  CacheSetOptions,\n  CacheSetResult,\n  CacheSimilarHit,\n  CacheSimilarOptions,\n  CacheTtl,\n  PgCacheOptions,\n  PgClientLike,\n} from \"../types\";\nimport { CacheConfigurationError, CacheUnsupportedError } from \"../types\";\nimport { BaseCacheDriver } from \"./base-cache-driver\";\n\n/**\n * Allowed characters in a Postgres identifier (table name). We accept the\n * conservative ASCII subset and reject anything else — interpolating an\n * arbitrary string into DDL would be a SQL-injection footgun.\n */\nconst SAFE_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;\n\n/**\n * Postgres cache driver with optional pgvector similarity support.\n *\n * Connection lifecycle is the caller's responsibility — pass an already-built\n * `pg.Pool` or `pg.Client` via the `client` option. The driver never closes it\n * on `cache.disconnect()`, so the same pool can serve queries elsewhere in\n * the app.\n *\n * Schema is not auto-migrated. Call `driver.schema()` to get the DDL string\n * and run it through whichever migration tool you use.\n *\n * @example\n * import { Pool } from \"pg\";\n * import { cache, PgCacheDriver } from \"@warlock.js/cache\";\n *\n * const pool = new Pool({ connectionString: process.env.DATABASE_URL });\n *\n * cache.setCacheConfigurations({\n *   default: \"pg\",\n *   drivers: { pg: PgCacheDriver },\n *   options: { pg: { client: pool, table: \"warlock_cache\", ttl: \"1h\" } },\n * });\n *\n * await cache.init();\n *\n * // Run once, via your own migration tooling:\n * // await pool.query(driver.schema());\n */\nexport class PgCacheDriver\n  extends BaseCacheDriver<PgClientLike, PgCacheOptions>\n  implements CacheDriver<PgClientLike, PgCacheOptions>\n{\n  /**\n   * {@inheritdoc}\n   */\n  public name = \"pg\";\n\n  /**\n   * Cached result of the pgvector extension check. Populated lazily on first\n   * vector op so the driver doesn't probe the database at construction time.\n   */\n  protected vectorReady?: boolean;\n\n  /**\n   * {@inheritdoc}\n   *\n   * Validates `client` presence and the table name before storing options.\n   */\n  public setOptions(options: PgCacheOptions) {\n    if (!options || !options.client || typeof options.client.query !== \"function\") {\n      throw new CacheConfigurationError(\n        \"Pg cache driver requires a 'client' option implementing { query(text, values) } — pass a pg.Pool or pg.Client.\",\n      );\n    }\n\n    const table = options.table ?? \"warlock_cache\";\n    if (!SAFE_IDENT.test(table)) {\n      throw new CacheConfigurationError(\n        `Pg cache driver: invalid table name '${table}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`,\n      );\n    }\n\n    if (options.vector) {\n      const dim = options.vector.dimensions;\n      if (!Number.isInteger(dim) || dim <= 0) {\n        throw new CacheConfigurationError(\n          `Pg cache driver: vector.dimensions must be a positive integer; got ${dim}.`,\n        );\n      }\n      const idx = options.vector.index ?? \"hnsw\";\n      if (idx !== \"hnsw\" && idx !== \"ivfflat\") {\n        throw new CacheConfigurationError(\n          `Pg cache driver: vector.index must be 'hnsw' or 'ivfflat'; got '${idx}'.`,\n        );\n      }\n    }\n\n    return super.setOptions({ ...options, table });\n  }\n\n  /**\n   * Lazy pgvector availability check. Runs once on the first vector op and\n   * caches the result — subsequent ops are zero-overhead. Throws\n   * {@link CacheConfigurationError} if the extension isn't installed; throws\n   * {@link CacheUnsupportedError} if `vector` config wasn't provided at all.\n   */\n  protected async ensureVectorReady(): Promise<void> {\n    if (!this.options.vector) {\n      throw new CacheUnsupportedError(\n        \"'pg' driver: similarity retrieval requires the 'vector' config block. Set options.vector.dimensions and reconnect.\",\n      );\n    }\n\n    if (this.vectorReady === true) {\n      return;\n    }\n\n    const { rows } = await this.pgClient.query(\n      `SELECT 1 FROM pg_extension WHERE extname = 'vector'`,\n    );\n\n    if (rows.length === 0) {\n      throw new CacheConfigurationError(\n        \"'pg' driver: pgvector extension not installed. Run 'CREATE EXTENSION vector;' or remove the 'vector' config option.\",\n      );\n    }\n\n    this.vectorReady = true;\n  }\n\n  /**\n   * Format a numeric vector for pgvector ingestion. The `vector` type accepts\n   * a string literal `'[1,2,3]'` cast via `::vector` — this avoids depending\n   * on the binary protocol and works against any pg client.\n   */\n  protected formatVector(vector: number[]): string {\n    return `[${vector.join(\",\")}]`;\n  }\n\n  /**\n   * Resolved table name. Always defined post-`setOptions` — the validator\n   * fills in the default.\n   */\n  protected get table(): string {\n    return this.options.table ?? \"warlock_cache\";\n  }\n\n  /**\n   * The user-supplied `pg.Pool` / `pg.Client`. Use this rather than `this.client`\n   * (which has a generic fallback to `this`) for actual queries.\n   */\n  protected get pgClient(): PgClientLike {\n    return this.options.client;\n  }\n\n  /**\n   * Compute an absolute `expires_at` Date for the given relative TTL in seconds,\n   * or `null` when the entry should not expire (`Infinity` / 0 / undefined).\n   */\n  protected ttlToExpiresAt(ttl?: number): Date | null {\n    if (!ttl || ttl === Infinity) {\n      return null;\n    }\n\n    return new Date(Date.now() + ttl * 1000);\n  }\n\n  /**\n   * Return the SQL needed to provision the cache table + index. Run once via\n   * the caller's migration tooling — the driver never auto-migrates.\n   *\n   * @example\n   * await pool.query(driver.schema());\n   */\n  public schema(): string {\n    const t = this.table;\n    const vec = this.options.vector;\n\n    const columns = [\n      `  key TEXT PRIMARY KEY,`,\n      `  value JSONB NOT NULL,`,\n      `  expires_at TIMESTAMPTZ,`,\n      `  stale_at TIMESTAMPTZ,`,\n      `  tags TEXT[] NOT NULL DEFAULT '{}'::TEXT[]`,\n    ];\n\n    if (vec) {\n      // Trailing comma on the previous line to make this a valid column list.\n      columns[columns.length - 1] = columns[columns.length - 1] + \",\";\n      columns.push(`  embedding VECTOR(${vec.dimensions})`);\n    }\n\n    const lines = [\n      `CREATE TABLE IF NOT EXISTS ${t} (`,\n      ...columns,\n      `);`,\n      `CREATE INDEX IF NOT EXISTS idx_${t}_expires_at ON ${t} (expires_at);`,\n      `CREATE INDEX IF NOT EXISTS idx_${t}_tags ON ${t} USING GIN (tags);`,\n    ];\n\n    if (vec) {\n      const idx = vec.index ?? \"hnsw\";\n      lines.push(\n        `CREATE INDEX IF NOT EXISTS idx_${t}_embedding ON ${t} USING ${idx} (embedding vector_cosine_ops);`,\n      );\n    }\n\n    return lines.join(\"\\n\");\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async connect() {\n    // No-op — caller owns the connection. We emit `connected` for symmetry\n    // with the other drivers' lifecycle events.\n    this.log(\"connecting\");\n    this.log(\"connected\");\n    await this.emit(\"connected\");\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Does NOT close the user-supplied client — lifecycle stays with the caller.\n   */\n  public async disconnect() {\n    this.log(\"disconnected\");\n    await this.emit(\"disconnected\");\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      if (!this.options.vector) {\n        throw new CacheUnsupportedError(\n          \"'pg' driver: cannot index a vector without options.vector configuration — set { dimensions } and recreate the table via driver.schema().\",\n        );\n      }\n\n      const expected = this.options.vector.dimensions;\n      if (vector.length !== expected) {\n        throw new CacheConfigurationError(\n          `Pg cache driver: vector dimension mismatch — expected ${expected}, got ${vector.length}.`,\n        );\n      }\n\n      await this.ensureVectorReady();\n    }\n\n    this.log(\"caching\", parsedKey);\n\n    const expiresAt = this.ttlToExpiresAt(ttl);\n    const staleAtDate = staleAt !== undefined ? new Date(staleAt) : null;\n    const tagsArr = tags ?? [];\n    const serialized = JSON.stringify(value);\n    const vecLiteral = vector ? this.formatVector(vector) : null;\n\n    const t = this.table;\n\n    // Build column / placeholder / param triplets dynamically so the same code\n    // path serves both KV-only and vector-aware writes. Param order is fixed:\n    //   $1 = key, $2 = value (jsonb), $3 = expires_at, $4 = stale_at,\n    //   $5 = tags, $6 = embedding::vector (only present when vecLiteral !== null).\n    const cols = [\"key\", \"value\", \"expires_at\", \"stale_at\", \"tags\"];\n    const placeholders = [\"$1\", \"$2::jsonb\", \"$3\", \"$4\", \"$5\"];\n    const params: unknown[] = [parsedKey, serialized, expiresAt, staleAtDate, tagsArr];\n    if (vecLiteral !== null) {\n      cols.push(\"embedding\");\n      placeholders.push(`$${params.length + 1}::vector`);\n      params.push(vecLiteral);\n    }\n    const colList = cols.join(\", \");\n    const valList = placeholders.join(\", \");\n    const setClause = cols\n      .slice(1)\n      .map((c) => `${c} = EXCLUDED.${c}`)\n      .join(\", \");\n    const updateSetClause = cols\n      .slice(1)\n      .map((c, i) => `${c} = ${placeholders[i + 1]}`)\n      .join(\", \");\n\n    if (onConflict === \"create\") {\n      // Race-safe insert: if another worker already holds the key (and the row\n      // hasn't expired), DO NOTHING; we then SELECT to surface the existing value.\n      const { rows } = await this.pgClient.query(\n        `INSERT INTO ${t}(${colList})\n         VALUES (${valList})\n         ON CONFLICT (key) DO UPDATE\n           SET ${setClause}\n           WHERE ${t}.expires_at IS NOT NULL AND ${t}.expires_at < now()\n         RETURNING value`,\n        params,\n      );\n\n      if (rows.length === 0) {\n        // Conflict + existing row not expired → fetch existing for the result.\n        const existing = await this.get(key);\n        return { wasSet: false, existing } satisfies CacheSetResult;\n      }\n\n      if (tags && tags.length > 0) {\n        await this.applyTags(key, tags);\n      }\n\n      this.log(\"cached\", parsedKey);\n      await this.emit(\"set\", { key: parsedKey, value, ttl });\n      return { wasSet: true, existing: null } satisfies CacheSetResult;\n    }\n\n    if (onConflict === \"update\") {\n      // Update only when the key exists AND hasn't expired.\n      const { rows } = await this.pgClient.query(\n        `UPDATE ${t}\n         SET ${updateSetClause}\n         WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())\n         RETURNING value`,\n        params,\n      );\n\n      if (rows.length === 0) {\n        return { wasSet: false, existing: null } satisfies CacheSetResult;\n      }\n\n      if (tags && tags.length > 0) {\n        await this.applyTags(key, tags);\n      }\n\n      this.log(\"cached\", parsedKey);\n      await this.emit(\"set\", { key: parsedKey, value, ttl });\n      return { wasSet: true, existing: null } satisfies CacheSetResult;\n    }\n\n    // upsert (default)\n    await this.pgClient.query(\n      `INSERT INTO ${t}(${colList})\n       VALUES (${valList})\n       ON CONFLICT (key) DO UPDATE\n         SET ${setClause}`,\n      params,\n    );\n\n    if (tags && tags.length > 0) {\n      await this.applyTags(key, tags);\n    }\n\n    this.log(\"cached\", parsedKey);\n    await this.emit(\"set\", { key: parsedKey, value, ttl });\n    return value;\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async get(key: CacheKey) {\n    const parsedKey = this.parseKey(key);\n    this.log(\"fetching\", parsedKey);\n\n    const t = this.table;\n    const { rows } = await this.pgClient.query(\n      `SELECT value FROM ${t}\n       WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())`,\n      [parsedKey],\n    );\n\n    if (rows.length === 0) {\n      this.log(\"notFound\", parsedKey);\n      await this.emit(\"miss\", { key: parsedKey });\n      return null;\n    }\n\n    this.log(\"fetched\", parsedKey);\n\n    // pg's JSONB type round-trips through node-postgres as a parsed JS value\n    // already — but some pool implementations may hand back a string. Be defensive.\n    let value = rows[0].value;\n    if (typeof value === \"string\") {\n      try {\n        value = JSON.parse(value);\n      } catch {\n        // Leave it as-is; cloning below will fail loud if it's truly broken.\n      }\n    }\n\n    if (value === null || value === undefined) {\n      await this.emit(\"hit\", { key: parsedKey, value });\n      return value;\n    }\n\n    const type = typeof value;\n    if (type === \"string\" || type === \"number\" || type === \"boolean\") {\n      await this.emit(\"hit\", { key: parsedKey, value });\n      return value;\n    }\n\n    try {\n      const cloned = structuredClone(value);\n      await this.emit(\"hit\", { key: parsedKey, value: cloned });\n      return cloned;\n    } catch (error) {\n      this.logError(`Failed to clone cached value for ${parsedKey}`, error);\n      throw error;\n    }\n  }\n\n  /**\n   * Read the raw {@link CacheData} wrapper, including `staleAt` metadata.\n   * Returns `null` for missing or expired rows — `swr()` consumes this to\n   * branch on freshness without going through `get()`'s clone-and-emit path.\n   */\n  protected async getEntry(key: CacheKey): Promise<CacheData | null> {\n    const parsedKey = this.parseKey(key);\n    const t = this.table;\n\n    const { rows } = await this.pgClient.query(\n      `SELECT value, expires_at, stale_at FROM ${t}\n       WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())`,\n      [parsedKey],\n    );\n\n    if (rows.length === 0) {\n      return null;\n    }\n\n    let data = rows[0].value;\n    if (typeof data === \"string\") {\n      try {\n        data = JSON.parse(data);\n      } catch {\n        // Leave as-is — getEntry is metadata-shaped, the caller will hit the\n        // same parse path on the public `get()` if they care.\n      }\n    }\n\n    const entry: CacheData = { data };\n\n    const expiresAtRaw = rows[0].expires_at as Date | string | null;\n    if (expiresAtRaw) {\n      const expiresAt = expiresAtRaw instanceof Date ? expiresAtRaw : new Date(expiresAtRaw);\n      entry.expiresAt = expiresAt.getTime();\n    }\n\n    const staleAtRaw = rows[0].stale_at as Date | string | null;\n    if (staleAtRaw) {\n      const staleAt = staleAtRaw instanceof Date ? staleAtRaw : new Date(staleAtRaw);\n      entry.staleAt = staleAt.getTime();\n    }\n\n    return entry;\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 t = this.table;\n    await this.pgClient.query(`DELETE FROM ${t} WHERE key = $1`, [parsedKey]);\n\n    this.log(\"removed\", parsedKey);\n    await this.emit(\"removed\", { key: parsedKey });\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Deletes all rows whose key equals the namespace exactly or starts with\n   * `<namespace>.` — same boundary semantics as the other drivers.\n   */\n  public async removeNamespace(namespace: string) {\n    const parsed = this.parseKey(namespace);\n    this.log(\"clearing\", parsed || \"(all)\");\n\n    const t = this.table;\n\n    if (parsed === \"\") {\n      await this.pgClient.query(`DELETE FROM ${t}`);\n    } else {\n      // Escape `_` and `%` in the prefix so they aren't treated as LIKE wildcards.\n      const escaped = parsed.replace(/\\\\/g, \"\\\\\\\\\").replace(/_/g, \"\\\\_\").replace(/%/g, \"\\\\%\");\n      await this.pgClient.query(`DELETE FROM ${t} WHERE key = $1 OR key LIKE $2 ESCAPE '\\\\'`, [\n        parsed,\n        `${escaped}.%`,\n      ]);\n    }\n\n    this.log(\"cleared\", parsed || \"(all)\");\n    return this;\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Honors `globalPrefix` — when configured, scopes the flush to entries\n   * under the prefix rather than truncating the entire table (which could\n   * wipe sibling tenants sharing the same Postgres database).\n   */\n  public async flush() {\n    this.log(\"flushing\");\n\n    if (this.options.globalPrefix) {\n      await this.removeNamespace(\"\");\n    } else {\n      await this.pgClient.query(`DELETE FROM ${this.table}`);\n    }\n\n    this.log(\"flushed\");\n    await this.emit(\"flushed\");\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * pgvector-backed similarity. Uses the `<=>` cosine-distance operator\n   * (lower distance = higher similarity) and converts to cosine similarity\n   * as `1 - distance` so the returned `score` matches the rest of the\n   * package (`[0, 1]`, higher is more similar).\n   *\n   * Honors `topK`, `threshold`, and an optional `tags` filter (native\n   * `tags && $tags` overlap query — much faster than the meta-key path).\n   *\n   * Throws {@link CacheUnsupportedError} when `options.vector` was not\n   * configured at driver setup; throws {@link CacheConfigurationError} when\n   * the pgvector extension is missing or the query vector's dimension count\n   * doesn't match the configured one.\n   */\n  public async similar<T = any>(\n    vector: number[],\n    options: CacheSimilarOptions,\n  ): Promise<CacheSimilarHit<T>[]> {\n    if (!this.options.vector) {\n      throw new CacheUnsupportedError(\n        \"'pg' driver: similarity retrieval requires the 'vector' config block. Set options.vector.dimensions and reconnect.\",\n      );\n    }\n\n    const expected = this.options.vector.dimensions;\n    if (vector.length !== expected) {\n      throw new CacheConfigurationError(\n        `Pg cache driver: vector dimension mismatch — expected ${expected}, got ${vector.length}.`,\n      );\n    }\n\n    if (!Number.isInteger(options.topK) || options.topK <= 0) {\n      throw new CacheConfigurationError(\n        `Pg cache driver: similar.topK must be a positive integer; got ${options.topK}.`,\n      );\n    }\n\n    await this.ensureVectorReady();\n\n    const t = this.table;\n    const vecLiteral = this.formatVector(vector);\n    const params: unknown[] = [vecLiteral];\n    let tagFilter = \"\";\n\n    if (options.tags && options.tags.length > 0) {\n      params.push(options.tags);\n      tagFilter = `AND tags && $${params.length}`;\n    }\n\n    params.push(options.topK);\n    const topKParam = `$${params.length}`;\n\n    const { rows } = await this.pgClient.query(\n      `SELECT key, value, 1 - (embedding <=> $1::vector) AS score\n       FROM ${t}\n       WHERE embedding IS NOT NULL\n         AND (expires_at IS NULL OR expires_at > now())\n         ${tagFilter}\n       ORDER BY embedding <=> $1::vector\n       LIMIT ${topKParam}`,\n      params,\n    );\n\n    const hits: CacheSimilarHit<T>[] = [];\n    for (const row of rows) {\n      const score = Number(row.score);\n      if (options.threshold !== undefined && score < options.threshold) {\n        continue;\n      }\n\n      let value = row.value;\n      if (typeof value === \"string\") {\n        try {\n          value = JSON.parse(value);\n        } catch {\n          // Surface as-is; if non-JSON crept in, the consumer will notice.\n        }\n      }\n\n      // Match get() cloning semantics so consumers can't mutate cached state.\n      if (value !== null && value !== undefined) {\n        const ty = typeof value;\n        if (ty !== \"string\" && ty !== \"number\" && ty !== \"boolean\") {\n          value = structuredClone(value);\n        }\n      }\n\n      hits.push({ key: row.key, value, score });\n    }\n\n    return hits;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"pg-cache-driver.mjs","names":[],"sources":["../../../../../../../cache/src/drivers/pg-cache-driver.ts"],"sourcesContent":["import type {\n  CacheData,\n  CacheDriver,\n  CacheKey,\n  CacheSetOptions,\n  CacheSetResult,\n  CacheSimilarHit,\n  CacheSimilarOptions,\n  CacheTtl,\n  PgCacheOptions,\n  PgClientLike,\n} from \"../types\";\nimport { CacheConfigurationError, CacheError, CacheUnsupportedError } from \"../types\";\nimport { parseTtl } from \"../utils\";\nimport { BaseCacheDriver } from \"./base-cache-driver\";\n\n/** Compare-and-set attempts before `update()` gives up under contention. */\nconst PG_UPDATE_MAX_ATTEMPTS = 10;\n\n/**\n * Allowed characters in a Postgres identifier (table name). We accept the\n * conservative ASCII subset and reject anything else — interpolating an\n * arbitrary string into DDL would be a SQL-injection footgun.\n */\nconst SAFE_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;\n\n/**\n * Postgres cache driver with optional pgvector similarity support.\n *\n * Connection lifecycle is the caller's responsibility — pass an already-built\n * `pg.Pool` or `pg.Client` via the `client` option. The driver never closes it\n * on `cache.disconnect()`, so the same pool can serve queries elsewhere in\n * the app.\n *\n * Schema is not auto-migrated. Call `driver.schema()` to get the DDL string\n * and run it through whichever migration tool you use.\n *\n * @example\n * import { Pool } from \"pg\";\n * import { cache, PgCacheDriver } from \"@warlock.js/cache\";\n *\n * const pool = new Pool({ connectionString: process.env.DATABASE_URL });\n *\n * cache.setCacheConfigurations({\n *   default: \"pg\",\n *   drivers: { pg: PgCacheDriver },\n *   options: { pg: { client: pool, table: \"warlock_cache\", ttl: \"1h\" } },\n * });\n *\n * await cache.init();\n *\n * // Run once, via your own migration tooling:\n * // await pool.query(driver.schema());\n */\nexport class PgCacheDriver\n  extends BaseCacheDriver<PgClientLike, PgCacheOptions>\n  implements CacheDriver<PgClientLike, PgCacheOptions>\n{\n  /**\n   * {@inheritdoc}\n   */\n  public name = \"pg\";\n\n  /**\n   * Cached result of the pgvector extension check. Populated lazily on first\n   * vector op so the driver doesn't probe the database at construction time.\n   */\n  protected vectorReady?: boolean;\n\n  /**\n   * {@inheritdoc}\n   *\n   * Validates `client` presence and the table name before storing options.\n   */\n  public setOptions(options: PgCacheOptions) {\n    if (!options || !options.client || typeof options.client.query !== \"function\") {\n      throw new CacheConfigurationError(\n        \"Pg cache driver requires a 'client' option implementing { query(text, values) } — pass a pg.Pool or pg.Client.\",\n      );\n    }\n\n    const table = options.table ?? \"warlock_cache\";\n    if (!SAFE_IDENT.test(table)) {\n      throw new CacheConfigurationError(\n        `Pg cache driver: invalid table name '${table}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`,\n      );\n    }\n\n    if (options.vector) {\n      const dim = options.vector.dimensions;\n      if (!Number.isInteger(dim) || dim <= 0) {\n        throw new CacheConfigurationError(\n          `Pg cache driver: vector.dimensions must be a positive integer; got ${dim}.`,\n        );\n      }\n      const idx = options.vector.index ?? \"hnsw\";\n      if (idx !== \"hnsw\" && idx !== \"ivfflat\") {\n        throw new CacheConfigurationError(\n          `Pg cache driver: vector.index must be 'hnsw' or 'ivfflat'; got '${idx}'.`,\n        );\n      }\n    }\n\n    return super.setOptions({ ...options, table });\n  }\n\n  /**\n   * Lazy pgvector availability check. Runs once on the first vector op and\n   * caches the result — subsequent ops are zero-overhead. Throws\n   * {@link CacheConfigurationError} if the extension isn't installed; throws\n   * {@link CacheUnsupportedError} if `vector` config wasn't provided at all.\n   */\n  protected async ensureVectorReady(): Promise<void> {\n    if (!this.options.vector) {\n      throw new CacheUnsupportedError(\n        \"'pg' driver: similarity retrieval requires the 'vector' config block. Set options.vector.dimensions and reconnect.\",\n      );\n    }\n\n    if (this.vectorReady === true) {\n      return;\n    }\n\n    const { rows } = await this.pgClient.query(\n      `SELECT 1 FROM pg_extension WHERE extname = 'vector'`,\n    );\n\n    if (rows.length === 0) {\n      throw new CacheConfigurationError(\n        \"'pg' driver: pgvector extension not installed. Run 'CREATE EXTENSION vector;' or remove the 'vector' config option.\",\n      );\n    }\n\n    this.vectorReady = true;\n  }\n\n  /**\n   * Format a numeric vector for pgvector ingestion. The `vector` type accepts\n   * a string literal `'[1,2,3]'` cast via `::vector` — this avoids depending\n   * on the binary protocol and works against any pg client.\n   */\n  protected formatVector(vector: number[]): string {\n    return `[${vector.join(\",\")}]`;\n  }\n\n  /**\n   * Resolved table name. Always defined post-`setOptions` — the validator\n   * fills in the default.\n   */\n  protected get table(): string {\n    return this.options.table ?? \"warlock_cache\";\n  }\n\n  /**\n   * The user-supplied `pg.Pool` / `pg.Client`. Use this rather than `this.client`\n   * (which has a generic fallback to `this`) for actual queries.\n   */\n  protected get pgClient(): PgClientLike {\n    return this.options.client;\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Single `DELETE … WHERE key AND value` — atomic in Postgres.\n   */\n  protected async deleteIfEquals(key: CacheKey, expected: unknown): Promise<boolean> {\n    const parsedKey = this.parseKey(key);\n\n    const res = await this.pgClient.query(\n      `DELETE FROM ${this.table}\n       WHERE key = $1 AND value = $2::jsonb AND (expires_at IS NULL OR expires_at > now())\n       RETURNING 1`,\n      [parsedKey, JSON.stringify(expected)],\n    );\n\n    if (res.rows.length === 0) {\n      return false;\n    }\n\n    await this.emit(\"removed\", { key: parsedKey });\n\n    return true;\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * One `INSERT … ON CONFLICT DO UPDATE` that unions the stored JSON array with\n   * `members`. Postgres row-locks the conflicting row, so concurrent adders on\n   * any number of servers serialize and none is lost.\n   *\n   * The index stays a row of the main table holding a JSON array — the same\n   * shape earlier versions wrote — so no schema change or migration is needed\n   * and existing indexes keep working. (The `tags` column only records tags\n   * passed inline to `set()`, not relationships added afterwards, so it can't\n   * serve as the invalidation index.)\n   */\n  public async tagAdd(tagKey: CacheKey, members: string[]): Promise<void> {\n    if (members.length === 0) {\n      return;\n    }\n\n    const t = this.table;\n\n    await this.pgClient.query(\n      `/* cache:tag-add */ INSERT INTO ${t} (key, value)\n       VALUES ($1, to_jsonb($2::text[]))\n       ON CONFLICT (key) DO UPDATE\n         SET value = (\n           SELECT COALESCE(jsonb_agg(u.member), '[]'::jsonb)\n           FROM (\n             SELECT x.member FROM jsonb_array_elements_text(\n               CASE WHEN jsonb_typeof(${t}.value) = 'array' THEN ${t}.value ELSE '[]'::jsonb END\n             ) AS x(member)\n             UNION\n             SELECT y.member FROM unnest($2::text[]) AS y(member)\n           ) AS u\n         ),\n         expires_at = NULL`,\n      [this.parseKey(tagKey), members],\n    );\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * One `UPDATE` that filters `members` out of the stored array (members added\n   * concurrently are kept), then a conditional `DELETE` of the row if it ended\n   * up empty.\n   */\n  public async tagRemove(tagKey: CacheKey, members: string[]): Promise<void> {\n    if (members.length === 0) {\n      return;\n    }\n\n    const t = this.table;\n    const parsedKey = this.parseKey(tagKey);\n\n    await this.pgClient.query(\n      `/* cache:tag-remove */ UPDATE ${t}\n       SET value = (\n         SELECT COALESCE(jsonb_agg(x.member), '[]'::jsonb)\n         FROM jsonb_array_elements_text(\n           CASE WHEN jsonb_typeof(${t}.value) = 'array' THEN ${t}.value ELSE '[]'::jsonb END\n         ) AS x(member)\n         WHERE x.member <> ALL($2::text[])\n       )\n       WHERE key = $1`,\n      [parsedKey, members],\n    );\n\n    await this.pgClient.query(\n      `/* cache:tag-drop-empty */ DELETE FROM ${t} WHERE key = $1 AND value = '[]'::jsonb`,\n      [parsedKey],\n    );\n  }\n\n  /**\n   * TTL in seconds bound to `now() + make_interval(secs => $n)`, so expiry is\n   * computed on the DB clock (immune to app/DB clock skew). `null` — from\n   * `Infinity` / 0 / undefined — yields a NULL `expires_at` (never expires).\n   */\n  protected ttlToSeconds(ttl?: number): number | null {\n    if (!ttl || ttl === Infinity) {\n      return null;\n    }\n\n    return ttl;\n  }\n\n  /**\n   * Delete expired rows in batches of `limit`. Returns how many were removed.\n   * Also invoked opportunistically (~1 in 200 writes) by `set()`.\n   */\n  public async prune(limit = 1000): Promise<number> {\n    const t = this.table;\n    const res = await this.pgClient.query(\n      `DELETE FROM ${t} WHERE ctid IN (SELECT ctid FROM ${t} WHERE expires_at < now() LIMIT $1)`,\n      [limit],\n    );\n\n    return res.rowCount ?? 0;\n  }\n\n  /**\n   * Fire-and-forget `prune()` on roughly 1 in 200 writes; errors are logged.\n   */\n  protected maybePrune(): void {\n    if (Math.random() >= 1 / 200) {\n      return;\n    }\n\n    this.prune().catch(error => this.logError(\"prune failed\", error));\n  }\n\n  /**\n   * Return the SQL needed to provision the cache table + index. Run once via\n   * the caller's migration tooling — the driver never auto-migrates.\n   *\n   * @example\n   * await pool.query(driver.schema());\n   */\n  public schema(): string {\n    const t = this.table;\n    const vec = this.options.vector;\n\n    const columns = [\n      `  key TEXT PRIMARY KEY,`,\n      `  value JSONB NOT NULL,`,\n      `  expires_at TIMESTAMPTZ,`,\n      `  stale_at TIMESTAMPTZ,`,\n      `  tags TEXT[] NOT NULL DEFAULT '{}'::TEXT[]`,\n    ];\n\n    if (vec) {\n      // Trailing comma on the previous line to make this a valid column list.\n      columns[columns.length - 1] = columns[columns.length - 1] + \",\";\n      columns.push(`  embedding VECTOR(${vec.dimensions})`);\n    }\n\n    const lines = [\n      `CREATE TABLE IF NOT EXISTS ${t} (`,\n      ...columns,\n      `);`,\n      `CREATE INDEX IF NOT EXISTS idx_${t}_expires_at ON ${t} (expires_at);`,\n      `CREATE INDEX IF NOT EXISTS idx_${t}_tags ON ${t} USING GIN (tags);`,\n    ];\n\n    if (vec) {\n      const idx = vec.index ?? \"hnsw\";\n      lines.push(\n        `CREATE INDEX IF NOT EXISTS idx_${t}_embedding ON ${t} USING ${idx} (embedding vector_cosine_ops);`,\n      );\n    }\n\n    return lines.join(\"\\n\");\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async connect() {\n    // No-op — caller owns the connection. We emit `connected` for symmetry\n    // with the other drivers' lifecycle events.\n    this.log(\"connecting\");\n    this.log(\"connected\");\n    await this.emit(\"connected\");\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Does NOT close the user-supplied client — lifecycle stays with the caller.\n   */\n  public async disconnect() {\n    this.log(\"disconnected\");\n    await this.emit(\"disconnected\");\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      if (!this.options.vector) {\n        throw new CacheUnsupportedError(\n          \"'pg' driver: cannot index a vector without options.vector configuration — set { dimensions } and recreate the table via driver.schema().\",\n        );\n      }\n\n      const expected = this.options.vector.dimensions;\n      if (vector.length !== expected) {\n        throw new CacheConfigurationError(\n          `Pg cache driver: vector dimension mismatch — expected ${expected}, got ${vector.length}.`,\n        );\n      }\n\n      await this.ensureVectorReady();\n    }\n\n    this.log(\"caching\", parsedKey);\n\n    const expiresAt = this.ttlToSeconds(ttl);\n    const staleAtDate = staleAt !== undefined ? new Date(staleAt) : null;\n    const tagsArr = tags ?? [];\n    const serialized = JSON.stringify(value);\n    const vecLiteral = vector ? this.formatVector(vector) : null;\n\n    const t = this.table;\n\n    // Build column / placeholder / param triplets dynamically so the same code\n    // path serves both KV-only and vector-aware writes. Param order is fixed:\n    //   $1 = key, $2 = value (jsonb), $3 = ttl seconds (expires_at = now() + make_interval), $4 = stale_at,\n    //   $5 = tags, $6 = embedding::vector (only present when vecLiteral !== null).\n    const cols = [\"key\", \"value\", \"expires_at\", \"stale_at\", \"tags\"];\n    const placeholders = [\n      \"$1\",\n      \"$2::jsonb\",\n      \"now() + make_interval(secs => $3::double precision)\",\n      \"$4\",\n      \"$5\",\n    ];\n    const params: unknown[] = [parsedKey, serialized, expiresAt, staleAtDate, tagsArr];\n    if (vecLiteral !== null) {\n      cols.push(\"embedding\");\n      placeholders.push(`$${params.length + 1}::vector`);\n      params.push(vecLiteral);\n    }\n    const colList = cols.join(\", \");\n    const valList = placeholders.join(\", \");\n    const setClause = cols\n      .slice(1)\n      .map((c) => `${c} = EXCLUDED.${c}`)\n      .join(\", \");\n    const updateSetClause = cols\n      .slice(1)\n      .map((c, i) => `${c} = ${placeholders[i + 1]}`)\n      .join(\", \");\n\n    if (onConflict === \"create\") {\n      // Race-safe insert: if another worker already holds the key (and the row\n      // hasn't expired), DO NOTHING; we then SELECT to surface the existing value.\n      const { rows } = await this.pgClient.query(\n        `INSERT INTO ${t}(${colList})\n         VALUES (${valList})\n         ON CONFLICT (key) DO UPDATE\n           SET ${setClause}\n           WHERE ${t}.expires_at IS NOT NULL AND ${t}.expires_at < now()\n         RETURNING value`,\n        params,\n      );\n\n      if (rows.length === 0) {\n        // Conflict + existing row not expired → fetch existing for the result.\n        const existing = await this.get(key);\n        return { wasSet: false, existing } satisfies CacheSetResult;\n      }\n\n      if (tags && tags.length > 0) {\n        await this.applyTags(key, tags);\n      }\n\n      this.log(\"cached\", parsedKey);\n      this.maybePrune();\n      await this.emit(\"set\", { key: parsedKey, value, ttl });\n      return { wasSet: true, existing: null } satisfies CacheSetResult;\n    }\n\n    if (onConflict === \"update\") {\n      // Update only when the key exists AND hasn't expired.\n      const { rows } = await this.pgClient.query(\n        `UPDATE ${t}\n         SET ${updateSetClause}\n         WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())\n         RETURNING value`,\n        params,\n      );\n\n      if (rows.length === 0) {\n        return { wasSet: false, existing: null } satisfies CacheSetResult;\n      }\n\n      if (tags && tags.length > 0) {\n        await this.applyTags(key, tags);\n      }\n\n      this.log(\"cached\", parsedKey);\n      this.maybePrune();\n      await this.emit(\"set\", { key: parsedKey, value, ttl });\n      return { wasSet: true, existing: null } satisfies CacheSetResult;\n    }\n\n    // upsert (default)\n    await this.pgClient.query(\n      `INSERT INTO ${t}(${colList})\n       VALUES (${valList})\n       ON CONFLICT (key) DO UPDATE\n         SET ${setClause}`,\n      params,\n    );\n\n    if (tags && tags.length > 0) {\n      await this.applyTags(key, tags);\n    }\n\n    this.log(\"cached\", parsedKey);\n    this.maybePrune();\n    await this.emit(\"set\", { key: parsedKey, value, ttl });\n    return value;\n  }\n\n  /**\n   * {@inheritdoc}\n   */\n  public async get(key: CacheKey) {\n    const parsedKey = this.parseKey(key);\n    this.log(\"fetching\", parsedKey);\n\n    const t = this.table;\n    const { rows } = await this.pgClient.query(\n      `SELECT value FROM ${t}\n       WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())`,\n      [parsedKey],\n    );\n\n    if (rows.length === 0) {\n      this.log(\"notFound\", parsedKey);\n      await this.emit(\"miss\", { key: parsedKey });\n      return null;\n    }\n\n    this.log(\"fetched\", parsedKey);\n\n    // pg's JSONB type round-trips through node-postgres as a parsed JS value\n    // already — but some pool implementations may hand back a string. Be defensive.\n    let value = rows[0].value;\n    if (typeof value === \"string\") {\n      try {\n        value = JSON.parse(value);\n      } catch {\n        // Leave it as-is; cloning below will fail loud if it's truly broken.\n      }\n    }\n\n    if (value === null || value === undefined) {\n      await this.emit(\"hit\", { key: parsedKey, value });\n      return value;\n    }\n\n    const type = typeof value;\n    if (type === \"string\" || type === \"number\" || type === \"boolean\") {\n      await this.emit(\"hit\", { key: parsedKey, value });\n      return value;\n    }\n\n    try {\n      const cloned = structuredClone(value);\n      await this.emit(\"hit\", { key: parsedKey, value: cloned });\n      return cloned;\n    } catch (error) {\n      this.logError(`Failed to clone cached value for ${parsedKey}`, error);\n      throw error;\n    }\n  }\n\n  /**\n   * Read the raw {@link CacheData} wrapper, including `staleAt` metadata.\n   * Returns `null` for missing or expired rows — `swr()` consumes this to\n   * branch on freshness without going through `get()`'s clone-and-emit path.\n   */\n  protected async getEntry(key: CacheKey): Promise<CacheData | null> {\n    const parsedKey = this.parseKey(key);\n    const t = this.table;\n\n    const { rows } = await this.pgClient.query(\n      `SELECT value, expires_at, stale_at FROM ${t}\n       WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())`,\n      [parsedKey],\n    );\n\n    if (rows.length === 0) {\n      return null;\n    }\n\n    let data = rows[0].value;\n    if (typeof data === \"string\") {\n      try {\n        data = JSON.parse(data);\n      } catch {\n        // Leave as-is — getEntry is metadata-shaped, the caller will hit the\n        // same parse path on the public `get()` if they care.\n      }\n    }\n\n    const entry: CacheData = { data };\n\n    const expiresAtRaw = rows[0].expires_at as Date | string | null;\n    if (expiresAtRaw) {\n      const expiresAt = expiresAtRaw instanceof Date ? expiresAtRaw : new Date(expiresAtRaw);\n      entry.expiresAt = expiresAt.getTime();\n    }\n\n    const staleAtRaw = rows[0].stale_at as Date | string | null;\n    if (staleAtRaw) {\n      const staleAt = staleAtRaw instanceof Date ? staleAtRaw : new Date(staleAtRaw);\n      entry.staleAt = staleAt.getTime();\n    }\n\n    return entry;\n  }\n\n  /**\n   * Decode a JSONB column value (node-postgres usually parses it already;\n   * some pools hand back a string).\n   */\n  protected decodeJson(value: unknown): any {\n    if (typeof value === \"string\") {\n      try {\n        return JSON.parse(value);\n      } catch {\n        return value;\n      }\n    }\n\n    return value;\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * One atomic `INSERT … ON CONFLICT DO UPDATE` statement, so concurrent\n   * increments from any number of servers never lose an update. A live row\n   * keeps its `expires_at`; a missing or expired row restarts from `value`\n   * with the driver default TTL. A non-numeric live value is rejected.\n   */\n  public async increment(key: CacheKey, value: number = 1): Promise<number> {\n    const parsedKey = this.parseKey(key);\n    const t = this.table;\n    const expired = `${t}.expires_at IS NOT NULL AND ${t}.expires_at <= now()`;\n\n    const { rows } = await this.pgClient.query(\n      `/* cache:increment */ INSERT INTO ${t}(key, value, expires_at)\n       VALUES ($1, to_jsonb($2::numeric), now() + make_interval(secs => $3::double precision))\n       ON CONFLICT (key) DO UPDATE\n         SET value = CASE WHEN ${expired} THEN EXCLUDED.value\n                          ELSE to_jsonb((${t}.value #>> '{}')::numeric + $2::numeric) END,\n             expires_at = CASE WHEN ${expired} THEN EXCLUDED.expires_at ELSE ${t}.expires_at END,\n             stale_at = CASE WHEN ${expired} THEN NULL ELSE ${t}.stale_at END\n         WHERE (${expired}) OR jsonb_typeof(${t}.value) = 'number'\n       RETURNING value`,\n      [parsedKey, value, this.ttlToSeconds(this.ttl)],\n    );\n\n    if (rows.length === 0) {\n      throw new Error(`Cannot increment non-numeric value for key: ${parsedKey}`);\n    }\n\n    const newValue = Number(this.decodeJson(rows[0].value));\n\n    await this.emit(\"set\", { key: parsedKey, value: newValue, ttl: this.ttl });\n\n    return newValue;\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * One atomic `DELETE … RETURNING`, so a value is handed out exactly once\n   * across servers. Expired rows count as missing.\n   */\n  public async pull(key: CacheKey): Promise<any | null> {\n    const parsedKey = this.parseKey(key);\n\n    const { rows } = await this.pgClient.query(\n      `/* cache:pull */ DELETE FROM ${this.table}\n       WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())\n       RETURNING value`,\n      [parsedKey],\n    );\n\n    if (rows.length === 0) {\n      await this.emit(\"miss\", { key: parsedKey });\n\n      return null;\n    }\n\n    const value = this.decodeJson(rows[0].value);\n\n    await this.emit(\"hit\", { key: parsedKey, value });\n    await this.emit(\"removed\", { key: parsedKey });\n\n    return value;\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Atomic across servers via optimistic compare-and-set: read the live value,\n   * run `fn`, then write with `UPDATE … WHERE value = <what was read>` (or a\n   * create-only insert for a missing key), retrying when another writer got\n   * there first. `fn` may run more than once under contention; after\n   * {@link PG_UPDATE_MAX_ATTEMPTS} lost races it throws {@link CacheError}.\n   *\n   * Without an explicit `ttl` the row keeps its `expires_at`; a new key gets\n   * the driver default TTL. Returning `null` deletes the key (compare-and-delete).\n   */\n  public async update<T = any>(\n    key: CacheKey,\n    fn: (current: T | null) => T | null | Promise<T | null>,\n    options: { ttl?: CacheTtl } = {},\n  ): Promise<T | null> {\n    const parsedKey = this.parseKey(key);\n    const t = this.table;\n    const live = `(expires_at IS NULL OR expires_at > now())`;\n    const explicitTtl = options.ttl !== undefined ? parseTtl(options.ttl) : undefined;\n\n    for (let attempt = 0; attempt < PG_UPDATE_MAX_ATTEMPTS; attempt++) {\n      const read = await this.pgClient.query(\n        `SELECT value FROM ${t}\n         WHERE key = $1 AND ${live}`,\n        [parsedKey],\n      );\n\n      const exists = read.rows.length > 0;\n      const current = exists ? (this.decodeJson(read.rows[0].value) as T) : null;\n      const expected = exists ? JSON.stringify(current) : null;\n      const result = await fn(current);\n\n      if (result === null) {\n        if (!exists) {\n          return null;\n        }\n\n        const deleted = await this.pgClient.query(\n          `/* cache:cas-delete */ DELETE FROM ${t}\n           WHERE key = $1 AND value = $2::jsonb AND ${live}\n           RETURNING 1`,\n          [parsedKey, expected],\n        );\n\n        if (deleted.rows.length > 0) {\n          await this.emit(\"removed\", { key: parsedKey });\n\n          return null;\n        }\n\n        continue;\n      }\n\n      if (!exists) {\n        const created = (await this.set(key, result, {\n          onConflict: \"create\",\n          ...(explicitTtl !== undefined ? { ttl: explicitTtl } : {}),\n        })) as CacheSetResult;\n\n        if (created.wasSet) {\n          return result;\n        }\n\n        continue;\n      }\n\n      const params: unknown[] = [parsedKey, JSON.stringify(result), expected];\n      let expirySql = \"\";\n\n      if (explicitTtl !== undefined) {\n        params.push(this.ttlToSeconds(explicitTtl));\n        expirySql = `, expires_at = now() + make_interval(secs => $4::double precision)`;\n      }\n\n      const updated = await this.pgClient.query(\n        `/* cache:cas-update */ UPDATE ${t}\n         SET value = $2::jsonb, stale_at = NULL${expirySql}\n         WHERE key = $1 AND value = $3::jsonb AND ${live}\n         RETURNING 1`,\n        params,\n      );\n\n      if (updated.rows.length > 0) {\n        await this.emit(\"set\", { key: parsedKey, value: result, ttl: explicitTtl });\n\n        return result;\n      }\n    }\n\n    throw new CacheError(\n      `cache.update(): '${parsedKey}' changed on every attempt (${PG_UPDATE_MAX_ATTEMPTS} tries) — too much write contention.`,\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 t = this.table;\n    await this.pgClient.query(`DELETE FROM ${t} WHERE key = $1`, [parsedKey]);\n\n    this.log(\"removed\", parsedKey);\n    await this.emit(\"removed\", { key: parsedKey });\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Deletes all rows whose key equals the namespace exactly or starts with\n   * `<namespace>.` — same boundary semantics as the other drivers.\n   */\n  public async removeNamespace(namespace: string) {\n    const parsed = this.parseKey(namespace);\n    this.log(\"clearing\", parsed || \"(all)\");\n\n    const t = this.table;\n\n    if (parsed === \"\") {\n      await this.pgClient.query(`DELETE FROM ${t}`);\n    } else {\n      // Escape `_` and `%` in the prefix so they aren't treated as LIKE wildcards.\n      const escaped = parsed.replace(/\\\\/g, \"\\\\\\\\\").replace(/_/g, \"\\\\_\").replace(/%/g, \"\\\\%\");\n      await this.pgClient.query(`DELETE FROM ${t} WHERE key = $1 OR key LIKE $2 ESCAPE '\\\\'`, [\n        parsed,\n        `${escaped}.%`,\n      ]);\n    }\n\n    this.log(\"cleared\", parsed || \"(all)\");\n    return this;\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * Honors `globalPrefix` — when configured, scopes the flush to entries\n   * under the prefix rather than truncating the entire table (which could\n   * wipe sibling tenants sharing the same Postgres database).\n   */\n  public async flush() {\n    this.log(\"flushing\");\n\n    if (this.options.globalPrefix) {\n      await this.removeNamespace(\"\");\n    } else {\n      await this.pgClient.query(`DELETE FROM ${this.table}`);\n    }\n\n    this.log(\"flushed\");\n    await this.emit(\"flushed\");\n  }\n\n  /**\n   * {@inheritdoc}\n   *\n   * pgvector-backed similarity. Uses the `<=>` cosine-distance operator\n   * (lower distance = higher similarity) and converts to cosine similarity\n   * as `1 - distance` so the returned `score` matches the rest of the\n   * package (`[0, 1]`, higher is more similar).\n   *\n   * Honors `topK`, `threshold`, and an optional `tags` filter (native\n   * `tags && $tags` overlap query — much faster than the meta-key path).\n   *\n   * Throws {@link CacheUnsupportedError} when `options.vector` was not\n   * configured at driver setup; throws {@link CacheConfigurationError} when\n   * the pgvector extension is missing or the query vector's dimension count\n   * doesn't match the configured one.\n   */\n  public async similar<T = any>(\n    vector: number[],\n    options: CacheSimilarOptions,\n  ): Promise<CacheSimilarHit<T>[]> {\n    if (!this.options.vector) {\n      throw new CacheUnsupportedError(\n        \"'pg' driver: similarity retrieval requires the 'vector' config block. Set options.vector.dimensions and reconnect.\",\n      );\n    }\n\n    const expected = this.options.vector.dimensions;\n    if (vector.length !== expected) {\n      throw new CacheConfigurationError(\n        `Pg cache driver: vector dimension mismatch — expected ${expected}, got ${vector.length}.`,\n      );\n    }\n\n    if (!Number.isInteger(options.topK) || options.topK <= 0) {\n      throw new CacheConfigurationError(\n        `Pg cache driver: similar.topK must be a positive integer; got ${options.topK}.`,\n      );\n    }\n\n    await this.ensureVectorReady();\n\n    const t = this.table;\n    const vecLiteral = this.formatVector(vector);\n    const params: unknown[] = [vecLiteral];\n    let tagFilter = \"\";\n\n    if (options.tags && options.tags.length > 0) {\n      params.push(options.tags);\n      tagFilter = `AND tags && $${params.length}`;\n    }\n\n    params.push(options.topK);\n    const topKParam = `$${params.length}`;\n\n    const { rows } = await this.pgClient.query(\n      `SELECT key, value, 1 - (embedding <=> $1::vector) AS score\n       FROM ${t}\n       WHERE embedding IS NOT NULL\n         AND (expires_at IS NULL OR expires_at > now())\n         ${tagFilter}\n       ORDER BY embedding <=> $1::vector\n       LIMIT ${topKParam}`,\n      params,\n    );\n\n    const hits: CacheSimilarHit<T>[] = [];\n    for (const row of rows) {\n      const score = Number(row.score);\n      if (options.threshold !== undefined && score < options.threshold) {\n        continue;\n      }\n\n      let value = row.value;\n      if (typeof value === \"string\") {\n        try {\n          value = JSON.parse(value);\n        } catch {\n          // Surface as-is; if non-JSON crept in, the consumer will notice.\n        }\n      }\n\n      // Match get() cloning semantics so consumers can't mutate cached state.\n      if (value !== null && value !== undefined) {\n        const ty = typeof value;\n        if (ty !== \"string\" && ty !== \"number\" && ty !== \"boolean\") {\n          value = structuredClone(value);\n        }\n      }\n\n      hits.push({ key: row.key, value, score });\n    }\n\n    return hits;\n  }\n}\n"],"mappings":"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"}

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

@@ -3,6 +3,22 @@ import { CacheData, CacheDriver, CacheKey, CacheSetOptions, CacheTtl, RedisOptio
 import { createClient } from "redis";
 
 //#region ../cache/src/drivers/redis-cache-driver.d.ts
+/** KEYS[1]=key, ARGV[1]=expected raw value. 1 when deleted, 0 when not the owner. */
+declare const REDIS_COMPARE_DELETE_SCRIPT = "if redis.call('GET', KEYS[1]) == ARGV[1] then redis.call('DEL', KEYS[1]) return 1 else return 0 end";
+/**
+ * Compare-and-set used by `update()`.
+ *
+ * KEYS[1]=key; ARGV[1]=expected raw value (ignored when ARGV[3]=='1');
+ * ARGV[2]=new raw value; ARGV[3]='1' when the key is expected to be missing;
+ * ARGV[4]=ttl seconds to apply ('0' = no expiry); ARGV[5]='keep' to keep the
+ * existing TTL instead (only when the key existed).
+ *
+ * Returns 1 when written, 0 when the current value no longer matches.
+ * `KEEPTTL` requires Redis >= 6.
+ */
+declare const REDIS_CAS_SET_SCRIPT = "local cur = redis.call('GET', KEYS[1])\nif ARGV[3] == '1' then\n  if cur then return 0 end\nelseif cur ~= ARGV[1] then\n  return 0\nend\nlocal ttl = tonumber(ARGV[4])\nif ARGV[5] == 'keep' and ARGV[3] ~= '1' then\n  redis.call('SET', KEYS[1], ARGV[2], 'KEEPTTL')\nelseif ttl > 0 then\n  redis.call('SET', KEYS[1], ARGV[2], 'EX', ttl)\nelse\n  redis.call('SET', KEYS[1], ARGV[2])\nend\nreturn 1";
+/** KEYS[1]=key. Fallback for clients without `getDel`: returns the value and deletes it. */
+declare const REDIS_GET_DEL_SCRIPT = "local v = redis.call('GET', KEYS[1])\nif v then redis.call('DEL', KEYS[1]) end\nreturn v";
 declare class RedisCacheDriver extends BaseCacheDriver<ReturnType<typeof createClient>, RedisOptions> implements CacheDriver<ReturnType<typeof createClient>, RedisOptions> {
   /**
    * Cache driver name
@@ -16,10 +32,53 @@ declare class RedisCacheDriver extends BaseCacheDriver<ReturnType<typeof createC
    * {@inheritDoc}
    */
   removeNamespace(namespace: string): Promise<string[] | undefined>;
+  /**
+   * Delete keys with `UNLINK` (non-blocking free), falling back to `DEL` when
+   * the client lacks it. Returns the number of keys removed.
+   */
+  protected deleteKeys(keys: string[]): Promise<number>;
+  /**
+   * {@inheritdoc}
+   *
+   * `SADD` — atomic across servers, so concurrent tagged writes on any number
+   * of instances never drop a member. The set key lives inside the prefix
+   * namespace, so `flush()` / `removeNamespace()` sweep it too.
+   */
+  tagAdd(tagKey: CacheKey, members: string[]): Promise<void>;
+  /**
+   * {@inheritdoc}
+   */
+  tagMembers(tagKey: CacheKey): Promise<string[]>;
+  /**
+   * {@inheritdoc}
+   *
+   * `SREM` — Redis drops the set once its last member is removed.
+   */
+  tagRemove(tagKey: CacheKey, members: string[]): Promise<void>;
+  /**
+   * {@inheritdoc}
+   */
+  tagDelete(tagKey: CacheKey): Promise<void>;
+  /**
+   * Run a SET command against a tag key, upgrading a pre-5.20 index first.
+   *
+   * Earlier versions stored the index as a JSON-array STRING under the same
+   * key, which makes any SET command fail with `WRONGTYPE`. On that error the
+   * legacy array is read, the string deleted, its members re-added with
+   * `SADD`, and the command retried once.
+   */
+  protected withTagSet<T>(parsedKey: string, run: (client: any) => Promise<T>): Promise<T>;
   /**
    * {@inheritDoc}
    */
   set(key: CacheKey, value: any, ttlOrOptions?: CacheTtl | CacheSetOptions): Promise<any>;
+  /**
+   * {@inheritdoc}
+   *
+   * Values are stored as `JSON.stringify(value)`, so the compare runs against
+   * the serialized form inside Lua.
+   */
+  protected deleteIfEquals(key: CacheKey, expected: unknown): Promise<boolean>;
   /**
    * Build the sidecar key Redis uses to track SWR freshness without
    * wrapping the main value JSON.
@@ -50,6 +109,10 @@ declare class RedisCacheDriver extends BaseCacheDriver<ReturnType<typeof createC
   remove(key: CacheKey): Promise<void>;
   /**
    * {@inheritDoc}
+   *
+   * WARNING: without a `globalPrefix` this runs `FLUSHDB`, which clears the
+   * WHOLE selected Redis database (including keys not written by this driver).
+   * Configure a `globalPrefix` to only delete this driver's keys.
    */
   flush(): Promise<void>;
   /**
@@ -65,6 +128,28 @@ declare class RedisCacheDriver extends BaseCacheDriver<ReturnType<typeof createC
    * would always be truthy and crash with "this.quit is not a function".
    */
   disconnect(): Promise<void>;
+  /**
+   * {@inheritdoc}
+   *
+   * Atomic across servers: `GETDEL` (Redis >= 6.2), or an equivalent Lua
+   * script when the client has no `getDel`. A value is handed out once.
+   */
+  pull(key: CacheKey): Promise<any | null>;
+  /**
+   * {@inheritdoc}
+   *
+   * Atomic across servers via optimistic compare-and-set: read the raw value,
+   * run `fn`, then write only if the value is still what was read (Lua), and
+   * retry otherwise. `fn` may therefore run more than once under contention;
+   * after {@link UPDATE_MAX_ATTEMPTS} lost races it throws {@link CacheError}.
+   *
+   * Without an explicit `ttl` the existing expiry is kept (`KEEPTTL`); a new
+   * key gets the driver default TTL. Returning `null` deletes the key
+   * (compare-and-delete).
+   */
+  update<T = any>(key: CacheKey, fn: (current: T | null) => T | null | Promise<T | null>, options?: {
+    ttl?: CacheTtl;
+  }): Promise<T | null>;
   /**
    * Atomic increment using Redis native INCRBY command
    * {@inheritdoc}
@@ -82,5 +167,5 @@ declare class RedisCacheDriver extends BaseCacheDriver<ReturnType<typeof createC
   setNX(key: CacheKey, value: any, ttl?: number): Promise<boolean>;
 }
 //#endregion
-export { RedisCacheDriver };
+export { REDIS_CAS_SET_SCRIPT, REDIS_COMPARE_DELETE_SCRIPT, REDIS_GET_DEL_SCRIPT, RedisCacheDriver };
 //# sourceMappingURL=redis-cache-driver.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"redis-cache-driver.d.mts","names":[],"sources":["../../../../../../../cache/src/drivers/redis-cache-driver.ts"],"mappings":";;;;;cA2Da,gBAAA,SACH,eAAA,CAAgB,UAAA,QAAkB,YAAA,GAAe,YAAA,aAC9C,WAAA,CAAY,UAAA,QAAkB,YAAA,GAAe,YAAA;;AAF1D;;EAOS,IAAA;EANmC;;;EAWnC,UAAA,CAAW,OAAA,EAAS,YAAA;EAVJ;;;EAuBV,eAAA,CAAgB,SAAA,WAAiB,OAAA;EAuCvC;;;EADM,GAAA,CACX,GAAA,EAAK,QAAA,EACL,KAAA,OACA,YAAA,GAAe,QAAA,GAAW,eAAA,GACzB,OAAA;EAmF2B;;;;EAAA,UAVpB,UAAA,CAAW,SAAA;EAqDC;;;;;;EAAA,UA3CN,QAAA,CAAS,GAAA,EAAK,QAAA,GAAW,OAAA,CAAQ,SAAA;EAiNrB;;;;;;;EAAA,UAxLZ,eAAA,CAAgB,GAAA,EAAK,QAAA,GAAW,OAAA;EA7K1B;;;EA+LT,GAAA,CAAI,GAAA,EAAK,QAAA,GAAQ,OAAA;EAhMY;;;EA+O7B,MAAA,CAAO,GAAA,EAAK,QAAA,GAAQ,OAAA;EA9OQ;;;EA+P5B,KAAA,IAAK,OAAA;EArPS;;;EAuQd,OAAA,IAAO,OAAA;EA1P0B;;;;;;;;EA6TjC,UAAA,IAAU,OAAA;EA1Mb;;;;EA2NG,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAoB,OAAA;EAjNjB;;;;EAoO5B,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAoB,OAAA;EA3MV;;;;EA8NnC,KAAA,CAAM,GAAA,EAAK,QAAA,EAAU,KAAA,OAAY,GAAA,YAAe,OAAA;AAAA"}
+{"version":3,"file":"redis-cache-driver.d.mts","names":[],"sources":["../../../../../../../cache/src/drivers/redis-cache-driver.ts"],"mappings":";;;;;;cA4Da,2BAAA;AAAb;;;;AAAwC;AAaxC;;;;AAAiC;AAiBjC;AA9BA,cAaa,oBAAA;;cAiBA,oBAAA;AAAA,cAcA,gBAAA,SACH,eAAA,CAAgB,UAAA,QAAkB,YAAA,GAAe,YAAA,aAC9C,WAAA,CAAY,UAAA,QAAkB,YAAA,GAAe,YAAA;EAF7C;;;EAOJ,IAAA;EANiB;;;EAWjB,UAAA,CAAW,OAAA,EAAS,YAAA;EAV6B;;;EAuB3C,eAAA,CAAgB,SAAA,WAAiB,OAAA;EA2FlB;;;;EAAA,UArBZ,UAAA,CAAW,IAAA,aAAiB,OAAA;EA6CiB;;;;;;;EAxBhD,MAAA,CAAO,MAAA,EAAQ,QAAA,EAAU,OAAA,aAAoB,OAAA;EAwFzC;;;EA3EJ,UAAA,CAAW,MAAA,EAAQ,QAAA,GAAW,OAAA;EA2JuB;;;;;EAhJrD,SAAA,CAAU,MAAA,EAAQ,QAAA,EAAU,OAAA,aAAoB,OAAA;EA4NvC;;;EA/MT,SAAA,CAAU,MAAA,EAAQ,QAAA,GAAW,OAAA;EAqRxB;;;;;;;;EAAA,UAzQF,UAAA,IAAc,SAAA,UAAmB,GAAA,GAAM,MAAA,UAAgB,OAAA,CAAQ,CAAA,IAAK,OAAA,CAAQ,CAAA;EA6ZpD;;;EAzX3B,GAAA,CACX,GAAA,EAAK,QAAA,EACL,KAAA,OACA,YAAA,GAAe,QAAA,GAAW,eAAA,GACzB,OAAA;EAubyB;;;;;;EAAA,UAxWZ,cAAA,CAAe,GAAA,EAAK,QAAA,EAAU,QAAA,YAAoB,OAAA;EA1RvD;;;;EAAA,UAiTD,UAAA,CAAW,SAAA;EAlTqB;;;;;;EAAA,UA4T1B,QAAA,CAAS,GAAA,EAAK,QAAA,GAAW,OAAA,CAAQ,SAAA;EAjT1C;;;;;;;EAAA,UA0US,eAAA,CAAgB,GAAA,EAAK,QAAA,GAAW,OAAA;EAvPJ;;;EAyQ/B,GAAA,CAAI,GAAA,EAAK,QAAA,GAAQ,OAAA;EApPQ;;;EAmSzB,MAAA,CAAO,GAAA,EAAK,QAAA,GAAQ,OAAA;EAtRT;;;;;;;EA6SX,KAAA,IAAK,OAAA;EArRa;;;EAuSlB,OAAA,IAAO,OAAA;EA3RO;;;;;;;;EAmWd,UAAA,IAAU,OAAA;EA9ThB;;;;;;EAiVM,IAAA,CAAK,GAAA,EAAK,QAAA,GAAW,OAAA;EA/PlB;;;;;;;;;;;;EAoSH,MAAA,UACX,GAAA,EAAK,QAAA,EACL,EAAA,GAAK,OAAA,EAAS,CAAA,YAAa,CAAA,UAAW,OAAA,CAAQ,CAAA,UAC9C,OAAA;IAAW,GAAA,GAAM,QAAA;EAAA,IAChB,OAAA,CAAQ,CAAA;EA9OqC;;;;EA8SnC,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAoB,OAAA;EA7O7C;;;;EAqQA,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAoB,OAAA;EA9OxC;;;;EAiQL,KAAA,CAAM,GAAA,EAAK,QAAA,EAAU,KAAA,OAAY,GAAA,YAAe,OAAA;AAAA"}