@warlock.js/cache 4.0.171 → 4.1.1

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

@@ -0,0 +1,437 @@
+import { CacheConfigurationError, CacheUnsupportedError } from "../types.mjs";
+import { BaseCacheDriver } from "./base-cache-driver.mjs";
+
+//#region ../../@warlock.js/cache/src/drivers/pg-cache-driver.ts
+/**
+* Allowed characters in a Postgres identifier (table name). We accept the
+* conservative ASCII subset and reject anything else — interpolating an
+* arbitrary string into DDL would be a SQL-injection footgun.
+*/
+const SAFE_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+* Postgres cache driver with optional pgvector similarity support.
+*
+* Connection lifecycle is the caller's responsibility — pass an already-built
+* `pg.Pool` or `pg.Client` via the `client` option. The driver never closes it
+* on `cache.disconnect()`, so the same pool can serve queries elsewhere in
+* the app.
+*
+* Schema is not auto-migrated. Call `driver.schema()` to get the DDL string
+* and run it through whichever migration tool you use.
+*
+* @example
+* import { Pool } from "pg";
+* import { cache, PgCacheDriver } from "@warlock.js/cache";
+*
+* const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+*
+* cache.setCacheConfigurations({
+*   default: "pg",
+*   drivers: { pg: PgCacheDriver },
+*   options: { pg: { client: pool, table: "warlock_cache", ttl: "1h" } },
+* });
+*
+* await cache.init();
+*
+* // Run once, via your own migration tooling:
+* // await pool.query(driver.schema());
+*/
+var PgCacheDriver = class extends BaseCacheDriver {
+	constructor(..._args) {
+		super(..._args);
+		this.name = "pg";
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Validates `client` presence and the table name before storing options.
+	*/
+	setOptions(options) {
+		if (!options || !options.client || typeof options.client.query !== "function") throw new CacheConfigurationError("Pg cache driver requires a 'client' option implementing { query(text, values) } — pass a pg.Pool or pg.Client.");
+		const table = options.table ?? "warlock_cache";
+		if (!SAFE_IDENT.test(table)) throw new CacheConfigurationError(`Pg cache driver: invalid table name '${table}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`);
+		if (options.vector) {
+			const dim = options.vector.dimensions;
+			if (!Number.isInteger(dim) || dim <= 0) throw new CacheConfigurationError(`Pg cache driver: vector.dimensions must be a positive integer; got ${dim}.`);
+			const idx = options.vector.index ?? "hnsw";
+			if (idx !== "hnsw" && idx !== "ivfflat") throw new CacheConfigurationError(`Pg cache driver: vector.index must be 'hnsw' or 'ivfflat'; got '${idx}'.`);
+		}
+		return super.setOptions({
+			...options,
+			table
+		});
+	}
+	/**
+	* Lazy pgvector availability check. Runs once on the first vector op and
+	* caches the result — subsequent ops are zero-overhead. Throws
+	* {@link CacheConfigurationError} if the extension isn't installed; throws
+	* {@link CacheUnsupportedError} if `vector` config wasn't provided at all.
+	*/
+	async ensureVectorReady() {
+		if (!this.options.vector) throw new CacheUnsupportedError("'pg' driver: similarity retrieval requires the 'vector' config block. Set options.vector.dimensions and reconnect.");
+		if (this.vectorReady === true) return;
+		const { rows } = await this.pgClient.query(`SELECT 1 FROM pg_extension WHERE extname = 'vector'`);
+		if (rows.length === 0) throw new CacheConfigurationError("'pg' driver: pgvector extension not installed. Run 'CREATE EXTENSION vector;' or remove the 'vector' config option.");
+		this.vectorReady = true;
+	}
+	/**
+	* Format a numeric vector for pgvector ingestion. The `vector` type accepts
+	* a string literal `'[1,2,3]'` cast via `::vector` — this avoids depending
+	* on the binary protocol and works against any pg client.
+	*/
+	formatVector(vector) {
+		return `[${vector.join(",")}]`;
+	}
+	/**
+	* Resolved table name. Always defined post-`setOptions` — the validator
+	* fills in the default.
+	*/
+	get table() {
+		return this.options.table ?? "warlock_cache";
+	}
+	/**
+	* The user-supplied `pg.Pool` / `pg.Client`. Use this rather than `this.client`
+	* (which has a generic fallback to `this`) for actual queries.
+	*/
+	get pgClient() {
+		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).
+	*/
+	ttlToExpiresAt(ttl) {
+		if (!ttl || ttl === Infinity) return null;
+		return new Date(Date.now() + ttl * 1e3);
+	}
+	/**
+	* Return the SQL needed to provision the cache table + index. Run once via
+	* the caller's migration tooling — the driver never auto-migrates.
+	*
+	* @example
+	* await pool.query(driver.schema());
+	*/
+	schema() {
+		const t = this.table;
+		const vec = this.options.vector;
+		const columns = [
+			`  key TEXT PRIMARY KEY,`,
+			`  value JSONB NOT NULL,`,
+			`  expires_at TIMESTAMPTZ,`,
+			`  stale_at TIMESTAMPTZ,`,
+			`  tags TEXT[] NOT NULL DEFAULT '{}'::TEXT[]`
+		];
+		if (vec) {
+			columns[columns.length - 1] = columns[columns.length - 1] + ",";
+			columns.push(`  embedding VECTOR(${vec.dimensions})`);
+		}
+		const lines = [
+			`CREATE TABLE IF NOT EXISTS ${t} (`,
+			...columns,
+			`);`,
+			`CREATE INDEX IF NOT EXISTS idx_${t}_expires_at ON ${t} (expires_at);`,
+			`CREATE INDEX IF NOT EXISTS idx_${t}_tags ON ${t} USING GIN (tags);`
+		];
+		if (vec) {
+			const idx = vec.index ?? "hnsw";
+			lines.push(`CREATE INDEX IF NOT EXISTS idx_${t}_embedding ON ${t} USING ${idx} (embedding vector_cosine_ops);`);
+		}
+		return lines.join("\n");
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async connect() {
+		this.log("connecting");
+		this.log("connected");
+		await this.emit("connected");
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Does NOT close the user-supplied client — lifecycle stays with the caller.
+	*/
+	async disconnect() {
+		this.log("disconnected");
+		await this.emit("disconnected");
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async set(key, value, ttlOrOptions) {
+		const parsedKey = this.parseKey(key);
+		const { ttl, tags, onConflict, vector, staleAt } = this.resolveSetOptions(ttlOrOptions);
+		if (vector) {
+			if (!this.options.vector) throw new CacheUnsupportedError("'pg' driver: cannot index a vector without options.vector configuration — set { dimensions } and recreate the table via driver.schema().");
+			const expected = this.options.vector.dimensions;
+			if (vector.length !== expected) throw new CacheConfigurationError(`Pg cache driver: vector dimension mismatch — expected ${expected}, got ${vector.length}.`);
+			await this.ensureVectorReady();
+		}
+		this.log("caching", parsedKey);
+		const expiresAt = this.ttlToExpiresAt(ttl);
+		const staleAtDate = staleAt !== void 0 ? new Date(staleAt) : null;
+		const tagsArr = tags ?? [];
+		const serialized = JSON.stringify(value);
+		const vecLiteral = vector ? this.formatVector(vector) : null;
+		const t = this.table;
+		const cols = [
+			"key",
+			"value",
+			"expires_at",
+			"stale_at",
+			"tags"
+		];
+		const placeholders = [
+			"$1",
+			"$2::jsonb",
+			"$3",
+			"$4",
+			"$5"
+		];
+		const params = [
+			parsedKey,
+			serialized,
+			expiresAt,
+			staleAtDate,
+			tagsArr
+		];
+		if (vecLiteral !== null) {
+			cols.push("embedding");
+			placeholders.push(`$${params.length + 1}::vector`);
+			params.push(vecLiteral);
+		}
+		const colList = cols.join(", ");
+		const valList = placeholders.join(", ");
+		const setClause = cols.slice(1).map((c) => `${c} = EXCLUDED.${c}`).join(", ");
+		const updateSetClause = cols.slice(1).map((c, i) => `${c} = ${placeholders[i + 1]}`).join(", ");
+		if (onConflict === "create") {
+			const { rows } = await this.pgClient.query(`INSERT INTO ${t}(${colList})
+         VALUES (${valList})
+         ON CONFLICT (key) DO UPDATE
+           SET ${setClause}
+           WHERE ${t}.expires_at IS NOT NULL AND ${t}.expires_at < now()
+         RETURNING value`, params);
+			if (rows.length === 0) return {
+				wasSet: false,
+				existing: await this.get(key)
+			};
+			if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+			this.log("cached", parsedKey);
+			await this.emit("set", {
+				key: parsedKey,
+				value,
+				ttl
+			});
+			return {
+				wasSet: true,
+				existing: null
+			};
+		}
+		if (onConflict === "update") {
+			const { rows } = await this.pgClient.query(`UPDATE ${t}
+         SET ${updateSetClause}
+         WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())
+         RETURNING value`, params);
+			if (rows.length === 0) return {
+				wasSet: false,
+				existing: null
+			};
+			if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+			this.log("cached", parsedKey);
+			await this.emit("set", {
+				key: parsedKey,
+				value,
+				ttl
+			});
+			return {
+				wasSet: true,
+				existing: null
+			};
+		}
+		await this.pgClient.query(`INSERT INTO ${t}(${colList})
+       VALUES (${valList})
+       ON CONFLICT (key) DO UPDATE
+         SET ${setClause}`, params);
+		if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+		this.log("cached", parsedKey);
+		await this.emit("set", {
+			key: parsedKey,
+			value,
+			ttl
+		});
+		return value;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async get(key) {
+		const parsedKey = this.parseKey(key);
+		this.log("fetching", parsedKey);
+		const t = this.table;
+		const { rows } = await this.pgClient.query(`SELECT value FROM ${t}
+       WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())`, [parsedKey]);
+		if (rows.length === 0) {
+			this.log("notFound", parsedKey);
+			await this.emit("miss", { key: parsedKey });
+			return null;
+		}
+		this.log("fetched", parsedKey);
+		let value = rows[0].value;
+		if (typeof value === "string") try {
+			value = JSON.parse(value);
+		} catch {}
+		if (value === null || value === void 0) {
+			await this.emit("hit", {
+				key: parsedKey,
+				value
+			});
+			return value;
+		}
+		const type = typeof value;
+		if (type === "string" || type === "number" || type === "boolean") {
+			await this.emit("hit", {
+				key: parsedKey,
+				value
+			});
+			return value;
+		}
+		try {
+			const cloned = structuredClone(value);
+			await this.emit("hit", {
+				key: parsedKey,
+				value: cloned
+			});
+			return cloned;
+		} catch (error) {
+			this.logError(`Failed to clone cached value for ${parsedKey}`, error);
+			throw error;
+		}
+	}
+	/**
+	* Read the raw {@link CacheData} wrapper, including `staleAt` metadata.
+	* Returns `null` for missing or expired rows — `swr()` consumes this to
+	* branch on freshness without going through `get()`'s clone-and-emit path.
+	*/
+	async getEntry(key) {
+		const parsedKey = this.parseKey(key);
+		const t = this.table;
+		const { rows } = await this.pgClient.query(`SELECT value, expires_at, stale_at FROM ${t}
+       WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())`, [parsedKey]);
+		if (rows.length === 0) return null;
+		let data = rows[0].value;
+		if (typeof data === "string") try {
+			data = JSON.parse(data);
+		} catch {}
+		const entry = { data };
+		const expiresAtRaw = rows[0].expires_at;
+		if (expiresAtRaw) entry.expiresAt = (expiresAtRaw instanceof Date ? expiresAtRaw : new Date(expiresAtRaw)).getTime();
+		const staleAtRaw = rows[0].stale_at;
+		if (staleAtRaw) entry.staleAt = (staleAtRaw instanceof Date ? staleAtRaw : new Date(staleAtRaw)).getTime();
+		return entry;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async remove(key) {
+		const parsedKey = this.parseKey(key);
+		this.log("removing", parsedKey);
+		const t = this.table;
+		await this.pgClient.query(`DELETE FROM ${t} WHERE key = $1`, [parsedKey]);
+		this.log("removed", parsedKey);
+		await this.emit("removed", { key: parsedKey });
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Deletes all rows whose key equals the namespace exactly or starts with
+	* `<namespace>.` — same boundary semantics as the other drivers.
+	*/
+	async removeNamespace(namespace) {
+		const parsed = this.parseKey(namespace);
+		this.log("clearing", parsed || "(all)");
+		const t = this.table;
+		if (parsed === "") await this.pgClient.query(`DELETE FROM ${t}`);
+		else {
+			const escaped = parsed.replace(/\\/g, "\\\\").replace(/_/g, "\\_").replace(/%/g, "\\%");
+			await this.pgClient.query(`DELETE FROM ${t} WHERE key = $1 OR key LIKE $2 ESCAPE '\\'`, [parsed, `${escaped}.%`]);
+		}
+		this.log("cleared", parsed || "(all)");
+		return this;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Honors `globalPrefix` — when configured, scopes the flush to entries
+	* under the prefix rather than truncating the entire table (which could
+	* wipe sibling tenants sharing the same Postgres database).
+	*/
+	async flush() {
+		this.log("flushing");
+		if (this.options.globalPrefix) await this.removeNamespace("");
+		else await this.pgClient.query(`DELETE FROM ${this.table}`);
+		this.log("flushed");
+		await this.emit("flushed");
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* pgvector-backed similarity. Uses the `<=>` cosine-distance operator
+	* (lower distance = higher similarity) and converts to cosine similarity
+	* as `1 - distance` so the returned `score` matches the rest of the
+	* package (`[0, 1]`, higher is more similar).
+	*
+	* Honors `topK`, `threshold`, and an optional `tags` filter (native
+	* `tags && $tags` overlap query — much faster than the meta-key path).
+	*
+	* Throws {@link CacheUnsupportedError} when `options.vector` was not
+	* configured at driver setup; throws {@link CacheConfigurationError} when
+	* the pgvector extension is missing or the query vector's dimension count
+	* doesn't match the configured one.
+	*/
+	async similar(vector, options) {
+		if (!this.options.vector) throw new CacheUnsupportedError("'pg' driver: similarity retrieval requires the 'vector' config block. Set options.vector.dimensions and reconnect.");
+		const expected = this.options.vector.dimensions;
+		if (vector.length !== expected) throw new CacheConfigurationError(`Pg cache driver: vector dimension mismatch — expected ${expected}, got ${vector.length}.`);
+		if (!Number.isInteger(options.topK) || options.topK <= 0) throw new CacheConfigurationError(`Pg cache driver: similar.topK must be a positive integer; got ${options.topK}.`);
+		await this.ensureVectorReady();
+		const t = this.table;
+		const params = [this.formatVector(vector)];
+		let tagFilter = "";
+		if (options.tags && options.tags.length > 0) {
+			params.push(options.tags);
+			tagFilter = `AND tags && $${params.length}`;
+		}
+		params.push(options.topK);
+		const topKParam = `$${params.length}`;
+		const { rows } = await this.pgClient.query(`SELECT key, value, 1 - (embedding <=> $1::vector) AS score
+       FROM ${t}
+       WHERE embedding IS NOT NULL
+         AND (expires_at IS NULL OR expires_at > now())
+         ${tagFilter}
+       ORDER BY embedding <=> $1::vector
+       LIMIT ${topKParam}`, params);
+		const hits = [];
+		for (const row of rows) {
+			const score = Number(row.score);
+			if (options.threshold !== void 0 && score < options.threshold) continue;
+			let value = row.value;
+			if (typeof value === "string") try {
+				value = JSON.parse(value);
+			} catch {}
+			if (value !== null && value !== void 0) {
+				const ty = typeof value;
+				if (ty !== "string" && ty !== "number" && ty !== "boolean") value = structuredClone(value);
+			}
+			hits.push({
+				key: row.key,
+				value,
+				score
+			});
+		}
+		return hits;
+	}
+};
+
+//#endregion
+export { PgCacheDriver };
+//# sourceMappingURL=pg-cache-driver.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pg-cache-driver.mjs","names":[],"sources":["../../../../../../@warlock.js/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(parsedKey, 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(parsedKey, 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(parsedKey, 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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"}

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

@@ -0,0 +1,86 @@
+import { BaseCacheDriver } from "./base-cache-driver.mjs";
+import { CacheData, CacheDriver, CacheKey, CacheSetOptions, CacheTtl, RedisOptions } from "../types.mjs";
+import { createClient } from "redis";
+
+//#region ../../@warlock.js/cache/src/drivers/redis-cache-driver.d.ts
+declare class RedisCacheDriver extends BaseCacheDriver<ReturnType<typeof createClient>, RedisOptions> implements CacheDriver<ReturnType<typeof createClient>, RedisOptions> {
+  /**
+   * Cache driver name
+   */
+  name: string;
+  /**
+   * {@inheritdoc}
+   */
+  setOptions(options: RedisOptions): this;
+  /**
+   * {@inheritDoc}
+   */
+  removeNamespace(namespace: string): Promise<string[] | undefined>;
+  /**
+   * {@inheritDoc}
+   */
+  set(key: CacheKey, value: any, ttlOrOptions?: CacheTtl | CacheSetOptions): Promise<any>;
+  /**
+   * Build the sidecar key Redis uses to track SWR freshness without
+   * wrapping the main value JSON.
+   */
+  protected swrMetaKey(parsedKey: string): string;
+  /**
+   * 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).
+   */
+  protected getEntry(key: CacheKey): Promise<CacheData | null>;
+  /**
+   * {@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.
+   */
+  protected getRemainingTtl(key: CacheKey): Promise<number | undefined>;
+  /**
+   * {@inheritDoc}
+   */
+  get(key: CacheKey): Promise<any>;
+  /**
+   * {@inheritDoc}
+   */
+  remove(key: CacheKey): Promise<void>;
+  /**
+   * {@inheritDoc}
+   */
+  flush(): Promise<void>;
+  /**
+   * {@inheritDoc}
+   */
+  connect(): Promise<void>;
+  /**
+   * {@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".
+   */
+  disconnect(): Promise<void>;
+  /**
+   * Atomic increment using Redis native INCRBY command
+   * {@inheritdoc}
+   */
+  increment(key: CacheKey, value?: number): Promise<number>;
+  /**
+   * Atomic decrement using Redis native DECRBY command
+   * {@inheritdoc}
+   */
+  decrement(key: CacheKey, value?: number): Promise<number>;
+  /**
+   * Set if not exists (atomic operation)
+   * Returns true if key was set, false if key already existed
+   */
+  setNX(key: CacheKey, value: any, ttl?: number): Promise<boolean>;
+}
+//#endregion
+export { RedisCacheDriver };
+//# sourceMappingURL=redis-cache-driver.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache-driver.d.mts","names":[],"sources":["../../../../../../@warlock.js/cache/src/drivers/redis-cache-driver.ts"],"mappings":";;;;;cA0Da,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;EAuBvC;;;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;EAkMrB;;;;;;;EAAA,UAzKZ,eAAA,CAAgB,GAAA,EAAK,QAAA,GAAW,OAAA;EA7J1B;;;EA+KT,GAAA,CAAI,GAAA,EAAK,QAAA,GAAQ,OAAA;EAhLY;;;EA+N7B,MAAA,CAAO,GAAA,EAAK,QAAA,GAAQ,OAAA;EA9NQ;;;EA+O5B,KAAA,CAAA,GAAK,OAAA;EArOS;;;EAuPd,OAAA,CAAA,GAAO,OAAA;EA1O0B;;;;;;;;EA8RjC,UAAA,CAAA,GAAU,OAAA;EA3Lb;;;;EA4MG,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAoB,OAAA;EAlMjB;;;;EAqN5B,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAoB,OAAA;EA5LV;;;;EA+MnC,KAAA,CAAM,GAAA,EAAK,QAAA,EAAU,KAAA,OAAY,GAAA,YAAe,OAAA;AAAA"}