@chidchanun/bcp 0.2.14 → 0.2.16

package/packages/client/src/cache.mjs

@@ -0,0 +1,1554 @@
+// packages/cache/src/index.ts
+import {
+  AsyncLocalStorage
+} from "node:async_hooks";
+import {
+  createHash
+} from "node:crypto";
+var CACHE_RUNTIME_SYMBOL = /* @__PURE__ */ Symbol.for(
+  "bcp.framework.cache.runtime"
+);
+var globalRecord = globalThis;
+var runtimeState = globalRecord[CACHE_RUNTIME_SYMBOL];
+if (!runtimeState) {
+  runtimeState = {
+    persistentCache: /* @__PURE__ */ new Map(),
+    inFlight: /* @__PURE__ */ new Map(),
+    requestStorage: new AsyncLocalStorage()
+  };
+  globalRecord[CACHE_RUNTIME_SYMBOL] = runtimeState;
+}
+var persistentCache = runtimeState.persistentCache;
+var inFlight = runtimeState.inFlight;
+var requestStorage = runtimeState.requestStorage;
+function dedupe(fn, key) {
+  const namespace = key ?? fn.name ?? "anonymous";
+  return async (...args) => {
+    const context = ensureRequestContext();
+    const cacheKey = `request:${namespace}:${hashArguments(args)}`;
+    const existing = context.memo.get(
+      cacheKey
+    );
+    if (existing) {
+      return await existing;
+    }
+    const promise = Promise.resolve(
+      fn(...args)
+    );
+    context.memo.set(
+      cacheKey,
+      promise
+    );
+    try {
+      return await promise;
+    } catch (error) {
+      context.memo.delete(
+        cacheKey
+      );
+      throw error;
+    }
+  };
+}
+function cache(fn, options = {}) {
+  const namespace = options.key ?? fn.name;
+  if (!namespace) {
+    throw new Error(
+      "BCP Framework: cache() requires options.key when the wrapped function has no name."
+    );
+  }
+  validateRevalidate(
+    options.revalidate
+  );
+  validateTags(
+    options.tags
+  );
+  return async (...args) => {
+    if (options.revalidate === 0) {
+      return await fn(
+        ...args
+      );
+    }
+    const cacheKey = `data:${namespace}:${hashArguments(args)}`;
+    const existingEntry = readCacheEntry(
+      cacheKey
+    );
+    if (existingEntry.hit) {
+      return existingEntry.value;
+    }
+    const pending = inFlight.get(
+      cacheKey
+    );
+    if (pending) {
+      return await pending;
+    }
+    const promise = Promise.resolve(
+      fn(...args)
+    );
+    inFlight.set(
+      cacheKey,
+      promise
+    );
+    try {
+      const value = await promise;
+      const currentPath = requestStorage.getStore()?.pathname ?? null;
+      const paths = new Set(
+        (options.paths ?? []).map(
+          normalizePath
+        )
+      );
+      if (currentPath) {
+        paths.add(
+          currentPath
+        );
+      }
+      setCacheEntry(
+        cacheKey,
+        value,
+        {
+          revalidate: options.revalidate,
+          tags: options.tags,
+          paths: Array.from(
+            paths
+          )
+        }
+      );
+      return value;
+    } finally {
+      inFlight.delete(
+        cacheKey
+      );
+    }
+  };
+}
+function setCacheEntry(key, value, options = {}) {
+  validateRevalidate(
+    options.revalidate
+  );
+  validateTags(
+    options.tags
+  );
+  if (options.revalidate === 0) {
+    persistentCache.delete(
+      key
+    );
+    return;
+  }
+  const expiresAt = options.revalidate === void 0 || options.revalidate === false ? null : Date.now() + options.revalidate * 1e3;
+  persistentCache.set(
+    key,
+    {
+      value,
+      expiresAt,
+      tags: new Set(
+        options.tags ?? []
+      ),
+      paths: new Set(
+        (options.paths ?? []).map(
+          normalizePath
+        )
+      )
+    }
+  );
+}
+function revalidateTag(tag) {
+  const normalized = normalizeTag(tag);
+  let removed = 0;
+  for (const [
+    key,
+    entry
+  ] of persistentCache) {
+    if (entry.tags.has(
+      normalized
+    )) {
+      persistentCache.delete(
+        key
+      );
+      removed++;
+    }
+  }
+  return removed;
+}
+function revalidatePath(pathname) {
+  const normalized = normalizePath(pathname);
+  let removed = 0;
+  for (const [
+    key,
+    entry
+  ] of persistentCache) {
+    const matches = Array.from(
+      entry.paths
+    ).some(
+      (cachedPath) => pathMatches(
+        cachedPath,
+        normalized
+      )
+    );
+    if (matches) {
+      persistentCache.delete(
+        key
+      );
+      removed++;
+    }
+  }
+  return removed;
+}
+function clearCache() {
+  persistentCache.clear();
+  inFlight.clear();
+}
+function getCacheStats() {
+  pruneExpiredEntries();
+  return {
+    entries: persistentCache.size,
+    inFlight: inFlight.size
+  };
+}
+function normalizeRevalidate(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (value === false) {
+    return false;
+  }
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+    return value;
+  }
+  throw new Error(
+    "BCP Framework: revalidate must be false or a non-negative number of seconds."
+  );
+}
+function readCacheEntry(key) {
+  const entry = persistentCache.get(
+    key
+  );
+  if (!entry) {
+    return {
+      hit: false
+    };
+  }
+  if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+    persistentCache.delete(
+      key
+    );
+    return {
+      hit: false
+    };
+  }
+  return {
+    hit: true,
+    value: entry.value
+  };
+}
+function ensureRequestContext() {
+  const existing = requestStorage.getStore();
+  if (existing) {
+    return existing;
+  }
+  const context = {
+    pathname: null,
+    memo: /* @__PURE__ */ new Map()
+  };
+  requestStorage.enterWith(
+    context
+  );
+  return context;
+}
+function pruneExpiredEntries() {
+  const now = Date.now();
+  for (const [
+    key,
+    entry
+  ] of persistentCache) {
+    if (entry.expiresAt !== null && entry.expiresAt <= now) {
+      persistentCache.delete(
+        key
+      );
+    }
+  }
+}
+function validateRevalidate(value) {
+  normalizeRevalidate(
+    value
+  );
+}
+function validateTags(tags) {
+  for (const tag of tags ?? []) {
+    normalizeTag(
+      tag
+    );
+  }
+}
+function normalizeTag(value) {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(
+      "BCP Framework: cache tags cannot be empty."
+    );
+  }
+  return normalized;
+}
+function normalizePath(value) {
+  let pathname = value.trim();
+  if (!pathname) {
+    return "/";
+  }
+  try {
+    if (pathname.startsWith(
+      "http://"
+    ) || pathname.startsWith(
+      "https://"
+    )) {
+      pathname = new URL(
+        pathname
+      ).pathname;
+    }
+  } catch {
+  }
+  pathname = pathname.split("?")[0].split("#")[0];
+  if (!pathname.startsWith("/")) {
+    pathname = `/${pathname}`;
+  }
+  if (pathname.length > 1 && pathname.endsWith("/")) {
+    pathname = pathname.slice(
+      0,
+      -1
+    );
+  }
+  return pathname;
+}
+function pathMatches(cachedPath, invalidatedPath) {
+  if (invalidatedPath === "/") {
+    return true;
+  }
+  return cachedPath === invalidatedPath || cachedPath.startsWith(
+    `${invalidatedPath}/`
+  );
+}
+function hashArguments(args) {
+  return createHash(
+    "sha256"
+  ).update(
+    stableSerialize(
+      args
+    )
+  ).digest(
+    "hex"
+  ).slice(
+    0,
+    24
+  );
+}
+function stableSerialize(value, seen = /* @__PURE__ */ new WeakSet()) {
+  if (value === null) {
+    return "null";
+  }
+  switch (typeof value) {
+    case "undefined":
+      return "undefined";
+    case "string":
+      return JSON.stringify(
+        value
+      );
+    case "number":
+    case "boolean":
+      return String(value);
+    case "bigint":
+      return `${value.toString()}n`;
+    case "symbol":
+    case "function":
+      throw new Error(
+        `BCP Framework: cache keys cannot include ${typeof value} values.`
+      );
+    case "object":
+      break;
+    default:
+      return String(value);
+  }
+  const object = value;
+  if (seen.has(object)) {
+    throw new Error(
+      "BCP Framework: cache keys cannot include circular values."
+    );
+  }
+  seen.add(object);
+  try {
+    if (value instanceof Date) {
+      return `Date(${value.toISOString()})`;
+    }
+    if (Array.isArray(value)) {
+      return `[${value.map(
+        (item) => stableSerialize(
+          item,
+          seen
+        )
+      ).join(",")}]`;
+    }
+    const record = value;
+    return `{${Object.keys(record).sort().map(
+      (key) => `${JSON.stringify(key)}:${stableSerialize(
+        record[key],
+        seen
+      )}`
+    ).join(",")}}`;
+  } finally {
+    seen.delete(object);
+  }
+}
+
+// packages/cache/src/platform-v2.ts
+import {
+  randomUUID
+} from "node:crypto";
+var DEFAULT_LOCK_TTL_MS = 3e4;
+var DEFAULT_WAIT_TIMEOUT_MS = 5e3;
+var DEFAULT_POLL_INTERVAL_MS = 25;
+function createMemoryCacheAdapter(options = {}) {
+  const now = options.now ?? Date.now;
+  const records = /* @__PURE__ */ new Map();
+  const adapter = {
+    get size() {
+      prune();
+      return records.size;
+    },
+    async get(rawKey) {
+      const key = normalizeKey(rawKey);
+      const entry = records.get(key);
+      if (!entry) {
+        return null;
+      }
+      if (isExpired(entry, now())) {
+        records.delete(key);
+        return null;
+      }
+      return cloneEntry(entry);
+    },
+    async set(rawKey, value, setOptions = {}) {
+      const key = normalizeKey(rawKey);
+      const timestamp = now();
+      assertFiniteTimestamp(timestamp, "cache timestamp");
+      const current = records.get(key);
+      const expiresAt = normalizeExpiresAt(
+        setOptions.expiresAt
+      );
+      records.set(key, {
+        key,
+        value,
+        expiresAt,
+        tags: normalizeTags(setOptions.tags),
+        paths: normalizePaths(setOptions.paths),
+        createdAt: current?.createdAt ?? timestamp,
+        updatedAt: timestamp
+      });
+    },
+    async delete(rawKey) {
+      return records.delete(
+        normalizeKey(rawKey)
+      );
+    },
+    async clear() {
+      const count = records.size;
+      records.clear();
+      return count;
+    },
+    async revalidateTag(rawTag) {
+      const tag = normalizeTag2(rawTag);
+      let removed = 0;
+      for (const [key, record] of records) {
+        if (record.tags.includes(tag)) {
+          records.delete(key);
+          removed++;
+        }
+      }
+      return removed;
+    },
+    async revalidatePath(rawPath) {
+      const pathname = normalizePath2(rawPath);
+      let removed = 0;
+      for (const [key, record] of records) {
+        if (record.paths.some(
+          (path) => pathMatches2(path, pathname)
+        )) {
+          records.delete(key);
+          removed++;
+        }
+      }
+      return removed;
+    },
+    async entries() {
+      prune();
+      return records.size;
+    }
+  };
+  return adapter;
+  function prune() {
+    const timestamp = now();
+    for (const [key, record] of records) {
+      if (isExpired(record, timestamp)) {
+        records.delete(key);
+      }
+    }
+  }
+}
+function createMemoryCacheLockAdapter(options = {}) {
+  const now = options.now ?? Date.now;
+  const locks = /* @__PURE__ */ new Map();
+  const adapter = {
+    get size() {
+      prune();
+      return locks.size;
+    },
+    async acquire(rawKey, rawOwnerId, ttlMs) {
+      const key = normalizeKey(rawKey);
+      const ownerId = normalizeOwnerId(rawOwnerId);
+      const ttl = positiveInteger(ttlMs, "lock ttlMs");
+      const timestamp = now();
+      const current = locks.get(key);
+      if (current && current.expiresAt > timestamp) {
+        return false;
+      }
+      locks.set(key, {
+        ownerId,
+        expiresAt: timestamp + ttl
+      });
+      return true;
+    },
+    async extend(rawKey, rawOwnerId, ttlMs) {
+      const key = normalizeKey(rawKey);
+      const ownerId = normalizeOwnerId(rawOwnerId);
+      const ttl = positiveInteger(ttlMs, "lock ttlMs");
+      const timestamp = now();
+      const current = locks.get(key);
+      if (!current || current.ownerId !== ownerId || current.expiresAt <= timestamp) {
+        return false;
+      }
+      current.expiresAt = timestamp + ttl;
+      return true;
+    },
+    async release(rawKey, rawOwnerId) {
+      const key = normalizeKey(rawKey);
+      const ownerId = normalizeOwnerId(rawOwnerId);
+      const current = locks.get(key);
+      if (!current || current.ownerId !== ownerId) {
+        return false;
+      }
+      locks.delete(key);
+      return true;
+    }
+  };
+  return adapter;
+  function prune() {
+    const timestamp = now();
+    for (const [key, record] of locks) {
+      if (record.expiresAt <= timestamp) {
+        locks.delete(key);
+      }
+    }
+  }
+}
+function createCacheStore(options = {}) {
+  const adapter = options.adapter ?? createMemoryCacheAdapter({
+    now: options.now
+  });
+  const lock = options.lock;
+  const now = options.now ?? Date.now;
+  const idFactory = options.idFactory ?? randomUUID;
+  const metrics = options.metrics;
+  const inFlight2 = /* @__PURE__ */ new Map();
+  const counters = {
+    hits: 0,
+    misses: 0,
+    sets: 0,
+    deletes: 0,
+    invalidations: 0,
+    loads: 0,
+    loadErrors: 0,
+    lockAcquired: 0,
+    lockContentions: 0,
+    lockTimeouts: 0
+  };
+  let closed = false;
+  const store = {
+    adapter,
+    lock,
+    async get(rawKey) {
+      assertOpen();
+      const key = normalizeKey(rawKey);
+      const entry = await adapter.get(key);
+      if (!entry) {
+        count("misses", "miss");
+        return void 0;
+      }
+      if (entry.expiresAt !== null && entry.expiresAt <= now()) {
+        await adapter.delete(key);
+        count("misses", "miss");
+        return void 0;
+      }
+      count("hits", "hit");
+      return entry.value;
+    },
+    async set(rawKey, value, setOptions = {}) {
+      assertOpen();
+      const key = normalizeKey(rawKey);
+      if (setOptions.ttlMs === 0) {
+        await store.delete(key);
+        return;
+      }
+      const expiresAt = setOptions.ttlMs === void 0 || setOptions.ttlMs === false ? null : now() + positiveInteger(
+        setOptions.ttlMs,
+        "cache ttlMs"
+      );
+      await adapter.set(
+        key,
+        value,
+        {
+          expiresAt,
+          tags: normalizeTags(setOptions.tags),
+          paths: normalizePaths(setOptions.paths)
+        }
+      );
+      count("sets", "set");
+    },
+    async delete(rawKey) {
+      assertOpen();
+      const removed = await adapter.delete(
+        normalizeKey(rawKey)
+      );
+      if (removed) {
+        count("deletes", "delete");
+      }
+      return removed;
+    },
+    async clear() {
+      assertOpen();
+      const removed = await adapter.clear();
+      if (removed > 0) {
+        counters.invalidations += removed;
+        metrics?.record("invalidate", removed);
+      }
+      return removed;
+    },
+    async revalidateTag(rawTag) {
+      assertOpen();
+      const removed = await adapter.revalidateTag(
+        normalizeTag2(rawTag)
+      );
+      if (removed > 0) {
+        counters.invalidations += removed;
+        metrics?.record("invalidate", removed);
+      }
+      return removed;
+    },
+    async revalidatePath(rawPath) {
+      assertOpen();
+      const removed = await adapter.revalidatePath(
+        normalizePath2(rawPath)
+      );
+      if (removed > 0) {
+        counters.invalidations += removed;
+        metrics?.record("invalidate", removed);
+      }
+      return removed;
+    },
+    async getOrSet(rawKey, loader, loadOptions = {}) {
+      assertOpen();
+      if (typeof loader !== "function") {
+        throw new TypeError(
+          "BCP Cache: loader must be a function."
+        );
+      }
+      const key = normalizeKey(rawKey);
+      const cached = await store.get(key);
+      if (cached !== void 0) {
+        return cached;
+      }
+      const pending = inFlight2.get(key);
+      if (pending) {
+        return await pending;
+      }
+      const promise = loadWithStampedeProtection(
+        key,
+        loader,
+        loadOptions
+      );
+      inFlight2.set(key, promise);
+      metrics?.setInFlight?.(inFlight2.size);
+      try {
+        return await promise;
+      } finally {
+        inFlight2.delete(key);
+        metrics?.setInFlight?.(inFlight2.size);
+      }
+    },
+    async stats() {
+      assertOpen();
+      return {
+        ...counters,
+        inFlight: inFlight2.size,
+        adapterEntries: adapter.entries ? await adapter.entries() : void 0
+      };
+    },
+    async close() {
+      if (closed) {
+        return;
+      }
+      closed = true;
+      inFlight2.clear();
+      metrics?.setInFlight?.(0);
+      const lockClose = lock && !Object.is(lock, adapter) ? lock.close?.() : void 0;
+      await Promise.all([
+        adapter.close?.(),
+        lockClose
+      ]);
+    }
+  };
+  return store;
+  async function loadWithStampedeProtection(key, loader, loadOptions) {
+    if (!lock) {
+      return executeLoader(
+        key,
+        loader,
+        loadOptions
+      );
+    }
+    const lockTtlMs = positiveInteger(
+      loadOptions.lockTtlMs ?? DEFAULT_LOCK_TTL_MS,
+      "lock ttlMs"
+    );
+    const waitTimeoutMs = nonNegativeInteger(
+      loadOptions.waitTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS,
+      "lock waitTimeoutMs"
+    );
+    const pollIntervalMs = positiveInteger(
+      loadOptions.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+      "lock pollIntervalMs"
+    );
+    const ownerId = normalizeOwnerId(idFactory());
+    const lockKey = `cache-load:${key}`;
+    if (await lock.acquire(
+      lockKey,
+      ownerId,
+      lockTtlMs
+    )) {
+      count(
+        "lockAcquired",
+        "lock-acquired"
+      );
+      return executeUnderLock(
+        key,
+        ownerId,
+        lockKey,
+        lockTtlMs,
+        loader,
+        loadOptions
+      );
+    }
+    count(
+      "lockContentions",
+      "lock-contention"
+    );
+    const waitStartedAt = Date.now();
+    while (Date.now() - waitStartedAt < waitTimeoutMs) {
+      await sleep(pollIntervalMs);
+      const cached = await store.get(key);
+      if (cached !== void 0) {
+        return cached;
+      }
+    }
+    count("lockTimeouts", "lock-timeout");
+    if (loadOptions.onLockTimeout === "error") {
+      throw new Error(
+        `BCP Cache: timed out waiting for distributed cache lock for "${key}".`
+      );
+    }
+    if (await lock.acquire(
+      lockKey,
+      ownerId,
+      lockTtlMs
+    )) {
+      count(
+        "lockAcquired",
+        "lock-acquired"
+      );
+      return executeUnderLock(
+        key,
+        ownerId,
+        lockKey,
+        lockTtlMs,
+        loader,
+        loadOptions
+      );
+    }
+    return executeLoader(
+      key,
+      loader,
+      loadOptions
+    );
+  }
+  async function executeUnderLock(key, ownerId, lockKey, lockTtlMs, loader, loadOptions) {
+    let timer;
+    let active = true;
+    if (lock?.extend) {
+      const intervalMs = Math.max(
+        1,
+        Math.floor(lockTtlMs / 3)
+      );
+      const heartbeat = async () => {
+        if (!active) {
+          return;
+        }
+        try {
+          await lock.extend?.(
+            lockKey,
+            ownerId,
+            lockTtlMs
+          );
+        } catch {
+        } finally {
+          if (active) {
+            timer = setTimeout(
+              heartbeat,
+              intervalMs
+            );
+          }
+        }
+      };
+      timer = setTimeout(
+        heartbeat,
+        intervalMs
+      );
+    }
+    try {
+      const cached = await store.get(key);
+      if (cached !== void 0) {
+        return cached;
+      }
+      return await executeLoader(
+        key,
+        loader,
+        loadOptions
+      );
+    } finally {
+      active = false;
+      if (timer) {
+        clearTimeout(timer);
+      }
+      await lock?.release(
+        lockKey,
+        ownerId
+      );
+    }
+  }
+  async function executeLoader(key, loader, loadOptions) {
+    count("loads", "load");
+    try {
+      const value = await loader();
+      await store.set(
+        key,
+        value,
+        loadOptions
+      );
+      return value;
+    } catch (error) {
+      count(
+        "loadErrors",
+        "load-error"
+      );
+      throw error;
+    }
+  }
+  function count(key, event, value = 1) {
+    counters[key] += value;
+    metrics?.record(event, value);
+  }
+  function assertOpen() {
+    if (closed) {
+      throw new Error(
+        "BCP Cache: cache store is closed."
+      );
+    }
+  }
+}
+function createCacheMetrics(registry, options = {}) {
+  const prefix = normalizeMetricPrefix(
+    options.prefix ?? "bcp_cache"
+  );
+  const operations = registry.counter(
+    `${prefix}_operations_total`,
+    {
+      help: "BCP Cache operations by event.",
+      labelNames: [
+        "event"
+      ]
+    }
+  );
+  const inFlight2 = registry.gauge(
+    `${prefix}_in_flight`,
+    {
+      help: "BCP Cache local in-flight loaders."
+    }
+  );
+  return {
+    record(event, value = 1) {
+      operations.inc(
+        value,
+        {
+          event
+        }
+      );
+    },
+    setInFlight(value) {
+      inFlight2.set(value);
+    }
+  };
+}
+function createRedisCacheAdapter(options) {
+  assertRedisClient(options.client);
+  const namespace = normalizeNamespace(
+    options.namespace ?? "bcp:{cache}"
+  );
+  const now = options.now ?? Date.now;
+  const serialize = options.serialize ?? JSON.stringify;
+  const deserialize = options.deserialize ?? JSON.parse;
+  const client = options.client;
+  const adapter = {
+    namespace,
+    async get(rawKey) {
+      const key = normalizeKey(rawKey);
+      const entryKey = redisEntryKey(
+        namespace,
+        key
+      );
+      const raw = redisString(
+        await client.sendCommand([
+          "GET",
+          entryKey
+        ])
+      );
+      if (raw === null) {
+        await client.sendCommand([
+          "SREM",
+          redisAllKeysKey(namespace),
+          entryKey
+        ]);
+        return null;
+      }
+      const stored = parseStoredRecord(raw);
+      if (stored.expiresAt !== null && stored.expiresAt <= now()) {
+        await deleteStoredRecord(
+          stored,
+          entryKey
+        );
+        return null;
+      }
+      return {
+        key: stored.key,
+        value: deserialize(stored.value),
+        expiresAt: stored.expiresAt,
+        tags: [...stored.tags],
+        paths: [...stored.paths],
+        createdAt: stored.createdAt,
+        updatedAt: stored.updatedAt
+      };
+    },
+    async set(rawKey, value, setOptions = {}) {
+      const key = normalizeKey(rawKey);
+      const entryKey = redisEntryKey(
+        namespace,
+        key
+      );
+      const timestamp = now();
+      const tags = normalizeTags(setOptions.tags);
+      const paths = normalizePaths(setOptions.paths);
+      const current = await adapter.get(key);
+      const stored = {
+        key,
+        value: serializeValue(
+          value,
+          serialize
+        ),
+        expiresAt: normalizeExpiresAt(
+          setOptions.expiresAt
+        ),
+        tags,
+        paths,
+        tagIndexKeys: tags.map(
+          (tag) => redisTagKey(
+            namespace,
+            tag
+          )
+        ),
+        pathIndexPairs: paths.map((pathname) => ({
+          path: pathname,
+          key: redisPathKey(
+            namespace,
+            pathname
+          )
+        })),
+        createdAt: current?.createdAt ?? timestamp,
+        updatedAt: timestamp
+      };
+      const ttlMs = stored.expiresAt === null ? 0 : Math.max(
+        1,
+        stored.expiresAt - timestamp
+      );
+      await evalRedis(
+        client,
+        REDIS_SET_SCRIPT,
+        [
+          entryKey,
+          redisAllKeysKey(namespace),
+          redisPathsIndexKey(namespace)
+        ],
+        [
+          JSON.stringify(stored),
+          String(ttlMs)
+        ]
+      );
+    },
+    async delete(rawKey) {
+      const key = normalizeKey(rawKey);
+      const entryKey = redisEntryKey(
+        namespace,
+        key
+      );
+      const result = await evalRedis(
+        client,
+        REDIS_DELETE_SCRIPT,
+        [
+          entryKey,
+          redisAllKeysKey(namespace),
+          redisPathsIndexKey(namespace)
+        ],
+        []
+      );
+      return Number(result) > 0;
+    },
+    async clear() {
+      const entryKeys = redisStringArray(
+        await client.sendCommand([
+          "SMEMBERS",
+          redisAllKeysKey(namespace)
+        ])
+      );
+      let removed = 0;
+      for (const entryKey of entryKeys) {
+        const result = await evalRedis(
+          client,
+          REDIS_DELETE_SCRIPT,
+          [
+            entryKey,
+            redisAllKeysKey(namespace),
+            redisPathsIndexKey(namespace)
+          ],
+          []
+        );
+        removed += Number(result) > 0 ? 1 : 0;
+      }
+      await client.sendCommand([
+        "DEL",
+        redisAllKeysKey(namespace),
+        redisPathsIndexKey(namespace)
+      ]);
+      return removed;
+    },
+    async revalidateTag(rawTag) {
+      const tag = normalizeTag2(rawTag);
+      const tagKey = redisTagKey(
+        namespace,
+        tag
+      );
+      const result = await evalRedis(
+        client,
+        REDIS_INVALIDATE_SET_SCRIPT,
+        [
+          tagKey,
+          redisAllKeysKey(namespace),
+          redisPathsIndexKey(namespace)
+        ],
+        []
+      );
+      return Number(result) || 0;
+    },
+    async revalidatePath(rawPath) {
+      const pathname = normalizePath2(rawPath);
+      const registeredPaths = redisStringArray(
+        await client.sendCommand([
+          "SMEMBERS",
+          redisPathsIndexKey(namespace)
+        ])
+      );
+      const matches = registeredPaths.filter(
+        (path) => pathMatches2(path, pathname)
+      ).map((path) => ({
+        path,
+        key: redisPathKey(
+          namespace,
+          path
+        )
+      }));
+      if (matches.length === 0) {
+        return 0;
+      }
+      const result = await evalRedis(
+        client,
+        REDIS_INVALIDATE_PATHS_SCRIPT,
+        [
+          redisAllKeysKey(namespace),
+          redisPathsIndexKey(namespace)
+        ],
+        [
+          JSON.stringify(matches)
+        ]
+      );
+      return Number(result) || 0;
+    },
+    async entries() {
+      return Number(
+        await client.sendCommand([
+          "SCARD",
+          redisAllKeysKey(namespace)
+        ])
+      ) || 0;
+    },
+    async close() {
+      await options.close?.();
+    }
+  };
+  return adapter;
+  async function deleteStoredRecord(_stored, entryKey) {
+    await evalRedis(
+      client,
+      REDIS_DELETE_SCRIPT,
+      [
+        entryKey,
+        redisAllKeysKey(namespace),
+        redisPathsIndexKey(namespace)
+      ],
+      []
+    );
+  }
+}
+function createRedisCacheLockAdapter(options) {
+  assertRedisClient(options.client);
+  const namespace = normalizeNamespace(
+    options.namespace ?? "bcp:{cache}"
+  );
+  const client = options.client;
+  return {
+    namespace,
+    async acquire(rawKey, rawOwnerId, ttlMs) {
+      const key = redisLockKey(
+        namespace,
+        normalizeKey(rawKey)
+      );
+      const ownerId = normalizeOwnerId(rawOwnerId);
+      const ttl = positiveInteger(
+        ttlMs,
+        "lock ttlMs"
+      );
+      const result = redisString(
+        await client.sendCommand([
+          "SET",
+          key,
+          ownerId,
+          "NX",
+          "PX",
+          String(ttl)
+        ])
+      );
+      return result === "OK";
+    },
+    async extend(rawKey, rawOwnerId, ttlMs) {
+      const result = await evalRedis(
+        client,
+        REDIS_LOCK_EXTEND_SCRIPT,
+        [
+          redisLockKey(
+            namespace,
+            normalizeKey(rawKey)
+          )
+        ],
+        [
+          normalizeOwnerId(rawOwnerId),
+          String(
+            positiveInteger(
+              ttlMs,
+              "lock ttlMs"
+            )
+          )
+        ]
+      );
+      return Number(result) > 0;
+    },
+    async release(rawKey, rawOwnerId) {
+      const result = await evalRedis(
+        client,
+        REDIS_LOCK_RELEASE_SCRIPT,
+        [
+          redisLockKey(
+            namespace,
+            normalizeKey(rawKey)
+          )
+        ],
+        [
+          normalizeOwnerId(rawOwnerId)
+        ]
+      );
+      return Number(result) > 0;
+    },
+    async close() {
+      await options.close?.();
+    }
+  };
+}
+function cloneEntry(entry) {
+  return {
+    ...entry,
+    tags: [...entry.tags],
+    paths: [...entry.paths]
+  };
+}
+function isExpired(entry, now) {
+  return entry.expiresAt !== null && entry.expiresAt <= now;
+}
+function normalizeExpiresAt(value) {
+  if (value === void 0 || value === null) {
+    return null;
+  }
+  assertFiniteTimestamp(value, "cache expiresAt");
+  return value;
+}
+function normalizeKey(value) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized) {
+    throw new TypeError(
+      "BCP Cache: key must be a non-empty string."
+    );
+  }
+  return normalized;
+}
+function normalizeOwnerId(value) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized) {
+    throw new TypeError(
+      "BCP Cache: lock ownerId must be a non-empty string."
+    );
+  }
+  return normalized;
+}
+function normalizeTag2(value) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized) {
+    throw new TypeError(
+      "BCP Cache: cache tags cannot be empty."
+    );
+  }
+  return normalized;
+}
+function normalizeTags(values) {
+  return Array.from(
+    new Set(
+      (values ?? []).map(normalizeTag2)
+    )
+  ).sort();
+}
+function normalizePath2(value) {
+  let pathname = String(value ?? "").trim();
+  if (!pathname) {
+    return "/";
+  }
+  try {
+    if (pathname.startsWith("http://") || pathname.startsWith("https://")) {
+      pathname = new URL(pathname).pathname;
+    }
+  } catch {
+  }
+  pathname = pathname.split("?")[0].split("#")[0];
+  if (!pathname.startsWith("/")) {
+    pathname = `/${pathname}`;
+  }
+  if (pathname.length > 1 && pathname.endsWith("/")) {
+    pathname = pathname.slice(0, -1);
+  }
+  return pathname;
+}
+function normalizePaths(values) {
+  return Array.from(
+    new Set(
+      (values ?? []).map(normalizePath2)
+    )
+  ).sort();
+}
+function pathMatches2(cachedPath, invalidatedPath) {
+  if (invalidatedPath === "/") {
+    return true;
+  }
+  return cachedPath === invalidatedPath || cachedPath.startsWith(
+    `${invalidatedPath}/`
+  );
+}
+function positiveInteger(value, field) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new TypeError(
+      `BCP Cache: ${field} must be a positive integer.`
+    );
+  }
+  return value;
+}
+function nonNegativeInteger(value, field) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new TypeError(
+      `BCP Cache: ${field} must be a non-negative integer.`
+    );
+  }
+  return value;
+}
+function assertFiniteTimestamp(value, field) {
+  if (!Number.isFinite(value)) {
+    throw new TypeError(
+      `BCP Cache: ${field} must be a finite number.`
+    );
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+function normalizeMetricPrefix(value) {
+  const normalized = value.trim();
+  if (!/^[a-zA-Z_:][a-zA-Z0-9_:]*$/.test(normalized)) {
+    throw new TypeError(
+      "BCP Cache: metrics prefix contains unsupported characters."
+    );
+  }
+  return normalized;
+}
+function normalizeNamespace(value) {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new TypeError(
+      "BCP Cache: Redis namespace must be a non-empty string."
+    );
+  }
+  return normalized.replace(/:+$/g, "");
+}
+function encodeRedisPart(value) {
+  return encodeURIComponent(value);
+}
+function redisEntryKey(namespace, key) {
+  return `${namespace}:entry:${encodeRedisPart(key)}`;
+}
+function redisTagKey(namespace, tag) {
+  return `${namespace}:tag:${encodeRedisPart(tag)}`;
+}
+function redisPathKey(namespace, pathname) {
+  return `${namespace}:path:${encodeRedisPart(pathname)}`;
+}
+function redisAllKeysKey(namespace) {
+  return `${namespace}:entries`;
+}
+function redisPathsIndexKey(namespace) {
+  return `${namespace}:paths`;
+}
+function redisLockKey(namespace, key) {
+  return `${namespace}:lock:${encodeRedisPart(key)}`;
+}
+function serializeValue(value, serialize) {
+  const result = serialize(value);
+  if (typeof result !== "string") {
+    throw new TypeError(
+      "BCP Cache: Redis serializer must return a string."
+    );
+  }
+  return result;
+}
+function parseStoredRecord(value) {
+  const parsed = JSON.parse(value);
+  if (!parsed || typeof parsed.key !== "string" || typeof parsed.value !== "string" || !Array.isArray(parsed.tags) || !Array.isArray(parsed.paths) || !Array.isArray(parsed.tagIndexKeys) || !Array.isArray(parsed.pathIndexPairs) || typeof parsed.createdAt !== "number" || typeof parsed.updatedAt !== "number") {
+    throw new Error(
+      "BCP Cache: invalid Redis cache record."
+    );
+  }
+  return parsed;
+}
+function assertRedisClient(client) {
+  if (!client || typeof client.sendCommand !== "function") {
+    throw new TypeError(
+      "BCP Cache: Redis adapter requires a sendCommand client."
+    );
+  }
+}
+function redisString(value) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value instanceof Uint8Array) {
+    return new TextDecoder().decode(value);
+  }
+  return String(value);
+}
+function redisStringArray(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map(redisString).filter(
+    (item) => item !== null
+  );
+}
+async function evalRedis(client, script, keys, args) {
+  return client.sendCommand([
+    "EVAL",
+    script,
+    String(keys.length),
+    ...keys,
+    ...args
+  ]);
+}
+var REDIS_SET_SCRIPT = `
+local old = redis.call('GET', KEYS[1])
+if old then
+    local previous = cjson.decode(old)
+    for _, tagKey in ipairs(previous.tagIndexKeys or {}) do
+        redis.call('SREM', tagKey, KEYS[1])
+        if redis.call('SCARD', tagKey) == 0 then redis.call('DEL', tagKey) end
+    end
+    for _, pair in ipairs(previous.pathIndexPairs or {}) do
+        redis.call('SREM', pair.key, KEYS[1])
+        if redis.call('SCARD', pair.key) == 0 then
+            redis.call('DEL', pair.key)
+            redis.call('SREM', KEYS[3], pair.path)
+        end
+    end
+end
+local record = cjson.decode(ARGV[1])
+if tonumber(ARGV[2]) > 0 then
+    redis.call('SET', KEYS[1], ARGV[1], 'PX', ARGV[2])
+else
+    redis.call('SET', KEYS[1], ARGV[1])
+end
+redis.call('SADD', KEYS[2], KEYS[1])
+for _, tagKey in ipairs(record.tagIndexKeys or {}) do
+    redis.call('SADD', tagKey, KEYS[1])
+end
+for _, pair in ipairs(record.pathIndexPairs or {}) do
+    redis.call('SADD', pair.key, KEYS[1])
+    redis.call('SADD', KEYS[3], pair.path)
+end
+return 1
+`;
+var REDIS_DELETE_SCRIPT = `
+local raw = redis.call('GET', KEYS[1])
+if not raw then
+    redis.call('SREM', KEYS[2], KEYS[1])
+    return 0
+end
+local record = cjson.decode(raw)
+for _, tagKey in ipairs(record.tagIndexKeys or {}) do
+    redis.call('SREM', tagKey, KEYS[1])
+    if redis.call('SCARD', tagKey) == 0 then redis.call('DEL', tagKey) end
+end
+for _, pair in ipairs(record.pathIndexPairs or {}) do
+    redis.call('SREM', pair.key, KEYS[1])
+    if redis.call('SCARD', pair.key) == 0 then
+        redis.call('DEL', pair.key)
+        redis.call('SREM', KEYS[3], pair.path)
+    end
+end
+redis.call('DEL', KEYS[1])
+redis.call('SREM', KEYS[2], KEYS[1])
+return 1
+`;
+var REDIS_INVALIDATE_SET_SCRIPT = `
+local members = redis.call('SMEMBERS', KEYS[1])
+local removed = 0
+for _, entryKey in ipairs(members) do
+    local raw = redis.call('GET', entryKey)
+    if raw then
+        local record = cjson.decode(raw)
+        for _, tagKey in ipairs(record.tagIndexKeys or {}) do
+            redis.call('SREM', tagKey, entryKey)
+            if redis.call('SCARD', tagKey) == 0 then redis.call('DEL', tagKey) end
+        end
+        for _, pair in ipairs(record.pathIndexPairs or {}) do
+            redis.call('SREM', pair.key, entryKey)
+            if redis.call('SCARD', pair.key) == 0 then
+                redis.call('DEL', pair.key)
+                redis.call('SREM', KEYS[3], pair.path)
+            end
+        end
+        redis.call('DEL', entryKey)
+        redis.call('SREM', KEYS[2], entryKey)
+        removed = removed + 1
+    else
+        redis.call('SREM', KEYS[2], entryKey)
+    end
+end
+redis.call('DEL', KEYS[1])
+return removed
+`;
+var REDIS_INVALIDATE_PATHS_SCRIPT = `
+local pairs = cjson.decode(ARGV[1])
+local seen = {}
+local removed = 0
+for _, pair in ipairs(pairs) do
+    local members = redis.call('SMEMBERS', pair.key)
+    for _, entryKey in ipairs(members) do
+        if not seen[entryKey] then
+            seen[entryKey] = true
+            local raw = redis.call('GET', entryKey)
+            if raw then
+                local record = cjson.decode(raw)
+                for _, tagKey in ipairs(record.tagIndexKeys or {}) do
+                    redis.call('SREM', tagKey, entryKey)
+                    if redis.call('SCARD', tagKey) == 0 then redis.call('DEL', tagKey) end
+                end
+                for _, pathPair in ipairs(record.pathIndexPairs or {}) do
+                    redis.call('SREM', pathPair.key, entryKey)
+                    if redis.call('SCARD', pathPair.key) == 0 then
+                        redis.call('DEL', pathPair.key)
+                        redis.call('SREM', KEYS[2], pathPair.path)
+                    end
+                end
+                redis.call('DEL', entryKey)
+                redis.call('SREM', KEYS[1], entryKey)
+                removed = removed + 1
+            else
+                redis.call('SREM', KEYS[1], entryKey)
+            end
+        end
+    end
+    redis.call('DEL', pair.key)
+    redis.call('SREM', KEYS[2], pair.path)
+end
+return removed
+`;
+var REDIS_LOCK_RELEASE_SCRIPT = `
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+    return redis.call('DEL', KEYS[1])
+end
+return 0
+`;
+var REDIS_LOCK_EXTEND_SCRIPT = `
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+    return redis.call('PEXPIRE', KEYS[1], ARGV[2])
+end
+return 0
+`;
+export {
+  cache,
+  clearCache,
+  createCacheMetrics,
+  createCacheStore,
+  createMemoryCacheAdapter,
+  createMemoryCacheLockAdapter,
+  createRedisCacheAdapter,
+  createRedisCacheLockAdapter,
+  dedupe,
+  getCacheStats,
+  revalidatePath,
+  revalidateTag
+};