@warlock.js/cache 4.8.2 → 4.9.1

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

@@ -1 +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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"}
+{"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(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

@@ -2,7 +2,7 @@ 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
+//#region ../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

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

@@ -1 +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;EA4MrB;;;;;;;EAAA,UAnLZ,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,IAAK,OAAA;EArOS;;;EAuPd,OAAA,IAAO,OAAA;EA1O0B;;;;;;;;EAwSjC,UAAA,IAAU,OAAA;EArMb;;;;EAsNG,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAoB,OAAA;EA5MjB;;;;EA+N5B,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAoB,OAAA;EAtMV;;;;EAyNnC,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":";;;;;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;EA4MrB;;;;;;;EAAA,UAnLZ,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,IAAK,OAAA;EArOS;;;EAuPd,OAAA,IAAO,OAAA;EA1O0B;;;;;;;;EAwSjC,UAAA,IAAU,OAAA;EArMb;;;;EAsNG,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAoB,OAAA;EA5MjB;;;;EA+N5B,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAoB,OAAA;EAtMV;;;;EAyNnC,KAAA,CAAM,GAAA,EAAK,QAAA,EAAU,KAAA,OAAY,GAAA,YAAe,OAAA;AAAA"}

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

@@ -2,7 +2,7 @@ import { CacheConfigurationError, CacheUnsupportedError } from "../types.mjs";
 import { BaseCacheDriver } from "./base-cache-driver.mjs";
 import { log } from "@warlock.js/logger";
 
-//#region ../@warlock.js/cache/src/drivers/redis-cache-driver.ts
+//#region ../cache/src/drivers/redis-cache-driver.ts
 /**
 * Cached Redis module (loaded once, reused)
 */

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

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

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

@@ -1,6 +1,6 @@
 import { CacheDriver, CacheKey, CacheListAccessor } from "../types.mjs";
 
-//#region ../@warlock.js/cache/src/list/memory-cache-list.d.ts
+//#region ../cache/src/list/memory-cache-list.d.ts
 /**
  * Generic array-backed {@link CacheListAccessor}.
  *

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

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

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

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/cache/src/list/memory-cache-list.ts
+//#region ../cache/src/list/memory-cache-list.ts
 /**
 * Generic array-backed {@link CacheListAccessor}.
 *

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

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

package/esm/metrics.d.mts

@@ -1,6 +1,6 @@
 import { CacheEventData, CacheMetricsSnapshot } from "./types.mjs";
 
-//#region ../@warlock.js/cache/src/metrics.d.ts
+//#region ../cache/src/metrics.d.ts
 /**
  * Per-driver counter row tracked inside {@link CacheMetricsCollector}.
  *

package/esm/metrics.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.d.mts","names":[],"sources":["../../../../../../@warlock.js/cache/src/metrics.ts"],"mappings":";;;;;AAGiB;;;;;KAgBZ,cAAA;EACH,IAAA;EACA,MAAA;EACA,IAAA;EACA,OAAA;EACA,MAAA;EACA,cAAA,YAEa;EAAb,aAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA+BW,qBAAA;EAoEJ;;;;;EAAA,mBA9DY,UAAA;EAoGT;;;;EAAA,mBA9FS,SAAA,EAAW,cAAA;EA6Gd;;;;EAAA,mBAvGG,QAAA,EAAU,GAAA,SAAY,cAAA;EA6HI;EAAA,UA1HnC,SAAA;cAES,UAAA;EAgJK;;;;EAvIjB,WAAA,CACL,KAAA,gDACA,IAAA,EAAM,cAAA;EA8JwB;;;AAAc;;EA5HvC,aAAA,CAAc,MAAA,UAAgB,UAAA;;;;;;EAU9B,QAAA,IAAY,oBAAA;;;;;EAkBZ,KAAA;;;;;YAUG,SAAA,CAAU,UAAA,WAAqB,cAAA;;;;;YAe/B,KAAA,CAAM,MAAA,EAAQ,cAAA,GAAiB,IAAA,CAAK,oBAAA;;;;;;YAsBpC,cAAA,CAAe,OAAA,aAAoB,oBAAA;;;;;YAwBnC,aAAA,CAAc,MAAA,EAAQ,cAAA,EAAgB,UAAA;;YAYtC,cAAA,IAAkB,cAAA;;YAalB,aAAA,CAAc,MAAA,EAAQ,cAAA;AAAA"}
+{"version":3,"file":"metrics.d.mts","names":[],"sources":["../../../../../../cache/src/metrics.ts"],"mappings":";;;;;AAGiB;;;;;KAgBZ,cAAA;EACH,IAAA;EACA,MAAA;EACA,IAAA;EACA,OAAA;EACA,MAAA;EACA,cAAA,YAEa;EAAb,aAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA+BW,qBAAA;EAoEJ;;;;;EAAA,mBA9DY,UAAA;EAoGT;;;;EAAA,mBA9FS,SAAA,EAAW,cAAA;EA6Gd;;;;EAAA,mBAvGG,QAAA,EAAU,GAAA,SAAY,cAAA;EA6HI;EAAA,UA1HnC,SAAA;cAES,UAAA;EAgJK;;;;EAvIjB,WAAA,CACL,KAAA,gDACA,IAAA,EAAM,cAAA;EA8JwB;;;AAAc;;EA5HvC,aAAA,CAAc,MAAA,UAAgB,UAAA;;;;;;EAU9B,QAAA,IAAY,oBAAA;;;;;EAkBZ,KAAA;;;;;YAUG,SAAA,CAAU,UAAA,WAAqB,cAAA;;;;;YAe/B,KAAA,CAAM,MAAA,EAAQ,cAAA,GAAiB,IAAA,CAAK,oBAAA;;;;;;YAsBpC,cAAA,CAAe,OAAA,aAAoB,oBAAA;;;;;YAwBnC,aAAA,CAAc,MAAA,EAAQ,cAAA,EAAgB,UAAA;;YAYtC,cAAA,IAAkB,cAAA;;YAalB,aAAA,CAAc,MAAA,EAAQ,cAAA;AAAA"}

package/esm/metrics.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/cache/src/metrics.ts
+//#region ../cache/src/metrics.ts
 /**
 * Default size of the circular latency-sample buffer. 1000 samples covers
 * "tell me the current p95" for every realistic workload while keeping the

package/esm/metrics.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.mjs","names":[],"sources":["../../../../../../@warlock.js/cache/src/metrics.ts"],"sourcesContent":["import type {\n  CacheEventData,\n  CacheMetricsSnapshot,\n} from \"./types\";\n\n/**\n * Default size of the circular latency-sample buffer. 1000 samples covers\n * \"tell me the current p95\" for every realistic workload while keeping the\n * memory cost negligible (8KB at 8 bytes per number).\n */\nconst DEFAULT_LATENCY_BUFFER_SIZE = 1000;\n\n/**\n * Per-driver counter row tracked inside {@link CacheMetricsCollector}.\n *\n * Same shape as the public {@link CacheMetricsSnapshot} except for the lack\n * of `byDriver` (which is the breakdown itself) and the `latencySamples`\n * array — the buffer that p50/p95/p99 are computed from at snapshot time.\n */\ntype DriverCounters = {\n  hits: number;\n  misses: number;\n  sets: number;\n  removed: number;\n  errors: number;\n  latencySamples: number[];\n  /** Pointer into `latencySamples` for the next write — circular buffer. */\n  latencyCursor: number;\n};\n\n/**\n * Listens to `CacheManager` events and accumulates running counters + a\n * circular latency buffer per driver. Returned to consumers via\n * `cache.metrics()` as a {@link CacheMetricsSnapshot}.\n *\n * **Role.** Single-instance observability layer attached to the manager.\n * Subscribes once at construction; survives `cache.use()` driver switches\n * because the global event registry on the manager re-attaches handlers to\n * every loaded driver.\n *\n * **Responsibility.**\n * - Owns: per-driver and aggregate counters (`hits`, `misses`, `sets`,\n *   `removed`, `errors`), the latency circular buffer, and snapshot\n *   computation including hit-rate + percentile calculation.\n * - Does NOT own: event emission (driven by drivers via `BaseCacheDriver.emit`),\n *   timing instrumentation (done at the manager level via `recordLatency`),\n *   or persistence — every metric resets on `resetMetrics()` and on process\n *   restart.\n *\n * @example\n * cache.metrics();\n * // {\n * //   hits: 9821, misses: 173, hitRate: 0.983,\n * //   latencyMs: { p50: 0.4, p95: 2.1, p99: 8.2, samples: 1000 },\n * //   byDriver: { memory: { ... }, redis: { ... } },\n * //   startedAt: 1714185600000,\n * // }\n */\nexport class CacheMetricsCollector {\n  /**\n   * Maximum number of latency samples retained per driver. Older samples\n   * are overwritten in arrival order — quantile calc operates on whatever\n   * window is currently in the buffer.\n   */\n  protected readonly bufferSize: number;\n\n  /**\n   * Aggregate counters across every driver. Mirrors what one driver bucket\n   * holds — the snapshot reports both totals and per-driver breakdowns.\n   */\n  protected readonly aggregate: DriverCounters;\n\n  /**\n   * Per-driver buckets keyed by driver name (`\"memory\"`, `\"redis\"`, …).\n   * Lazy-allocated on first event.\n   */\n  protected readonly byDriver: Map<string, DriverCounters> = new Map();\n\n  /** Millisecond timestamp the collector last reset. */\n  protected startedAt: number = Date.now();\n\n  public constructor(bufferSize: number = DEFAULT_LATENCY_BUFFER_SIZE) {\n    this.bufferSize = bufferSize;\n    this.aggregate = this.createCounters();\n  }\n\n  /**\n   * Increment the appropriate counters for a cache event. Called from the\n   * manager's global listeners (one per event type).\n   */\n  public recordEvent(\n    event: \"hit\" | \"miss\" | \"set\" | \"removed\" | \"error\",\n    data: CacheEventData,\n  ): void {\n    const driverBucket = this.bucketFor(data.driver);\n    const aggregate = this.aggregate;\n\n    switch (event) {\n      case \"hit\":\n        aggregate.hits += 1;\n        driverBucket.hits += 1;\n        break;\n      case \"miss\":\n        aggregate.misses += 1;\n        driverBucket.misses += 1;\n        break;\n      case \"set\":\n        aggregate.sets += 1;\n        driverBucket.sets += 1;\n        break;\n      case \"removed\":\n        aggregate.removed += 1;\n        driverBucket.removed += 1;\n        break;\n      case \"error\":\n        aggregate.errors += 1;\n        driverBucket.errors += 1;\n        break;\n    }\n  }\n\n  /**\n   * Append a latency sample for `driver`. Called by the manager from its\n   * timed wrappers around `get` / `set` / `remove`. Uses circular-buffer\n   * semantics: oldest samples are overwritten once the buffer is full.\n   */\n  public recordLatency(driver: string, durationMs: number): void {\n    this.appendLatency(this.aggregate, durationMs);\n    this.appendLatency(this.bucketFor(driver), durationMs);\n  }\n\n  /**\n   * Compute and return the current snapshot. Latency percentiles are\n   * derived from a sorted copy of the buffer at call time — O(N log N)\n   * on N=1000 is cheap enough that we don't bother caching.\n   */\n  public snapshot(): CacheMetricsSnapshot {\n    const byDriver: Record<string, Omit<CacheMetricsSnapshot, \"byDriver\">> = {};\n\n    for (const [driverName, bucket] of this.byDriver) {\n      byDriver[driverName] = this.toRow(bucket);\n    }\n\n    return {\n      ...this.toRow(this.aggregate),\n      byDriver,\n      startedAt: this.startedAt,\n    };\n  }\n\n  /**\n   * Wipe every counter, drop every latency sample, and reset `startedAt`.\n   * The collector itself stays subscribed to events.\n   */\n  public reset(): void {\n    this.resetCounters(this.aggregate);\n    this.byDriver.clear();\n    this.startedAt = Date.now();\n  }\n\n  /**\n   * Locate the per-driver bucket, creating it on first reference. Driver\n   * names are taken verbatim from `CacheEventData.driver`.\n   */\n  protected bucketFor(driverName: string): DriverCounters {\n    let bucket = this.byDriver.get(driverName);\n\n    if (!bucket) {\n      bucket = this.createCounters();\n      this.byDriver.set(driverName, bucket);\n    }\n\n    return bucket;\n  }\n\n  /**\n   * Convert raw counters into the public snapshot row shape. Computes\n   * `hitRate` and the latency percentiles on the fly.\n   */\n  protected toRow(bucket: DriverCounters): Omit<CacheMetricsSnapshot, \"byDriver\"> {\n    const totalReads = bucket.hits + bucket.misses;\n    const hitRate = totalReads === 0 ? 0 : bucket.hits / totalReads;\n    const latency = this.computeLatency(bucket.latencySamples);\n\n    return {\n      hits: bucket.hits,\n      misses: bucket.misses,\n      sets: bucket.sets,\n      removed: bucket.removed,\n      errors: bucket.errors,\n      hitRate,\n      latencyMs: latency,\n      startedAt: this.startedAt,\n    };\n  }\n\n  /**\n   * Sort a copy of the buffer and pick the percentile entries directly.\n   * Empty buffers return zeroed percentiles so consumers can render\n   * dashboards without null-checking.\n   */\n  protected computeLatency(samples: number[]): CacheMetricsSnapshot[\"latencyMs\"] {\n    if (samples.length === 0) {\n      return { p50: 0, p95: 0, p99: 0, samples: 0 };\n    }\n\n    const sorted = [...samples].sort((a, b) => a - b);\n    const pick = (quantile: number): number => {\n      const index = Math.min(sorted.length - 1, Math.floor(quantile * sorted.length));\n\n      return sorted[index];\n    };\n\n    return {\n      p50: pick(0.5),\n      p95: pick(0.95),\n      p99: pick(0.99),\n      samples: sorted.length,\n    };\n  }\n\n  /**\n   * Append a latency sample using circular-buffer semantics — overwrite the\n   * oldest entry once the buffer is full instead of growing unbounded.\n   */\n  protected appendLatency(bucket: DriverCounters, durationMs: number): void {\n    if (bucket.latencySamples.length < this.bufferSize) {\n      bucket.latencySamples.push(durationMs);\n\n      return;\n    }\n\n    bucket.latencySamples[bucket.latencyCursor] = durationMs;\n    bucket.latencyCursor = (bucket.latencyCursor + 1) % this.bufferSize;\n  }\n\n  /** Build a fresh counter row with zeroed totals and an empty buffer. */\n  protected createCounters(): DriverCounters {\n    return {\n      hits: 0,\n      misses: 0,\n      sets: 0,\n      removed: 0,\n      errors: 0,\n      latencySamples: [],\n      latencyCursor: 0,\n    };\n  }\n\n  /** Reset an existing counter row in place. Used by `reset()` for the aggregate. */\n  protected resetCounters(bucket: DriverCounters): void {\n    bucket.hits = 0;\n    bucket.misses = 0;\n    bucket.sets = 0;\n    bucket.removed = 0;\n    bucket.errors = 0;\n    bucket.latencySamples.length = 0;\n    bucket.latencyCursor = 0;\n  }\n}\n"],"mappings":";;;;;;AAUA,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDpC,IAAa,wBAAb,MAAmC;CAuBjC,AAAO,YAAY,aAAqB,6BAA6B;kCALV,IAAI,IAAI;mBAGrC,KAAK,IAAI;EAGrC,KAAK,aAAa;EAClB,KAAK,YAAY,KAAK,eAAe;CACvC;;;;;CAMA,AAAO,YACL,OACA,MACM;EACN,MAAM,eAAe,KAAK,UAAU,KAAK,MAAM;EAC/C,MAAM,YAAY,KAAK;EAEvB,QAAQ,OAAR;GACE,KAAK;IACH,UAAU,QAAQ;IAClB,aAAa,QAAQ;IACrB;GACF,KAAK;IACH,UAAU,UAAU;IACpB,aAAa,UAAU;IACvB;GACF,KAAK;IACH,UAAU,QAAQ;IAClB,aAAa,QAAQ;IACrB;GACF,KAAK;IACH,UAAU,WAAW;IACrB,aAAa,WAAW;IACxB;GACF,KAAK;IACH,UAAU,UAAU;IACpB,aAAa,UAAU;IACvB;EACJ;CACF;;;;;;CAOA,AAAO,cAAc,QAAgB,YAA0B;EAC7D,KAAK,cAAc,KAAK,WAAW,UAAU;EAC7C,KAAK,cAAc,KAAK,UAAU,MAAM,GAAG,UAAU;CACvD;;;;;;CAOA,AAAO,WAAiC;EACtC,MAAM,WAAmE,CAAC;EAE1E,KAAK,MAAM,CAAC,YAAY,WAAW,KAAK,UACtC,SAAS,cAAc,KAAK,MAAM,MAAM;EAG1C,OAAO;GACL,GAAG,KAAK,MAAM,KAAK,SAAS;GAC5B;GACA,WAAW,KAAK;EAClB;CACF;;;;;CAMA,AAAO,QAAc;EACnB,KAAK,cAAc,KAAK,SAAS;EACjC,KAAK,SAAS,MAAM;EACpB,KAAK,YAAY,KAAK,IAAI;CAC5B;;;;;CAMA,AAAU,UAAU,YAAoC;EACtD,IAAI,SAAS,KAAK,SAAS,IAAI,UAAU;EAEzC,IAAI,CAAC,QAAQ;GACX,SAAS,KAAK,eAAe;GAC7B,KAAK,SAAS,IAAI,YAAY,MAAM;EACtC;EAEA,OAAO;CACT;;;;;CAMA,AAAU,MAAM,QAAgE;EAC9E,MAAM,aAAa,OAAO,OAAO,OAAO;EACxC,MAAM,UAAU,eAAe,IAAI,IAAI,OAAO,OAAO;EACrD,MAAM,UAAU,KAAK,eAAe,OAAO,cAAc;EAEzD,OAAO;GACL,MAAM,OAAO;GACb,QAAQ,OAAO;GACf,MAAM,OAAO;GACb,SAAS,OAAO;GAChB,QAAQ,OAAO;GACf;GACA,WAAW;GACX,WAAW,KAAK;EAClB;CACF;;;;;;CAOA,AAAU,eAAe,SAAsD;EAC7E,IAAI,QAAQ,WAAW,GACrB,OAAO;GAAE,KAAK;GAAG,KAAK;GAAG,KAAK;GAAG,SAAS;EAAE;EAG9C,MAAM,SAAS,CAAC,GAAG,OAAO,CAAC,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC;EAChD,MAAM,QAAQ,aAA6B;GAGzC,OAAO,OAFO,KAAK,IAAI,OAAO,SAAS,GAAG,KAAK,MAAM,WAAW,OAAO,MAAM,CAE3D;EACpB;EAEA,OAAO;GACL,KAAK,KAAK,EAAG;GACb,KAAK,KAAK,GAAI;GACd,KAAK,KAAK,GAAI;GACd,SAAS,OAAO;EAClB;CACF;;;;;CAMA,AAAU,cAAc,QAAwB,YAA0B;EACxE,IAAI,OAAO,eAAe,SAAS,KAAK,YAAY;GAClD,OAAO,eAAe,KAAK,UAAU;GAErC;EACF;EAEA,OAAO,eAAe,OAAO,iBAAiB;EAC9C,OAAO,iBAAiB,OAAO,gBAAgB,KAAK,KAAK;CAC3D;;CAGA,AAAU,iBAAiC;EACzC,OAAO;GACL,MAAM;GACN,QAAQ;GACR,MAAM;GACN,SAAS;GACT,QAAQ;GACR,gBAAgB,CAAC;GACjB,eAAe;EACjB;CACF;;CAGA,AAAU,cAAc,QAA8B;EACpD,OAAO,OAAO;EACd,OAAO,SAAS;EAChB,OAAO,OAAO;EACd,OAAO,UAAU;EACjB,OAAO,SAAS;EAChB,OAAO,eAAe,SAAS;EAC/B,OAAO,gBAAgB;CACzB;AACF"}
+{"version":3,"file":"metrics.mjs","names":[],"sources":["../../../../../../cache/src/metrics.ts"],"sourcesContent":["import type {\n  CacheEventData,\n  CacheMetricsSnapshot,\n} from \"./types\";\n\n/**\n * Default size of the circular latency-sample buffer. 1000 samples covers\n * \"tell me the current p95\" for every realistic workload while keeping the\n * memory cost negligible (8KB at 8 bytes per number).\n */\nconst DEFAULT_LATENCY_BUFFER_SIZE = 1000;\n\n/**\n * Per-driver counter row tracked inside {@link CacheMetricsCollector}.\n *\n * Same shape as the public {@link CacheMetricsSnapshot} except for the lack\n * of `byDriver` (which is the breakdown itself) and the `latencySamples`\n * array — the buffer that p50/p95/p99 are computed from at snapshot time.\n */\ntype DriverCounters = {\n  hits: number;\n  misses: number;\n  sets: number;\n  removed: number;\n  errors: number;\n  latencySamples: number[];\n  /** Pointer into `latencySamples` for the next write — circular buffer. */\n  latencyCursor: number;\n};\n\n/**\n * Listens to `CacheManager` events and accumulates running counters + a\n * circular latency buffer per driver. Returned to consumers via\n * `cache.metrics()` as a {@link CacheMetricsSnapshot}.\n *\n * **Role.** Single-instance observability layer attached to the manager.\n * Subscribes once at construction; survives `cache.use()` driver switches\n * because the global event registry on the manager re-attaches handlers to\n * every loaded driver.\n *\n * **Responsibility.**\n * - Owns: per-driver and aggregate counters (`hits`, `misses`, `sets`,\n *   `removed`, `errors`), the latency circular buffer, and snapshot\n *   computation including hit-rate + percentile calculation.\n * - Does NOT own: event emission (driven by drivers via `BaseCacheDriver.emit`),\n *   timing instrumentation (done at the manager level via `recordLatency`),\n *   or persistence — every metric resets on `resetMetrics()` and on process\n *   restart.\n *\n * @example\n * cache.metrics();\n * // {\n * //   hits: 9821, misses: 173, hitRate: 0.983,\n * //   latencyMs: { p50: 0.4, p95: 2.1, p99: 8.2, samples: 1000 },\n * //   byDriver: { memory: { ... }, redis: { ... } },\n * //   startedAt: 1714185600000,\n * // }\n */\nexport class CacheMetricsCollector {\n  /**\n   * Maximum number of latency samples retained per driver. Older samples\n   * are overwritten in arrival order — quantile calc operates on whatever\n   * window is currently in the buffer.\n   */\n  protected readonly bufferSize: number;\n\n  /**\n   * Aggregate counters across every driver. Mirrors what one driver bucket\n   * holds — the snapshot reports both totals and per-driver breakdowns.\n   */\n  protected readonly aggregate: DriverCounters;\n\n  /**\n   * Per-driver buckets keyed by driver name (`\"memory\"`, `\"redis\"`, …).\n   * Lazy-allocated on first event.\n   */\n  protected readonly byDriver: Map<string, DriverCounters> = new Map();\n\n  /** Millisecond timestamp the collector last reset. */\n  protected startedAt: number = Date.now();\n\n  public constructor(bufferSize: number = DEFAULT_LATENCY_BUFFER_SIZE) {\n    this.bufferSize = bufferSize;\n    this.aggregate = this.createCounters();\n  }\n\n  /**\n   * Increment the appropriate counters for a cache event. Called from the\n   * manager's global listeners (one per event type).\n   */\n  public recordEvent(\n    event: \"hit\" | \"miss\" | \"set\" | \"removed\" | \"error\",\n    data: CacheEventData,\n  ): void {\n    const driverBucket = this.bucketFor(data.driver);\n    const aggregate = this.aggregate;\n\n    switch (event) {\n      case \"hit\":\n        aggregate.hits += 1;\n        driverBucket.hits += 1;\n        break;\n      case \"miss\":\n        aggregate.misses += 1;\n        driverBucket.misses += 1;\n        break;\n      case \"set\":\n        aggregate.sets += 1;\n        driverBucket.sets += 1;\n        break;\n      case \"removed\":\n        aggregate.removed += 1;\n        driverBucket.removed += 1;\n        break;\n      case \"error\":\n        aggregate.errors += 1;\n        driverBucket.errors += 1;\n        break;\n    }\n  }\n\n  /**\n   * Append a latency sample for `driver`. Called by the manager from its\n   * timed wrappers around `get` / `set` / `remove`. Uses circular-buffer\n   * semantics: oldest samples are overwritten once the buffer is full.\n   */\n  public recordLatency(driver: string, durationMs: number): void {\n    this.appendLatency(this.aggregate, durationMs);\n    this.appendLatency(this.bucketFor(driver), durationMs);\n  }\n\n  /**\n   * Compute and return the current snapshot. Latency percentiles are\n   * derived from a sorted copy of the buffer at call time — O(N log N)\n   * on N=1000 is cheap enough that we don't bother caching.\n   */\n  public snapshot(): CacheMetricsSnapshot {\n    const byDriver: Record<string, Omit<CacheMetricsSnapshot, \"byDriver\">> = {};\n\n    for (const [driverName, bucket] of this.byDriver) {\n      byDriver[driverName] = this.toRow(bucket);\n    }\n\n    return {\n      ...this.toRow(this.aggregate),\n      byDriver,\n      startedAt: this.startedAt,\n    };\n  }\n\n  /**\n   * Wipe every counter, drop every latency sample, and reset `startedAt`.\n   * The collector itself stays subscribed to events.\n   */\n  public reset(): void {\n    this.resetCounters(this.aggregate);\n    this.byDriver.clear();\n    this.startedAt = Date.now();\n  }\n\n  /**\n   * Locate the per-driver bucket, creating it on first reference. Driver\n   * names are taken verbatim from `CacheEventData.driver`.\n   */\n  protected bucketFor(driverName: string): DriverCounters {\n    let bucket = this.byDriver.get(driverName);\n\n    if (!bucket) {\n      bucket = this.createCounters();\n      this.byDriver.set(driverName, bucket);\n    }\n\n    return bucket;\n  }\n\n  /**\n   * Convert raw counters into the public snapshot row shape. Computes\n   * `hitRate` and the latency percentiles on the fly.\n   */\n  protected toRow(bucket: DriverCounters): Omit<CacheMetricsSnapshot, \"byDriver\"> {\n    const totalReads = bucket.hits + bucket.misses;\n    const hitRate = totalReads === 0 ? 0 : bucket.hits / totalReads;\n    const latency = this.computeLatency(bucket.latencySamples);\n\n    return {\n      hits: bucket.hits,\n      misses: bucket.misses,\n      sets: bucket.sets,\n      removed: bucket.removed,\n      errors: bucket.errors,\n      hitRate,\n      latencyMs: latency,\n      startedAt: this.startedAt,\n    };\n  }\n\n  /**\n   * Sort a copy of the buffer and pick the percentile entries directly.\n   * Empty buffers return zeroed percentiles so consumers can render\n   * dashboards without null-checking.\n   */\n  protected computeLatency(samples: number[]): CacheMetricsSnapshot[\"latencyMs\"] {\n    if (samples.length === 0) {\n      return { p50: 0, p95: 0, p99: 0, samples: 0 };\n    }\n\n    const sorted = [...samples].sort((a, b) => a - b);\n    const pick = (quantile: number): number => {\n      const index = Math.min(sorted.length - 1, Math.floor(quantile * sorted.length));\n\n      return sorted[index];\n    };\n\n    return {\n      p50: pick(0.5),\n      p95: pick(0.95),\n      p99: pick(0.99),\n      samples: sorted.length,\n    };\n  }\n\n  /**\n   * Append a latency sample using circular-buffer semantics — overwrite the\n   * oldest entry once the buffer is full instead of growing unbounded.\n   */\n  protected appendLatency(bucket: DriverCounters, durationMs: number): void {\n    if (bucket.latencySamples.length < this.bufferSize) {\n      bucket.latencySamples.push(durationMs);\n\n      return;\n    }\n\n    bucket.latencySamples[bucket.latencyCursor] = durationMs;\n    bucket.latencyCursor = (bucket.latencyCursor + 1) % this.bufferSize;\n  }\n\n  /** Build a fresh counter row with zeroed totals and an empty buffer. */\n  protected createCounters(): DriverCounters {\n    return {\n      hits: 0,\n      misses: 0,\n      sets: 0,\n      removed: 0,\n      errors: 0,\n      latencySamples: [],\n      latencyCursor: 0,\n    };\n  }\n\n  /** Reset an existing counter row in place. Used by `reset()` for the aggregate. */\n  protected resetCounters(bucket: DriverCounters): void {\n    bucket.hits = 0;\n    bucket.misses = 0;\n    bucket.sets = 0;\n    bucket.removed = 0;\n    bucket.errors = 0;\n    bucket.latencySamples.length = 0;\n    bucket.latencyCursor = 0;\n  }\n}\n"],"mappings":"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"}

package/esm/scoped-cache.d.mts

@@ -1,6 +1,6 @@
 import { CacheDriver, CacheKey, CacheListAccessor, CacheNamespaceOptions, CacheSetOptions, CacheSimilarHit, CacheSimilarOptions, CacheSwrOptions, CacheTtl, LockOptions, LockOutcome, RememberOptions, ScopedCacheContract, TaggedScopedCacheContract } from "./types.mjs";
 
-//#region ../@warlock.js/cache/src/scoped-cache.d.ts
+//#region ../cache/src/scoped-cache.d.ts
 /**
  * Scoped view over a cache source. Returned by `cache.namespace(prefix, options?)`.
  *

package/esm/scoped-cache.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"scoped-cache.d.mts","names":[],"sources":["../../../../../../@warlock.js/cache/src/scoped-cache.ts"],"mappings":"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"}
+{"version":3,"file":"scoped-cache.d.mts","names":[],"sources":["../../../../../../cache/src/scoped-cache.ts"],"mappings":"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"}

package/esm/scoped-cache.mjs

@@ -1,7 +1,7 @@
 import { mergeTagSets, normalizeToOptions, normalizeToRememberOptions, parseCacheKey, parseTtl } from "./utils.mjs";
 import { TaggedScopedCache } from "./tagged-scoped-cache.mjs";
 
-//#region ../@warlock.js/cache/src/scoped-cache.ts
+//#region ../cache/src/scoped-cache.ts
 /**
 * Scoped view over a cache source. Returned by `cache.namespace(prefix, options?)`.
 *

package/esm/scoped-cache.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"scoped-cache.mjs","names":[],"sources":["../../../../../../@warlock.js/cache/src/scoped-cache.ts"],"sourcesContent":["import { TaggedScopedCache } from \"./tagged-scoped-cache\";\nimport type {\n  CacheDriver,\n  CacheKey,\n  CacheListAccessor,\n  CacheNamespaceOptions,\n  CacheSetOptions,\n  CacheSimilarHit,\n  CacheSimilarOptions,\n  CacheSwrOptions,\n  CacheTtl,\n  LockOptions,\n  LockOutcome,\n  RememberOptions,\n  ScopedCacheContract,\n  TaggedScopedCacheContract,\n} from \"./types\";\nimport {\n  mergeTagSets,\n  normalizeToOptions,\n  normalizeToRememberOptions,\n  parseCacheKey,\n  parseTtl,\n} from \"./utils\";\n\n/**\n * Scoped view over a cache source. Returned by `cache.namespace(prefix, options?)`.\n *\n * **Role.** A `ScopedCache` is a stateless wrapper that prepends a fixed\n * prefix to every key and applies optional default `ttl` / `tags` to every\n * write. Stores nothing itself — every call forwards to the underlying\n * `source` (typically the `CacheManager`, but any `CacheDriver` works).\n *\n * **Responsibility.**\n * - Owns: prefix-prepending of keys, normalization of nested-scope prefixes,\n *   merging scope defaults into write options (`ttl`, `tags`), filtering\n *   `similar()` hits to its own scope, and exposing `.clear()` as a sugar\n *   for `removeNamespace(prefix)`.\n * - Does NOT own: actual storage, connection lifecycle, event listeners,\n *   driver selection, or tag-index bookkeeping (delegated to the source's\n *   tagged-cache machinery).\n *\n * Per-call options always win over scope defaults; tags merge additively\n * across (scope defaults + per-call) layers. Nested scopes inherit and may\n * override the parent's defaults — see {@link ScopedCache.namespace}.\n *\n * @example\n * const chat = cache.namespace(`chats.${id}`, { ttl: \"30d\" });\n *\n * await chat.set(\"messages.10\", msg);          // 30d default\n * await chat.set(\"draft\", d, { ttl: \"1h\" });   // per-call override\n * await chat.namespace(\"typing\", { ttl: \"5s\" }).set(\"user.42\", true);\n * await chat.clear();\n */\nexport class ScopedCache implements ScopedCacheContract {\n  /**\n   * Fully-qualified prefix prepended to every key handled by this scope.\n   * Normalized through {@link parseCacheKey} on construction so colon-form\n   * input (`\"chats:10\"`) and trailing dots compose cleanly with nested scopes.\n   */\n  public readonly prefix: string;\n\n  /**\n   * Underlying cache source. Public-readonly so co-located helpers\n   * (`TaggedScopedCache`) can delegate without ceremony — not part of the\n   * stable consumer API.\n   *\n   * @internal\n   */\n  public readonly source: CacheDriver<any, any>;\n\n  /**\n   * Defaults applied to every write through this scope. Per-call options\n   * override `ttl`; `tags` merge additively across layers.\n   *\n   * @internal\n   */\n  public readonly defaults: CacheNamespaceOptions;\n\n  /**\n   * Build a scope. Constructed via `cache.namespace(prefix, options)` —\n   * users never call this directly.\n   */\n  public constructor(\n    source: CacheDriver<any, any>,\n    prefix: string,\n    defaults: CacheNamespaceOptions = {},\n  ) {\n    this.source = source;\n    this.prefix = parseCacheKey(prefix);\n    this.defaults = {\n      ttl: defaults.ttl,\n      tags: defaults.tags && defaults.tags.length > 0 ? [...defaults.tags] : undefined,\n    };\n  }\n\n  /**\n   * Build a nested scope. The child's prefix is `parent.child`; child options\n   * override the parent's `ttl` and union into `tags`.\n   *\n   * @example\n   * const chat = cache.namespace(\"chats.10\", { ttl: \"30d\" });\n   * const typing = chat.namespace(\"typing\", { ttl: \"5s\" });\n   * // typing.prefix === \"chats.10.typing\"\n   */\n  public namespace(prefix: string, options: CacheNamespaceOptions = {}): ScopedCacheContract {\n    const childPrefix = `${this.prefix}.${parseCacheKey(prefix)}`;\n\n    return new ScopedCache(this.source, childPrefix, {\n      ttl: options.ttl ?? this.defaults.ttl,\n      tags: mergeTagSets(this.defaults.tags, options.tags),\n    });\n  }\n\n  /**\n   * Return a one-shot tagged write handle. The handle's tags merge additively\n   * with scope-level defaults — final tag list per write is the union of\n   * (scope tags + handle tags + per-call tags), deduped.\n   */\n  public tags(tags: string[]): TaggedScopedCacheContract {\n    return new TaggedScopedCache(this, tags);\n  }\n\n  /**\n   * Wipe every entry under this scope's prefix. Sugar over\n   * `source.removeNamespace(prefix)` — siblings outside the scope are\n   * untouched.\n   */\n  public clear(): Promise<void> {\n    return this.source.removeNamespace(this.prefix);\n  }\n\n  /**\n   * Read the value at the scoped key. Forwards to the source after prefixing.\n   */\n  public get<T = any>(key: CacheKey): Promise<T | null> {\n    return this.source.get<T>(this.scopedKey(key));\n  }\n\n  /**\n   * Check presence of the scoped key without fetching the value.\n   */\n  public has(key: CacheKey): Promise<boolean> {\n    return this.source.has(this.scopedKey(key));\n  }\n\n  /**\n   * Batch-read scoped keys. Each input key is prefixed before forwarding.\n   */\n  public many(keys: CacheKey[]): Promise<any[]> {\n    return this.source.many(keys.map((key) => this.scopedKey(key)));\n  }\n\n  /**\n   * Read-and-remove. Returns the value or `null`; the entry is gone after.\n   */\n  public pull<T = any>(key: CacheKey): Promise<T | null> {\n    return this.source.pull<T>(this.scopedKey(key));\n  }\n\n  /**\n   * Write the scoped key. Per-call `ttl`/`tags` win over scope defaults;\n   * `expiresAt` is preserved as-is (absolute deadlines are never overridden\n   * by the scope's relative-ttl default).\n   */\n  public set(\n    key: CacheKey,\n    value: any,\n    ttlOrOptions?: CacheTtl | CacheSetOptions,\n  ): Promise<any> {\n    return this.source.set(this.scopedKey(key), value, this.mergeSetOptions(ttlOrOptions));\n  }\n\n  /**\n   * Batch-write under the scope. Caller's positional `ttl` wins; otherwise\n   * the scope default is parsed to seconds (since `setMany` accepts only a\n   * numeric ttl).\n   */\n  public setMany(items: Record<string, any>, ttl?: number): Promise<void> {\n    const scoped: Record<string, any> = {};\n\n    for (const [key, value] of Object.entries(items)) {\n      scoped[this.scopedKey(key)] = value;\n    }\n\n    return this.source.setMany(scoped, ttl ?? this.scopeTtlSeconds());\n  }\n\n  /**\n   * Atomic create-or-skip on the scoped key. Throws when the underlying\n   * source has no `setNX` (driver-specific — Redis-only today).\n   */\n  public setNX(key: CacheKey, value: any, ttl?: number): Promise<boolean> {\n    if (!this.source.setNX) {\n      throw new Error(\n        `setNX is not supported by the underlying cache source: ${this.source.name}`,\n      );\n    }\n\n    return this.source.setNX(this.scopedKey(key), value, ttl ?? this.scopeTtlSeconds());\n  }\n\n  /**\n   * Permanent write (no expiration). Bypasses the scope's `ttl` default —\n   * `forever` always means forever, regardless of scope policy.\n   */\n  public forever<T = any>(key: CacheKey, value: T): Promise<T> {\n    return this.source.forever<T>(this.scopedKey(key), value);\n  }\n\n  /**\n   * Remove a single scoped key.\n   */\n  public remove(key: CacheKey): Promise<void> {\n    return this.source.remove(this.scopedKey(key));\n  }\n\n  /**\n   * Read-or-compute. Cache-miss writes pick up the scope's default `ttl`\n   * and `tags` unless the caller passed an options object that overrides.\n   */\n  public remember<T = any>(\n    key: CacheKey,\n    ttlOrOptions: CacheTtl | RememberOptions,\n    callback: () => Promise<T>,\n  ): Promise<T> {\n    return this.source.remember<T>(\n      this.scopedKey(key),\n      this.mergeRememberOptions(ttlOrOptions),\n      callback,\n    );\n  }\n\n  /**\n   * Stale-while-revalidate on the scoped key. Scope-level `tags` merge\n   * additively with `options.tags`; `freshTtl`/`staleTtl` always come from\n   * the caller (no scope-default precedence — the SWR shape is too\n   * specific to the call site to inherit).\n   */\n  public swr<T = any>(\n    key: CacheKey,\n    options: CacheSwrOptions,\n    callback: () => Promise<T>,\n  ): Promise<T> {\n    const merged: CacheSwrOptions = {\n      ...options,\n      tags: mergeTagSets(this.defaults.tags, options.tags),\n    };\n\n    return this.source.swr<T>(this.scopedKey(key), merged, callback);\n  }\n\n  /**\n   * Atomic counter increment on the scoped key. TTL is preserved by the\n   * underlying driver — scope ttl is only applied on first write via `set`.\n   */\n  public increment(key: CacheKey, value?: number): Promise<number> {\n    return this.source.increment(this.scopedKey(key), value);\n  }\n\n  /**\n   * Atomic counter decrement on the scoped key. See {@link increment} for\n   * TTL semantics.\n   */\n  public decrement(key: CacheKey, value?: number): Promise<number> {\n    return this.source.decrement(this.scopedKey(key), value);\n  }\n\n  /**\n   * Atomic read-modify-write. Falls back to the scope's `ttl` when the caller\n   * doesn't provide one; the source still keeps the existing entry's TTL on\n   * an update unless `options.ttl` is explicitly set.\n   */\n  public 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    return this.source.update<T>(this.scopedKey(key), fn, {\n      ttl: options?.ttl ?? this.defaults.ttl,\n    });\n  }\n\n  /**\n   * Shallow-merge a partial object into the scoped entry. Same TTL semantics\n   * as {@link update}.\n   */\n  public merge<T extends Record<string, any> = Record<string, any>>(\n    key: CacheKey,\n    partial: Partial<T>,\n    options?: { ttl?: CacheTtl },\n  ): Promise<T> {\n    return this.source.merge<T>(this.scopedKey(key), partial, {\n      ttl: options?.ttl ?? this.defaults.ttl,\n    });\n  }\n\n  /**\n   * Return a list accessor bound to the scoped key. The accessor itself\n   * does its own read-mutate-write under the prefixed entry.\n   */\n  public list<T = any>(key: CacheKey): CacheListAccessor<T> {\n    return this.source.list<T>(this.scopedKey(key));\n  }\n\n  /**\n   * Acquire a distributed lock on the scoped key. Caller's TTL wins; when\n   * the options form omits `ttl`, the scope default fills in.\n   */\n  public lock<T>(\n    key: CacheKey,\n    ttlOrOptions: CacheTtl | Omit<LockOptions, \"driver\">,\n    fn: () => Promise<T>,\n  ): Promise<LockOutcome<T>> {\n    if (typeof ttlOrOptions === \"object\" && ttlOrOptions !== null) {\n      const merged: Omit<LockOptions, \"driver\"> = {\n        ...ttlOrOptions,\n        ttl: ttlOrOptions.ttl ?? this.defaults.ttl ?? ttlOrOptions.ttl,\n      };\n\n      // The third coalesce is intentional — when both caller and scope omit\n      // the TTL, we still pass the original (undefined) through so the source\n      // raises its own validation error rather than us swallowing it silently.\n      return this.source.lock<T>(this.scopedKey(key), merged, fn);\n    }\n\n    return this.source.lock<T>(this.scopedKey(key), ttlOrOptions, fn);\n  }\n\n  /**\n   * Similarity retrieval, scope-isolated. Hits whose keys fall outside this\n   * scope are filtered out before the result is returned. `topK` applies to\n   * the underlying retrieval — when the scope contains fewer than `topK`\n   * matches but other scopes do, the caller will see fewer hits than `topK`.\n   */\n  public async similar<T = any>(\n    vector: number[],\n    options: CacheSimilarOptions,\n  ): Promise<CacheSimilarHit<T>[]> {\n    const hits = await this.source.similar<T>(vector, options);\n    const parsedPrefix = this.source.parseKey(this.prefix);\n\n    return hits.filter(\n      (hit) => hit.key === parsedPrefix || hit.key.startsWith(parsedPrefix + \".\"),\n    );\n  }\n\n  /**\n   * Build the source-side key by prepending the scope prefix. Object keys\n   * are normalized via {@link parseCacheKey} first so they compose with the\n   * prefix as plain dot-strings.\n   */\n  protected scopedKey(key: CacheKey): string {\n    const keyString = typeof key === \"string\" ? key : parseCacheKey(key);\n\n    if (!keyString) {\n      return this.prefix;\n    }\n\n    return `${this.prefix}.${keyString}`;\n  }\n\n  /**\n   * Coerce the polymorphic 3rd `set` argument into a {@link CacheSetOptions}\n   * with scope defaults filled in. Per-call values always win; tags merge\n   * additively. `expiresAt` is preserved without injecting the scope's `ttl`\n   * default (absolute deadlines override relative ones).\n   */\n  protected mergeSetOptions(\n    input?: CacheTtl | CacheSetOptions,\n  ): CacheSetOptions | undefined {\n    const options = normalizeToOptions(input);\n    const ttl =\n      options.ttl ?? (options.expiresAt === undefined ? this.defaults.ttl : undefined);\n    const tags = mergeTagSets(this.defaults.tags, options.tags);\n\n    const merged: CacheSetOptions = { ...options };\n\n    if (ttl !== undefined) {\n      merged.ttl = ttl;\n    }\n\n    if (tags !== undefined) {\n      merged.tags = tags;\n    }\n\n    return merged;\n  }\n\n  /**\n   * Same merge as {@link mergeSetOptions} but for the `remember()` shape\n   * ({@link RememberOptions} — no `expiresAt`).\n   */\n  protected mergeRememberOptions(\n    input: CacheTtl | RememberOptions,\n  ): CacheTtl | RememberOptions {\n    const options = normalizeToRememberOptions(input);\n    const ttl = options.ttl ?? this.defaults.ttl;\n    const tags = mergeTagSets(this.defaults.tags, options.tags);\n\n    const merged: RememberOptions = { ...options };\n\n    if (ttl !== undefined) {\n      merged.ttl = ttl;\n    }\n\n    if (tags !== undefined) {\n      merged.tags = tags;\n    }\n\n    return merged;\n  }\n\n  /**\n   * Convert the scope's default `ttl` (which may be a duration string) into\n   * seconds, for the few methods (`setMany`, `setNX`) that accept only a\n   * numeric ttl.\n   */\n  protected scopeTtlSeconds(): number | undefined {\n    if (this.defaults.ttl === undefined) {\n      return undefined;\n    }\n\n    return parseTtl(this.defaults.ttl);\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"scoped-cache.mjs","names":[],"sources":["../../../../../../cache/src/scoped-cache.ts"],"sourcesContent":["import { TaggedScopedCache } from \"./tagged-scoped-cache\";\nimport type {\n  CacheDriver,\n  CacheKey,\n  CacheListAccessor,\n  CacheNamespaceOptions,\n  CacheSetOptions,\n  CacheSimilarHit,\n  CacheSimilarOptions,\n  CacheSwrOptions,\n  CacheTtl,\n  LockOptions,\n  LockOutcome,\n  RememberOptions,\n  ScopedCacheContract,\n  TaggedScopedCacheContract,\n} from \"./types\";\nimport {\n  mergeTagSets,\n  normalizeToOptions,\n  normalizeToRememberOptions,\n  parseCacheKey,\n  parseTtl,\n} from \"./utils\";\n\n/**\n * Scoped view over a cache source. Returned by `cache.namespace(prefix, options?)`.\n *\n * **Role.** A `ScopedCache` is a stateless wrapper that prepends a fixed\n * prefix to every key and applies optional default `ttl` / `tags` to every\n * write. Stores nothing itself — every call forwards to the underlying\n * `source` (typically the `CacheManager`, but any `CacheDriver` works).\n *\n * **Responsibility.**\n * - Owns: prefix-prepending of keys, normalization of nested-scope prefixes,\n *   merging scope defaults into write options (`ttl`, `tags`), filtering\n *   `similar()` hits to its own scope, and exposing `.clear()` as a sugar\n *   for `removeNamespace(prefix)`.\n * - Does NOT own: actual storage, connection lifecycle, event listeners,\n *   driver selection, or tag-index bookkeeping (delegated to the source's\n *   tagged-cache machinery).\n *\n * Per-call options always win over scope defaults; tags merge additively\n * across (scope defaults + per-call) layers. Nested scopes inherit and may\n * override the parent's defaults — see {@link ScopedCache.namespace}.\n *\n * @example\n * const chat = cache.namespace(`chats.${id}`, { ttl: \"30d\" });\n *\n * await chat.set(\"messages.10\", msg);          // 30d default\n * await chat.set(\"draft\", d, { ttl: \"1h\" });   // per-call override\n * await chat.namespace(\"typing\", { ttl: \"5s\" }).set(\"user.42\", true);\n * await chat.clear();\n */\nexport class ScopedCache implements ScopedCacheContract {\n  /**\n   * Fully-qualified prefix prepended to every key handled by this scope.\n   * Normalized through {@link parseCacheKey} on construction so colon-form\n   * input (`\"chats:10\"`) and trailing dots compose cleanly with nested scopes.\n   */\n  public readonly prefix: string;\n\n  /**\n   * Underlying cache source. Public-readonly so co-located helpers\n   * (`TaggedScopedCache`) can delegate without ceremony — not part of the\n   * stable consumer API.\n   *\n   * @internal\n   */\n  public readonly source: CacheDriver<any, any>;\n\n  /**\n   * Defaults applied to every write through this scope. Per-call options\n   * override `ttl`; `tags` merge additively across layers.\n   *\n   * @internal\n   */\n  public readonly defaults: CacheNamespaceOptions;\n\n  /**\n   * Build a scope. Constructed via `cache.namespace(prefix, options)` —\n   * users never call this directly.\n   */\n  public constructor(\n    source: CacheDriver<any, any>,\n    prefix: string,\n    defaults: CacheNamespaceOptions = {},\n  ) {\n    this.source = source;\n    this.prefix = parseCacheKey(prefix);\n    this.defaults = {\n      ttl: defaults.ttl,\n      tags: defaults.tags && defaults.tags.length > 0 ? [...defaults.tags] : undefined,\n    };\n  }\n\n  /**\n   * Build a nested scope. The child's prefix is `parent.child`; child options\n   * override the parent's `ttl` and union into `tags`.\n   *\n   * @example\n   * const chat = cache.namespace(\"chats.10\", { ttl: \"30d\" });\n   * const typing = chat.namespace(\"typing\", { ttl: \"5s\" });\n   * // typing.prefix === \"chats.10.typing\"\n   */\n  public namespace(prefix: string, options: CacheNamespaceOptions = {}): ScopedCacheContract {\n    const childPrefix = `${this.prefix}.${parseCacheKey(prefix)}`;\n\n    return new ScopedCache(this.source, childPrefix, {\n      ttl: options.ttl ?? this.defaults.ttl,\n      tags: mergeTagSets(this.defaults.tags, options.tags),\n    });\n  }\n\n  /**\n   * Return a one-shot tagged write handle. The handle's tags merge additively\n   * with scope-level defaults — final tag list per write is the union of\n   * (scope tags + handle tags + per-call tags), deduped.\n   */\n  public tags(tags: string[]): TaggedScopedCacheContract {\n    return new TaggedScopedCache(this, tags);\n  }\n\n  /**\n   * Wipe every entry under this scope's prefix. Sugar over\n   * `source.removeNamespace(prefix)` — siblings outside the scope are\n   * untouched.\n   */\n  public clear(): Promise<void> {\n    return this.source.removeNamespace(this.prefix);\n  }\n\n  /**\n   * Read the value at the scoped key. Forwards to the source after prefixing.\n   */\n  public get<T = any>(key: CacheKey): Promise<T | null> {\n    return this.source.get<T>(this.scopedKey(key));\n  }\n\n  /**\n   * Check presence of the scoped key without fetching the value.\n   */\n  public has(key: CacheKey): Promise<boolean> {\n    return this.source.has(this.scopedKey(key));\n  }\n\n  /**\n   * Batch-read scoped keys. Each input key is prefixed before forwarding.\n   */\n  public many(keys: CacheKey[]): Promise<any[]> {\n    return this.source.many(keys.map((key) => this.scopedKey(key)));\n  }\n\n  /**\n   * Read-and-remove. Returns the value or `null`; the entry is gone after.\n   */\n  public pull<T = any>(key: CacheKey): Promise<T | null> {\n    return this.source.pull<T>(this.scopedKey(key));\n  }\n\n  /**\n   * Write the scoped key. Per-call `ttl`/`tags` win over scope defaults;\n   * `expiresAt` is preserved as-is (absolute deadlines are never overridden\n   * by the scope's relative-ttl default).\n   */\n  public set(\n    key: CacheKey,\n    value: any,\n    ttlOrOptions?: CacheTtl | CacheSetOptions,\n  ): Promise<any> {\n    return this.source.set(this.scopedKey(key), value, this.mergeSetOptions(ttlOrOptions));\n  }\n\n  /**\n   * Batch-write under the scope. Caller's positional `ttl` wins; otherwise\n   * the scope default is parsed to seconds (since `setMany` accepts only a\n   * numeric ttl).\n   */\n  public setMany(items: Record<string, any>, ttl?: number): Promise<void> {\n    const scoped: Record<string, any> = {};\n\n    for (const [key, value] of Object.entries(items)) {\n      scoped[this.scopedKey(key)] = value;\n    }\n\n    return this.source.setMany(scoped, ttl ?? this.scopeTtlSeconds());\n  }\n\n  /**\n   * Atomic create-or-skip on the scoped key. Throws when the underlying\n   * source has no `setNX` (driver-specific — Redis-only today).\n   */\n  public setNX(key: CacheKey, value: any, ttl?: number): Promise<boolean> {\n    if (!this.source.setNX) {\n      throw new Error(\n        `setNX is not supported by the underlying cache source: ${this.source.name}`,\n      );\n    }\n\n    return this.source.setNX(this.scopedKey(key), value, ttl ?? this.scopeTtlSeconds());\n  }\n\n  /**\n   * Permanent write (no expiration). Bypasses the scope's `ttl` default —\n   * `forever` always means forever, regardless of scope policy.\n   */\n  public forever<T = any>(key: CacheKey, value: T): Promise<T> {\n    return this.source.forever<T>(this.scopedKey(key), value);\n  }\n\n  /**\n   * Remove a single scoped key.\n   */\n  public remove(key: CacheKey): Promise<void> {\n    return this.source.remove(this.scopedKey(key));\n  }\n\n  /**\n   * Read-or-compute. Cache-miss writes pick up the scope's default `ttl`\n   * and `tags` unless the caller passed an options object that overrides.\n   */\n  public remember<T = any>(\n    key: CacheKey,\n    ttlOrOptions: CacheTtl | RememberOptions,\n    callback: () => Promise<T>,\n  ): Promise<T> {\n    return this.source.remember<T>(\n      this.scopedKey(key),\n      this.mergeRememberOptions(ttlOrOptions),\n      callback,\n    );\n  }\n\n  /**\n   * Stale-while-revalidate on the scoped key. Scope-level `tags` merge\n   * additively with `options.tags`; `freshTtl`/`staleTtl` always come from\n   * the caller (no scope-default precedence — the SWR shape is too\n   * specific to the call site to inherit).\n   */\n  public swr<T = any>(\n    key: CacheKey,\n    options: CacheSwrOptions,\n    callback: () => Promise<T>,\n  ): Promise<T> {\n    const merged: CacheSwrOptions = {\n      ...options,\n      tags: mergeTagSets(this.defaults.tags, options.tags),\n    };\n\n    return this.source.swr<T>(this.scopedKey(key), merged, callback);\n  }\n\n  /**\n   * Atomic counter increment on the scoped key. TTL is preserved by the\n   * underlying driver — scope ttl is only applied on first write via `set`.\n   */\n  public increment(key: CacheKey, value?: number): Promise<number> {\n    return this.source.increment(this.scopedKey(key), value);\n  }\n\n  /**\n   * Atomic counter decrement on the scoped key. See {@link increment} for\n   * TTL semantics.\n   */\n  public decrement(key: CacheKey, value?: number): Promise<number> {\n    return this.source.decrement(this.scopedKey(key), value);\n  }\n\n  /**\n   * Atomic read-modify-write. Falls back to the scope's `ttl` when the caller\n   * doesn't provide one; the source still keeps the existing entry's TTL on\n   * an update unless `options.ttl` is explicitly set.\n   */\n  public 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    return this.source.update<T>(this.scopedKey(key), fn, {\n      ttl: options?.ttl ?? this.defaults.ttl,\n    });\n  }\n\n  /**\n   * Shallow-merge a partial object into the scoped entry. Same TTL semantics\n   * as {@link update}.\n   */\n  public merge<T extends Record<string, any> = Record<string, any>>(\n    key: CacheKey,\n    partial: Partial<T>,\n    options?: { ttl?: CacheTtl },\n  ): Promise<T> {\n    return this.source.merge<T>(this.scopedKey(key), partial, {\n      ttl: options?.ttl ?? this.defaults.ttl,\n    });\n  }\n\n  /**\n   * Return a list accessor bound to the scoped key. The accessor itself\n   * does its own read-mutate-write under the prefixed entry.\n   */\n  public list<T = any>(key: CacheKey): CacheListAccessor<T> {\n    return this.source.list<T>(this.scopedKey(key));\n  }\n\n  /**\n   * Acquire a distributed lock on the scoped key. Caller's TTL wins; when\n   * the options form omits `ttl`, the scope default fills in.\n   */\n  public lock<T>(\n    key: CacheKey,\n    ttlOrOptions: CacheTtl | Omit<LockOptions, \"driver\">,\n    fn: () => Promise<T>,\n  ): Promise<LockOutcome<T>> {\n    if (typeof ttlOrOptions === \"object\" && ttlOrOptions !== null) {\n      const merged: Omit<LockOptions, \"driver\"> = {\n        ...ttlOrOptions,\n        ttl: ttlOrOptions.ttl ?? this.defaults.ttl ?? ttlOrOptions.ttl,\n      };\n\n      // The third coalesce is intentional — when both caller and scope omit\n      // the TTL, we still pass the original (undefined) through so the source\n      // raises its own validation error rather than us swallowing it silently.\n      return this.source.lock<T>(this.scopedKey(key), merged, fn);\n    }\n\n    return this.source.lock<T>(this.scopedKey(key), ttlOrOptions, fn);\n  }\n\n  /**\n   * Similarity retrieval, scope-isolated. Hits whose keys fall outside this\n   * scope are filtered out before the result is returned. `topK` applies to\n   * the underlying retrieval — when the scope contains fewer than `topK`\n   * matches but other scopes do, the caller will see fewer hits than `topK`.\n   */\n  public async similar<T = any>(\n    vector: number[],\n    options: CacheSimilarOptions,\n  ): Promise<CacheSimilarHit<T>[]> {\n    const hits = await this.source.similar<T>(vector, options);\n    const parsedPrefix = this.source.parseKey(this.prefix);\n\n    return hits.filter(\n      (hit) => hit.key === parsedPrefix || hit.key.startsWith(parsedPrefix + \".\"),\n    );\n  }\n\n  /**\n   * Build the source-side key by prepending the scope prefix. Object keys\n   * are normalized via {@link parseCacheKey} first so they compose with the\n   * prefix as plain dot-strings.\n   */\n  protected scopedKey(key: CacheKey): string {\n    const keyString = typeof key === \"string\" ? key : parseCacheKey(key);\n\n    if (!keyString) {\n      return this.prefix;\n    }\n\n    return `${this.prefix}.${keyString}`;\n  }\n\n  /**\n   * Coerce the polymorphic 3rd `set` argument into a {@link CacheSetOptions}\n   * with scope defaults filled in. Per-call values always win; tags merge\n   * additively. `expiresAt` is preserved without injecting the scope's `ttl`\n   * default (absolute deadlines override relative ones).\n   */\n  protected mergeSetOptions(\n    input?: CacheTtl | CacheSetOptions,\n  ): CacheSetOptions | undefined {\n    const options = normalizeToOptions(input);\n    const ttl =\n      options.ttl ?? (options.expiresAt === undefined ? this.defaults.ttl : undefined);\n    const tags = mergeTagSets(this.defaults.tags, options.tags);\n\n    const merged: CacheSetOptions = { ...options };\n\n    if (ttl !== undefined) {\n      merged.ttl = ttl;\n    }\n\n    if (tags !== undefined) {\n      merged.tags = tags;\n    }\n\n    return merged;\n  }\n\n  /**\n   * Same merge as {@link mergeSetOptions} but for the `remember()` shape\n   * ({@link RememberOptions} — no `expiresAt`).\n   */\n  protected mergeRememberOptions(\n    input: CacheTtl | RememberOptions,\n  ): CacheTtl | RememberOptions {\n    const options = normalizeToRememberOptions(input);\n    const ttl = options.ttl ?? this.defaults.ttl;\n    const tags = mergeTagSets(this.defaults.tags, options.tags);\n\n    const merged: RememberOptions = { ...options };\n\n    if (ttl !== undefined) {\n      merged.ttl = ttl;\n    }\n\n    if (tags !== undefined) {\n      merged.tags = tags;\n    }\n\n    return merged;\n  }\n\n  /**\n   * Convert the scope's default `ttl` (which may be a duration string) into\n   * seconds, for the few methods (`setMany`, `setNX`) that accept only a\n   * numeric ttl.\n   */\n  protected scopeTtlSeconds(): number | undefined {\n    if (this.defaults.ttl === undefined) {\n      return undefined;\n    }\n\n    return parseTtl(this.defaults.ttl);\n  }\n}\n"],"mappings":"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"}

package/esm/tagged-cache.d.mts

@@ -1,6 +1,6 @@
 import { CacheDriver, CacheKey, CacheSetOptions, CacheTtl, TaggedCacheDriver } from "./types.mjs";
 
-//#region ../@warlock.js/cache/src/tagged-cache.d.ts
+//#region ../cache/src/tagged-cache.d.ts
 /**
  * Tagged Cache Wrapper
  * Wraps a cache driver to automatically manage tag relationships

package/esm/tagged-cache.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"tagged-cache.d.mts","names":[],"sources":["../../../../../../@warlock.js/cache/src/tagged-cache.ts"],"mappings":";;;;;AAYA;;cAAa,WAAA,YAAuB,iBAAA;EAShB;;;EAAA,UALR,SAAA;EAmD+B;;;EAAA,UA9C/B,MAAA,EAAQ,WAAA;EAmEU;;;cA9DT,IAAA,YAAgB,MAAA,EAAQ,WAAA;EAmFlB;;;EAAA,UA3Ef,MAAA,CAAO,GAAA;EAsHK;;;EAAA,UA/GN,cAAA,CAAe,GAAA,WAAc,OAAA;EA0H1C;;;;;;;EA/GU,oBAAA,CAAqB,SAAA,WAAoB,OAAA;EAqKI;;;EAAA,UAtJ1C,aAAA,IAAiB,OAAA,CAAQ,GAAA;EAvDP;;;EAyErB,GAAA,CACX,GAAA,EAAK,QAAA,EACL,KAAA,OACA,YAAA,GAAe,QAAA,GAAW,eAAA,GACzB,OAAA;;;;EAaU,GAAA,CAAI,GAAA,EAAK,QAAA,GAAW,OAAA;EApEvB;;;EA2EG,MAAA,CAAO,GAAA,EAAK,QAAA,GAAW,OAAA;EApES;;;EAsFhC,UAAA,IAAc,OAAA;EA5DX;;;;EA8EH,KAAA,IAAS,OAAA;EA3DpB;;;EAkEW,GAAA,CAAI,GAAA,EAAK,QAAA,GAAW,OAAA;EAhE/B;;;EAuEW,QAAA,CACX,GAAA,EAAK,QAAA,EACL,GAAA,UACA,QAAA,QAAgB,OAAA,QACf,OAAA;EA7Dc;;;EA6EJ,IAAA,CAAK,GAAA,EAAK,QAAA,GAAW,OAAA;EAtEd;;;EAmFP,OAAA,CAAQ,GAAA,EAAK,QAAA,EAAU,KAAA,QAAa,OAAA;EA/CpC;;;EAsDA,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAoB,OAAA;EA/CzC;;;EAiEJ,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAoB,OAAA;AAAA"}
+{"version":3,"file":"tagged-cache.d.mts","names":[],"sources":["../../../../../../cache/src/tagged-cache.ts"],"mappings":";;;;;AAYA;;cAAa,WAAA,YAAuB,iBAAA;EAShB;;;EAAA,UALR,SAAA;EAmD+B;;;EAAA,UA9C/B,MAAA,EAAQ,WAAA;EAmEU;;;cA9DT,IAAA,YAAgB,MAAA,EAAQ,WAAA;EAmFlB;;;EAAA,UA3Ef,MAAA,CAAO,GAAA;EAsHK;;;EAAA,UA/GN,cAAA,CAAe,GAAA,WAAc,OAAA;EA0H1C;;;;;;;EA/GU,oBAAA,CAAqB,SAAA,WAAoB,OAAA;EAqKI;;;EAAA,UAtJ1C,aAAA,IAAiB,OAAA,CAAQ,GAAA;EAvDP;;;EAyErB,GAAA,CACX,GAAA,EAAK,QAAA,EACL,KAAA,OACA,YAAA,GAAe,QAAA,GAAW,eAAA,GACzB,OAAA;;;;EAaU,GAAA,CAAI,GAAA,EAAK,QAAA,GAAW,OAAA;EApEvB;;;EA2EG,MAAA,CAAO,GAAA,EAAK,QAAA,GAAW,OAAA;EApES;;;EAsFhC,UAAA,IAAc,OAAA;EA5DX;;;;EA8EH,KAAA,IAAS,OAAA;EA3DpB;;;EAkEW,GAAA,CAAI,GAAA,EAAK,QAAA,GAAW,OAAA;EAhE/B;;;EAuEW,QAAA,CACX,GAAA,EAAK,QAAA,EACL,GAAA,UACA,QAAA,QAAgB,OAAA,QACf,OAAA;EA7Dc;;;EA6EJ,IAAA,CAAK,GAAA,EAAK,QAAA,GAAW,OAAA;EAtEd;;;EAmFP,OAAA,CAAQ,GAAA,EAAK,QAAA,EAAU,KAAA,QAAa,OAAA;EA/CpC;;;EAsDA,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAoB,OAAA;EA/CzC;;;EAiEJ,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAoB,OAAA;AAAA"}

package/esm/tagged-cache.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/cache/src/tagged-cache.ts
+//#region ../cache/src/tagged-cache.ts
 /**
 * Tagged Cache Wrapper
 * Wraps a cache driver to automatically manage tag relationships

package/esm/tagged-cache.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"tagged-cache.mjs","names":[],"sources":["../../../../../../@warlock.js/cache/src/tagged-cache.ts"],"sourcesContent":["import type {\r\n  CacheDriver,\r\n  CacheKey,\r\n  CacheSetOptions,\r\n  CacheTtl,\r\n  TaggedCacheDriver,\r\n} from \"./types\";\r\n\r\n/**\r\n * Tagged Cache Wrapper\r\n * Wraps a cache driver to automatically manage tag relationships\r\n */\r\nexport class TaggedCache implements TaggedCacheDriver {\r\n  /**\r\n   * The tags associated with this tagged cache instance\r\n   */\r\n  protected cacheTags: string[];\r\n\r\n  /**\r\n   * The underlying cache driver\r\n   */\r\n  protected driver: CacheDriver<any, any>;\r\n\r\n  /**\r\n   * Constructor\r\n   */\r\n  public constructor(tags: string[], driver: CacheDriver<any, any>) {\r\n    this.cacheTags = tags;\r\n    this.driver = driver;\r\n  }\r\n\r\n  /**\r\n   * Get the tag key prefix for storing tag-key relationships\r\n   */\r\n  protected tagKey(tag: string): string {\r\n    return `cache:tags:${tag}`;\r\n  }\r\n\r\n  /**\r\n   * Store tag-key relationship\r\n   */\r\n  protected async storeTaggedKey(key: string): Promise<void> {\r\n    await this.storeTagRelationship(key);\r\n  }\r\n\r\n  /**\r\n   * Public alias of the tag-index writer. Called by `BaseCacheDriver.applyTags`\r\n   * when tags are passed inline through `CacheSetOptions.tags`.\r\n   *\r\n   * @internal — public for cross-class use within this package; not part of the\r\n   * stable consumer API.\r\n   */\r\n  public async storeTagRelationship(parsedKey: string): Promise<void> {\r\n    for (const tag of this.cacheTags) {\r\n      const tagKey = this.tagKey(tag);\r\n      const keys = (await this.driver.get(tagKey)) || [];\r\n\r\n      if (!keys.includes(parsedKey)) {\r\n        keys.push(parsedKey);\r\n        await this.driver.set(tagKey, keys, Infinity);\r\n      }\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get all keys associated with tags\r\n   */\r\n  protected async getTaggedKeys(): Promise<Set<string>> {\r\n    const allKeys = new Set<string>();\r\n\r\n    for (const tag of this.cacheTags) {\r\n      const tagKey = this.tagKey(tag);\r\n      const keys = (await this.driver.get(tagKey)) || [];\r\n\r\n      for (const key of keys) {\r\n        allKeys.add(key);\r\n      }\r\n    }\r\n\r\n    return allKeys;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async set(\r\n    key: CacheKey,\r\n    value: any,\r\n    ttlOrOptions?: CacheTtl | CacheSetOptions,\r\n  ): Promise<any> {\r\n    const parsedKey = this.driver.parseKey(key);\r\n\r\n    await this.driver.set(key, value, ttlOrOptions);\r\n\r\n    await this.storeTaggedKey(parsedKey);\r\n\r\n    return value;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async get(key: CacheKey): Promise<any | null> {\r\n    return this.driver.get(key);\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async remove(key: CacheKey): Promise<void> {\r\n    const parsedKey = this.driver.parseKey(key);\r\n\r\n    // Remove the value\r\n    await this.driver.remove(key);\r\n\r\n    // Remove from all tag relationships\r\n    for (const tag of this.cacheTags) {\r\n      const tagKey = this.tagKey(tag);\r\n      const keys = (await this.driver.get(tagKey)) || [];\r\n      const updatedKeys = keys.filter((k: string) => k !== parsedKey);\r\n      await this.driver.set(tagKey, updatedKeys, Infinity);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Invalidate (clear) all keys associated with the current tags\r\n   */\r\n  public async invalidate(): Promise<void> {\r\n    const keysToRemove = await this.getTaggedKeys();\r\n\r\n    // Remove all tagged keys\r\n    for (const key of keysToRemove) {\r\n      await this.driver.remove(key);\r\n    }\r\n\r\n    // Clear tag relationship keys\r\n    for (const tag of this.cacheTags) {\r\n      await this.driver.remove(this.tagKey(tag));\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Flush all keys associated with the current tags\r\n   * @deprecated Use invalidate() instead for better semantics\r\n   */\r\n  public async flush(): Promise<void> {\r\n    return this.invalidate();\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async has(key: CacheKey): Promise<boolean> {\r\n    return this.driver.has(key);\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async remember(\r\n    key: CacheKey,\r\n    ttl: number,\r\n    callback: () => Promise<any>,\r\n  ): Promise<any> {\r\n    const value = await this.get(key);\r\n\r\n    if (value !== null) {\r\n      return value;\r\n    }\r\n\r\n    const result = await callback();\r\n    await this.set(key, result, ttl);\r\n\r\n    return result;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async pull(key: CacheKey): Promise<any | null> {\r\n    const value = await this.get(key);\r\n\r\n    if (value !== null) {\r\n      await this.remove(key);\r\n    }\r\n\r\n    return value;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async forever(key: CacheKey, value: any): Promise<any> {\r\n    return this.set(key, value, Infinity);\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async increment(key: CacheKey, value: number = 1): Promise<number> {\r\n    const current = (await this.get(key)) || 0;\r\n\r\n    if (typeof current !== \"number\") {\r\n      throw new Error(\r\n        `Cannot increment non-numeric value for key: ${this.driver.parseKey(key)}`,\r\n      );\r\n    }\r\n\r\n    const newValue = current + value;\r\n    await this.set(key, newValue);\r\n\r\n    return newValue;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async decrement(key: CacheKey, value: number = 1): Promise<number> {\r\n    return this.increment(key, -value);\r\n  }\r\n}\r\n"],"mappings":"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"}
+{"version":3,"file":"tagged-cache.mjs","names":[],"sources":["../../../../../../cache/src/tagged-cache.ts"],"sourcesContent":["import type {\r\n  CacheDriver,\r\n  CacheKey,\r\n  CacheSetOptions,\r\n  CacheTtl,\r\n  TaggedCacheDriver,\r\n} from \"./types\";\r\n\r\n/**\r\n * Tagged Cache Wrapper\r\n * Wraps a cache driver to automatically manage tag relationships\r\n */\r\nexport class TaggedCache implements TaggedCacheDriver {\r\n  /**\r\n   * The tags associated with this tagged cache instance\r\n   */\r\n  protected cacheTags: string[];\r\n\r\n  /**\r\n   * The underlying cache driver\r\n   */\r\n  protected driver: CacheDriver<any, any>;\r\n\r\n  /**\r\n   * Constructor\r\n   */\r\n  public constructor(tags: string[], driver: CacheDriver<any, any>) {\r\n    this.cacheTags = tags;\r\n    this.driver = driver;\r\n  }\r\n\r\n  /**\r\n   * Get the tag key prefix for storing tag-key relationships\r\n   */\r\n  protected tagKey(tag: string): string {\r\n    return `cache:tags:${tag}`;\r\n  }\r\n\r\n  /**\r\n   * Store tag-key relationship\r\n   */\r\n  protected async storeTaggedKey(key: string): Promise<void> {\r\n    await this.storeTagRelationship(key);\r\n  }\r\n\r\n  /**\r\n   * Public alias of the tag-index writer. Called by `BaseCacheDriver.applyTags`\r\n   * when tags are passed inline through `CacheSetOptions.tags`.\r\n   *\r\n   * @internal — public for cross-class use within this package; not part of the\r\n   * stable consumer API.\r\n   */\r\n  public async storeTagRelationship(parsedKey: string): Promise<void> {\r\n    for (const tag of this.cacheTags) {\r\n      const tagKey = this.tagKey(tag);\r\n      const keys = (await this.driver.get(tagKey)) || [];\r\n\r\n      if (!keys.includes(parsedKey)) {\r\n        keys.push(parsedKey);\r\n        await this.driver.set(tagKey, keys, Infinity);\r\n      }\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get all keys associated with tags\r\n   */\r\n  protected async getTaggedKeys(): Promise<Set<string>> {\r\n    const allKeys = new Set<string>();\r\n\r\n    for (const tag of this.cacheTags) {\r\n      const tagKey = this.tagKey(tag);\r\n      const keys = (await this.driver.get(tagKey)) || [];\r\n\r\n      for (const key of keys) {\r\n        allKeys.add(key);\r\n      }\r\n    }\r\n\r\n    return allKeys;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async set(\r\n    key: CacheKey,\r\n    value: any,\r\n    ttlOrOptions?: CacheTtl | CacheSetOptions,\r\n  ): Promise<any> {\r\n    const parsedKey = this.driver.parseKey(key);\r\n\r\n    await this.driver.set(key, value, ttlOrOptions);\r\n\r\n    await this.storeTaggedKey(parsedKey);\r\n\r\n    return value;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async get(key: CacheKey): Promise<any | null> {\r\n    return this.driver.get(key);\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async remove(key: CacheKey): Promise<void> {\r\n    const parsedKey = this.driver.parseKey(key);\r\n\r\n    // Remove the value\r\n    await this.driver.remove(key);\r\n\r\n    // Remove from all tag relationships\r\n    for (const tag of this.cacheTags) {\r\n      const tagKey = this.tagKey(tag);\r\n      const keys = (await this.driver.get(tagKey)) || [];\r\n      const updatedKeys = keys.filter((k: string) => k !== parsedKey);\r\n      await this.driver.set(tagKey, updatedKeys, Infinity);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Invalidate (clear) all keys associated with the current tags\r\n   */\r\n  public async invalidate(): Promise<void> {\r\n    const keysToRemove = await this.getTaggedKeys();\r\n\r\n    // Remove all tagged keys\r\n    for (const key of keysToRemove) {\r\n      await this.driver.remove(key);\r\n    }\r\n\r\n    // Clear tag relationship keys\r\n    for (const tag of this.cacheTags) {\r\n      await this.driver.remove(this.tagKey(tag));\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Flush all keys associated with the current tags\r\n   * @deprecated Use invalidate() instead for better semantics\r\n   */\r\n  public async flush(): Promise<void> {\r\n    return this.invalidate();\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async has(key: CacheKey): Promise<boolean> {\r\n    return this.driver.has(key);\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async remember(\r\n    key: CacheKey,\r\n    ttl: number,\r\n    callback: () => Promise<any>,\r\n  ): Promise<any> {\r\n    const value = await this.get(key);\r\n\r\n    if (value !== null) {\r\n      return value;\r\n    }\r\n\r\n    const result = await callback();\r\n    await this.set(key, result, ttl);\r\n\r\n    return result;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async pull(key: CacheKey): Promise<any | null> {\r\n    const value = await this.get(key);\r\n\r\n    if (value !== null) {\r\n      await this.remove(key);\r\n    }\r\n\r\n    return value;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async forever(key: CacheKey, value: any): Promise<any> {\r\n    return this.set(key, value, Infinity);\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async increment(key: CacheKey, value: number = 1): Promise<number> {\r\n    const current = (await this.get(key)) || 0;\r\n\r\n    if (typeof current !== \"number\") {\r\n      throw new Error(\r\n        `Cannot increment non-numeric value for key: ${this.driver.parseKey(key)}`,\r\n      );\r\n    }\r\n\r\n    const newValue = current + value;\r\n    await this.set(key, newValue);\r\n\r\n    return newValue;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async decrement(key: CacheKey, value: number = 1): Promise<number> {\r\n    return this.increment(key, -value);\r\n  }\r\n}\r\n"],"mappings":";;;;;AAYA,IAAa,cAAb,MAAsD;;;;CAcpD,AAAO,YAAY,MAAgB,QAA+B;EAChE,KAAK,YAAY;EACjB,KAAK,SAAS;CAChB;;;;CAKA,AAAU,OAAO,KAAqB;EACpC,OAAO,cAAc;CACvB;;;;CAKA,MAAgB,eAAe,KAA4B;EACzD,MAAM,KAAK,qBAAqB,GAAG;CACrC;;;;;;;;CASA,MAAa,qBAAqB,WAAkC;EAClE,KAAK,MAAM,OAAO,KAAK,WAAW;GAChC,MAAM,SAAS,KAAK,OAAO,GAAG;GAC9B,MAAM,OAAQ,MAAM,KAAK,OAAO,IAAI,MAAM,KAAM,CAAC;GAEjD,IAAI,CAAC,KAAK,SAAS,SAAS,GAAG;IAC7B,KAAK,KAAK,SAAS;IACnB,MAAM,KAAK,OAAO,IAAI,QAAQ,MAAM,QAAQ;GAC9C;EACF;CACF;;;;CAKA,MAAgB,gBAAsC;EACpD,MAAM,0BAAU,IAAI,IAAY;EAEhC,KAAK,MAAM,OAAO,KAAK,WAAW;GAChC,MAAM,SAAS,KAAK,OAAO,GAAG;GAC9B,MAAM,OAAQ,MAAM,KAAK,OAAO,IAAI,MAAM,KAAM,CAAC;GAEjD,KAAK,MAAM,OAAO,MAChB,QAAQ,IAAI,GAAG;EAEnB;EAEA,OAAO;CACT;;;;CAKA,MAAa,IACX,KACA,OACA,cACc;EACd,MAAM,YAAY,KAAK,OAAO,SAAS,GAAG;EAE1C,MAAM,KAAK,OAAO,IAAI,KAAK,OAAO,YAAY;EAE9C,MAAM,KAAK,eAAe,SAAS;EAEnC,OAAO;CACT;;;;CAKA,MAAa,IAAI,KAAoC;EACnD,OAAO,KAAK,OAAO,IAAI,GAAG;CAC5B;;;;CAKA,MAAa,OAAO,KAA8B;EAChD,MAAM,YAAY,KAAK,OAAO,SAAS,GAAG;EAG1C,MAAM,KAAK,OAAO,OAAO,GAAG;EAG5B,KAAK,MAAM,OAAO,KAAK,WAAW;GAChC,MAAM,SAAS,KAAK,OAAO,GAAG;GAE9B,MAAM,eADQ,MAAM,KAAK,OAAO,IAAI,MAAM,KAAM,CAAC,EACzB,CAAC,QAAQ,MAAc,MAAM,SAAS;GAC9D,MAAM,KAAK,OAAO,IAAI,QAAQ,aAAa,QAAQ;EACrD;CACF;;;;CAKA,MAAa,aAA4B;EACvC,MAAM,eAAe,MAAM,KAAK,cAAc;EAG9C,KAAK,MAAM,OAAO,cAChB,MAAM,KAAK,OAAO,OAAO,GAAG;EAI9B,KAAK,MAAM,OAAO,KAAK,WACrB,MAAM,KAAK,OAAO,OAAO,KAAK,OAAO,GAAG,CAAC;CAE7C;;;;;CAMA,MAAa,QAAuB;EAClC,OAAO,KAAK,WAAW;CACzB;;;;CAKA,MAAa,IAAI,KAAiC;EAChD,OAAO,KAAK,OAAO,IAAI,GAAG;CAC5B;;;;CAKA,MAAa,SACX,KACA,KACA,UACc;EACd,MAAM,QAAQ,MAAM,KAAK,IAAI,GAAG;EAEhC,IAAI,UAAU,MACZ,OAAO;EAGT,MAAM,SAAS,MAAM,SAAS;EAC9B,MAAM,KAAK,IAAI,KAAK,QAAQ,GAAG;EAE/B,OAAO;CACT;;;;CAKA,MAAa,KAAK,KAAoC;EACpD,MAAM,QAAQ,MAAM,KAAK,IAAI,GAAG;EAEhC,IAAI,UAAU,MACZ,MAAM,KAAK,OAAO,GAAG;EAGvB,OAAO;CACT;;;;CAKA,MAAa,QAAQ,KAAe,OAA0B;EAC5D,OAAO,KAAK,IAAI,KAAK,OAAO,QAAQ;CACtC;;;;CAKA,MAAa,UAAU,KAAe,QAAgB,GAAoB;EACxE,MAAM,UAAW,MAAM,KAAK,IAAI,GAAG,KAAM;EAEzC,IAAI,OAAO,YAAY,UACrB,MAAM,IAAI,MACR,+CAA+C,KAAK,OAAO,SAAS,GAAG,GACzE;EAGF,MAAM,WAAW,UAAU;EAC3B,MAAM,KAAK,IAAI,KAAK,QAAQ;EAE5B,OAAO;CACT;;;;CAKA,MAAa,UAAU,KAAe,QAAgB,GAAoB;EACxE,OAAO,KAAK,UAAU,KAAK,CAAC,KAAK;CACnC;AACF"}