dialcache 0.1.1

package/dist/index.js

@@ -0,0 +1,956 @@
+import {
+  DialCacheRedisPayloadEncodingError,
+  DialCacheRedisPayloadError
+} from "./chunk-S5VCTJID.js";
+
+// src/config.ts
+var CacheLayer = /* @__PURE__ */ ((CacheLayer2) => {
+  CacheLayer2["LOCAL"] = "local";
+  CacheLayer2["REMOTE"] = "remote";
+  return CacheLayer2;
+})(CacheLayer || {});
+var deterministicRampSampler = ({ key, layer }) => stablePercent(`${key.urn}:${layer}`);
+var randomRampSampler = () => Math.random() * 100;
+var DEFAULT_WATERMARK_TTL_SEC = 3600 * 4;
+var DialCacheKeyConfig = class _DialCacheKeyConfig {
+  ttlSec;
+  ramp;
+  constructor(config) {
+    this.ttlSec = { ...config.ttlSec };
+    this.ramp = { ...config.ramp };
+  }
+  static enabled(ttlSec) {
+    return new _DialCacheKeyConfig({
+      ttlSec: {
+        ["local" /* LOCAL */]: ttlSec,
+        ["remote" /* REMOTE */]: ttlSec
+      },
+      ramp: {
+        ["local" /* LOCAL */]: 100,
+        ["remote" /* REMOTE */]: 100
+      }
+    });
+  }
+};
+function stablePercent(value) {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0) / 4294967296 * 100;
+}
+
+// src/context.ts
+import { AsyncLocalStorage } from "async_hooks";
+var DialCacheContext = class {
+  storage = new AsyncLocalStorage();
+  isEnabled() {
+    return this.storage.getStore() ?? false;
+  }
+  enable(fn) {
+    return this.run(true, fn);
+  }
+  disable(fn) {
+    return this.run(false, fn);
+  }
+  async run(enabled, fn) {
+    return await this.storage.run(enabled, async () => await fn());
+  }
+};
+
+// src/metrics.ts
+import { Counter, Histogram, register as defaultRegistry } from "prom-client";
+var NO_CACHE_LAYER = "noop";
+var TIMER_BUCKETS = [1e-3, 5e-3, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+var SIZE_BUCKETS = [100, 1e3, 1e4, 1e5, 1e6, 1e7];
+var PrometheusDialCacheMetrics = class {
+  requestCounter;
+  missCounter;
+  disabledCounter;
+  errorCounter;
+  invalidationCounter;
+  coalescedCounter;
+  getTimer;
+  fallbackTimer;
+  serializationTimer;
+  sizeHistogram;
+  constructor(options = {}) {
+    const registry = options.registry ?? defaultRegistry;
+    const prefix = options.prefix ?? "";
+    this.disabledCounter = counter(registry, {
+      name: `${prefix}dialcache_disabled_counter`,
+      help: "Requests where DialCache skipped a cache layer.",
+      labelNames: ["use_case", "key_type", "layer", "reason"]
+    });
+    this.missCounter = counter(registry, {
+      name: `${prefix}dialcache_miss_counter`,
+      help: "DialCache cache misses.",
+      labelNames: ["use_case", "key_type", "layer"]
+    });
+    this.requestCounter = counter(registry, {
+      name: `${prefix}dialcache_request_counter`,
+      help: "Total DialCache cache-layer requests.",
+      labelNames: ["use_case", "key_type", "layer"]
+    });
+    this.errorCounter = counter(registry, {
+      name: `${prefix}dialcache_error_counter`,
+      help: "Errors during DialCache cache operations or fallback execution.",
+      labelNames: ["use_case", "key_type", "layer", "error", "in_fallback"]
+    });
+    this.invalidationCounter = counter(registry, {
+      name: `${prefix}dialcache_invalidation_counter`,
+      help: "DialCache invalidation calls by key type and layer.",
+      labelNames: ["key_type", "layer"]
+    });
+    this.coalescedCounter = counter(registry, {
+      name: `${prefix}dialcache_coalesced_counter`,
+      help: "DialCache requests coalesced onto an in-flight cache miss.",
+      labelNames: ["use_case", "key_type"]
+    });
+    this.getTimer = histogram(registry, {
+      name: `${prefix}dialcache_get_timer`,
+      help: "DialCache cache get latency in seconds.",
+      labelNames: ["use_case", "key_type", "layer"],
+      buckets: TIMER_BUCKETS
+    });
+    this.fallbackTimer = histogram(registry, {
+      name: `${prefix}dialcache_fallback_timer`,
+      help: "Time spent in the underlying fallback function in seconds.",
+      labelNames: ["use_case", "key_type", "layer"],
+      buckets: TIMER_BUCKETS
+    });
+    this.serializationTimer = histogram(registry, {
+      name: `${prefix}dialcache_serialization_timer`,
+      help: "DialCache serialization latency in seconds.",
+      labelNames: ["use_case", "key_type", "layer", "operation"],
+      buckets: TIMER_BUCKETS
+    });
+    this.sizeHistogram = histogram(registry, {
+      name: `${prefix}dialcache_size_histogram`,
+      help: "Serialized DialCache value sizes in bytes.",
+      labelNames: ["use_case", "key_type", "layer"],
+      buckets: SIZE_BUCKETS
+    });
+  }
+  request(labels) {
+    this.requestCounter.inc(cacheLabels(labels));
+  }
+  miss(labels) {
+    this.missCounter.inc(cacheLabels(labels));
+  }
+  disabled(labels) {
+    this.disabledCounter.inc({ ...cacheLabels(labels), reason: labels.reason });
+  }
+  error(labels) {
+    this.errorCounter.inc({
+      ...cacheLabels(labels),
+      error: labels.error,
+      in_fallback: String(labels.inFallback)
+    });
+  }
+  invalidation(labels) {
+    this.invalidationCounter.inc({ key_type: labels.keyType, layer: labels.layer });
+  }
+  coalesced(labels) {
+    this.coalescedCounter.inc({ use_case: labels.useCase, key_type: labels.keyType });
+  }
+  observeGet(labels, seconds) {
+    this.getTimer.observe(cacheLabels(labels), seconds);
+  }
+  observeFallback(labels, seconds) {
+    this.fallbackTimer.observe(cacheLabels(labels), seconds);
+  }
+  observeSerialization(labels, seconds) {
+    this.serializationTimer.observe({ ...cacheLabels(labels), operation: labels.operation }, seconds);
+  }
+  observeSize(labels, bytes) {
+    this.sizeHistogram.observe(cacheLabels(labels), bytes);
+  }
+};
+function createPrometheusDialCacheMetrics(options = {}) {
+  return new PrometheusDialCacheMetrics(options);
+}
+function labelsFor(key, layer) {
+  return { useCase: key.useCase, keyType: key.keyType, layer };
+}
+function errorName(error) {
+  return error instanceof Error ? error.name : typeof error;
+}
+function cacheLabels(labels) {
+  return {
+    use_case: labels.useCase,
+    key_type: labels.keyType,
+    layer: labels.layer
+  };
+}
+function counter(registry, config) {
+  return registry.getSingleMetric(config.name) ?? new Counter({ ...config, registers: [registry] });
+}
+function histogram(registry, config) {
+  return registry.getSingleMetric(config.name) ?? new Histogram({ ...config, buckets: [...config.buckets], registers: [registry] });
+}
+
+// src/errors.ts
+var DialCacheError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+};
+var UseCaseIsAlreadyRegisteredError = class extends DialCacheError {
+  constructor(useCase) {
+    super(`Use case already registered: ${useCase}`);
+  }
+};
+var UseCaseNameIsReservedError = class extends DialCacheError {
+  constructor(useCase) {
+    super(`Use case name is reserved: ${useCase}`);
+  }
+};
+var MissingKeyConfigError = class extends DialCacheError {
+  constructor(useCase) {
+    super(`Missing key config for use case: ${useCase}`);
+  }
+};
+
+// src/dialcache.ts
+import { performance as performance3 } from "perf_hooks";
+
+// src/key.ts
+var DialCacheKey = class {
+  keyType;
+  id;
+  useCase;
+  args;
+  urnPrefix;
+  prefix;
+  urn;
+  defaultConfig;
+  serializer;
+  trackForInvalidation;
+  constructor(init) {
+    this.keyType = init.keyType;
+    this.id = init.id;
+    this.useCase = init.useCase;
+    this.args = init.args ?? [];
+    this.defaultConfig = init.defaultConfig ?? null;
+    this.serializer = init.serializer ?? null;
+    this.trackForInvalidation = init.trackForInvalidation ?? false;
+    this.urnPrefix = init.urnPrefix ?? "urn";
+    const rawPrefix = joinUrnComponents(this.urnPrefix, this.keyType, this.id);
+    this.prefix = this.trackForInvalidation ? redisClusterHashTag(invalidationPrefix(this.urnPrefix, this.keyType, this.id)) : rawPrefix;
+    const args = this.args.length > 0 ? `?${this.args.map(([name, value]) => `${encodeComponent(name)}=${encodeComponent(value)}`).join("&")}` : "";
+    this.urn = `${this.prefix}${args}#${encodeComponent(this.useCase)}`;
+  }
+  toString() {
+    return this.urn;
+  }
+};
+function normalizeArgs(args) {
+  return Object.entries(args).filter(([, value]) => value !== void 0).map(([name, value]) => [name, String(value)]).sort(([left], [right]) => compareCodePoints(left, right));
+}
+function invalidationPrefix(urnPrefix, keyType, id) {
+  assertRedisHashTagComponent("urnPrefix", urnPrefix);
+  assertRedisHashTagComponent("keyType", keyType);
+  assertRedisHashTagComponent("id", id);
+  return joinUrnComponents(urnPrefix, keyType, id);
+}
+function redisClusterHashTag(value) {
+  assertRedisHashTagComponent("value", value);
+  return `{${value}}`;
+}
+function assertRedisHashTagComponent(name, value) {
+  if (value.includes("{") || value.includes("}")) {
+    throw new Error(`Redis Cluster hash tag components must not contain braces: ${name}`);
+  }
+}
+function joinUrnComponents(...components) {
+  return components.map(encodeComponent).join(":");
+}
+function encodeComponent(value) {
+  return encodeURIComponent(value);
+}
+function compareCodePoints(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+// src/internal/local-cache.ts
+import { performance } from "perf_hooks";
+import { LRUCache } from "lru-cache";
+
+// src/internal/runtime-config.ts
+async function fetchKeyConfig(configProvider, key) {
+  return await configProvider(key) ?? key.defaultConfig;
+}
+async function resolveLayerConfigResult(options) {
+  const config = options.config;
+  if (config === null) {
+    return { status: "disabled", reason: "missing_config" };
+  }
+  const ttlSec = config.ttlSec[options.layer];
+  if (ttlSec === void 0) {
+    return { status: "disabled", reason: "missing_config" };
+  }
+  if (!Number.isSafeInteger(ttlSec) || ttlSec <= 0) {
+    return { status: "disabled", reason: "invalid_ttl" };
+  }
+  const configuredRamp = config.ramp[options.layer];
+  if (configuredRamp === void 0) {
+    return { status: "disabled", reason: "missing_config" };
+  }
+  if (!Number.isFinite(configuredRamp)) {
+    return { status: "disabled", reason: "ramped_down" };
+  }
+  const ramp = clampPercentage(configuredRamp);
+  if (ramp <= 0) {
+    return { status: "disabled", reason: "ramped_down" };
+  }
+  if (ramp >= 100) {
+    return { status: "enabled", config: { ttlSec, ramp } };
+  }
+  const sample = await options.rampSampler({ key: options.key, layer: options.layer, ramp });
+  if (!Number.isFinite(sample)) {
+    return { status: "disabled", reason: "ramped_down" };
+  }
+  return clampPercentage(sample) < ramp ? { status: "enabled", config: { ttlSec, ramp } } : { status: "disabled", reason: "ramped_down" };
+}
+function clampPercentage(value) {
+  if (value <= 0) {
+    return 0;
+  }
+  if (value >= 100) {
+    return 100;
+  }
+  return value;
+}
+
+// src/internal/local-cache.ts
+var LocalCache = class {
+  constructor(configProvider, rampSampler, maxSize) {
+    this.configProvider = configProvider;
+    this.rampSampler = rampSampler;
+    this.cache = maxSize === 0 ? null : new LRUCache({
+      // Weight every entry as one so large configured limits remain sparse
+      // instead of eagerly preallocating max-sized storage arrays.
+      maxSize,
+      // Read a fresh monotonic integer clock and avoid lru-cache's zero
+      // timestamp sentinel when the process or a fake clock starts at 0.
+      perf: { now: () => Math.floor(performance.now()) + 1 },
+      ttlResolution: 0
+    });
+  }
+  configProvider;
+  rampSampler;
+  cache;
+  async get(key, fallback) {
+    const result = await this.getIfPresentResult(key);
+    if (result.status === "hit") {
+      return result.value;
+    }
+    const value = await fallback();
+    if (result.status === "miss") {
+      await this.put(key, value, result.config);
+    }
+    return value;
+  }
+  async getIfPresent(key) {
+    const result = await this.getIfPresentResult(key);
+    return result.status === "hit" ? result.value : void 0;
+  }
+  async getIfPresentResult(key, keyConfig) {
+    const layerConfig = await this.resolveLocalLayerConfig(key, keyConfig);
+    if (layerConfig.status === "disabled") {
+      return layerConfig;
+    }
+    const hit = this.cache?.get(key.urn);
+    if (hit !== void 0) {
+      return { status: "hit", value: hit.value };
+    }
+    return { status: "miss", config: layerConfig.config };
+  }
+  async put(key, value, config) {
+    const ttlSec = config?.ttlSec ?? await this.resolveLocalTtlSec(key);
+    if (ttlSec === null) {
+      return;
+    }
+    const ttlMs = ttlSec * 1e3 - 1;
+    this.cache?.set(key.urn, { value }, { size: 1, ttl: ttlMs });
+  }
+  async flushAll() {
+    this.cache?.clear();
+  }
+  async resolveLocalLayerConfig(key, keyConfig) {
+    const config = keyConfig === void 0 ? await fetchKeyConfig(this.configProvider, key) : keyConfig;
+    return await resolveLayerConfigResult({
+      config,
+      key,
+      layer: "local" /* LOCAL */,
+      rampSampler: this.rampSampler
+    });
+  }
+  async resolveLocalTtlSec(key) {
+    const layerConfig = await this.resolveLocalLayerConfig(key);
+    return layerConfig.status === "enabled" ? layerConfig.config.ttlSec : null;
+  }
+};
+
+// src/internal/redis-cache.ts
+import { performance as performance2 } from "perf_hooks";
+
+// src/serializer.ts
+var JSON_UNDEFINED_SENTINEL = "__dialcache_json_undefined_v1__";
+var JsonSerializer = class {
+  async dump(value) {
+    if (value === void 0) {
+      return JSON_UNDEFINED_SENTINEL;
+    }
+    const payload = JSON.stringify(value);
+    if (payload === void 0) {
+      throw new Error("DialCache JSON serializer cannot serialize this value");
+    }
+    return payload;
+  }
+  async load(value) {
+    const payload = Buffer.isBuffer(value) ? value.toString("utf8") : value;
+    if (payload === JSON_UNDEFINED_SENTINEL) {
+      return void 0;
+    }
+    return JSON.parse(payload);
+  }
+};
+
+// src/internal/redis-cache.ts
+var defaultSerializer = new JsonSerializer();
+var REDIS_FRAME_KEY_SUFFIX = ":dialcache-frame-v1";
+var RedisCache = class {
+  configProvider;
+  rampSampler;
+  keyPrefix;
+  defaultSerializer;
+  watermarkTtlMs;
+  createClient;
+  metrics;
+  clientPromise;
+  constructor(options) {
+    this.configProvider = options.configProvider;
+    this.rampSampler = options.rampSampler;
+    this.keyPrefix = options.redis.keyPrefix ?? "";
+    this.defaultSerializer = options.redis.serializer ?? defaultSerializer;
+    const watermarkTtlSec = options.redis.watermarkTtlSec ?? DEFAULT_WATERMARK_TTL_SEC;
+    if (!Number.isSafeInteger(watermarkTtlSec) || watermarkTtlSec <= 0) {
+      throw new RangeError("Redis watermarkTtlSec must be a positive safe integer");
+    }
+    this.watermarkTtlMs = watermarkTtlSec * 1e3;
+    if (!Number.isSafeInteger(this.watermarkTtlMs)) {
+      throw new RangeError("Redis watermarkTtlSec is too large");
+    }
+    this.metrics = options.metrics;
+    if (options.redis.client === void 0 && options.redis.createClient === void 0) {
+      throw new Error("Redis config requires either client or createClient");
+    }
+    this.createClient = options.redis.createClient ?? null;
+    this.clientPromise = options.redis.client === void 0 ? null : Promise.resolve(options.redis.client);
+  }
+  async get(key) {
+    const result = await this.getResult(key);
+    return result.status === "hit" ? result.value : void 0;
+  }
+  async getResult(key, keyConfig) {
+    const layerConfig = await this.resolveRemoteLayerConfig(key, keyConfig);
+    if (layerConfig.status === "disabled") {
+      return layerConfig;
+    }
+    return await this.getWithResolvedConfig(key, layerConfig.config);
+  }
+  async getWithResolvedConfig(key, layerConfig) {
+    const client = await this.resolveClient();
+    const redisKey = this.redisKey(key);
+    const payload = await client.read({
+      valueKey: redisKey,
+      ...key.trackForInvalidation ? { watermarkKey: this.redisWatermarkKeyFromKey(key) } : {}
+    });
+    if (payload === null) {
+      return { status: "miss", config: layerConfig };
+    }
+    const start = performance2.now();
+    try {
+      const value = await this.serializerFor(key).load(payload);
+      return { status: "hit", value };
+    } catch (error) {
+      this.recordMetric((metrics) => metrics.error({ ...labelsFor(key, "remote" /* REMOTE */), error: errorName(error), inFallback: false }));
+      return { status: "miss", config: layerConfig };
+    } finally {
+      this.recordMetric((metrics) => metrics.observeSerialization({ ...labelsFor(key, "remote" /* REMOTE */), operation: "load" }, elapsedSeconds(start)));
+    }
+  }
+  async put(key, value, config) {
+    const ttlSec = config?.ttlSec ?? await this.resolveRemoteTtlSec(key);
+    if (ttlSec === null) {
+      return true;
+    }
+    const start = performance2.now();
+    let serialized;
+    try {
+      serialized = await this.serializerFor(key).dump(value);
+    } finally {
+      this.recordMetric((metrics) => metrics.observeSerialization({ ...labelsFor(key, "remote" /* REMOTE */), operation: "dump" }, elapsedSeconds(start)));
+    }
+    this.recordMetric((metrics) => metrics.observeSize(labelsFor(key, "remote" /* REMOTE */), payloadSize(serialized)));
+    const client = await this.resolveClient();
+    const cacheTtlMs = ttlSec * 1e3;
+    if (!Number.isSafeInteger(cacheTtlMs)) {
+      throw new RangeError("Redis cache TTL is too large");
+    }
+    const request = {
+      valueKey: this.redisKey(key),
+      cacheTtlMs,
+      value: serialized
+    };
+    return key.trackForInvalidation ? await client.write({
+      ...request,
+      watermarkKey: this.redisWatermarkKeyFromKey(key),
+      watermarkTtlFloorMs: this.watermarkTtlMs
+    }) : await client.write(request);
+  }
+  async invalidate(keyType, id, futureBufferMs = 0, urnPrefix = "urn") {
+    const client = await this.resolveClient();
+    await client.invalidate({
+      watermarkKey: this.redisWatermarkKey(urnPrefix, keyType, id),
+      futureBufferMs,
+      watermarkTtlFloorMs: this.watermarkTtlMs
+    });
+  }
+  async flushAll() {
+    const client = await this.resolveClient();
+    await client.flushAll();
+  }
+  redisKey(key) {
+    return `${this.keyPrefix}${key.urn}${REDIS_FRAME_KEY_SUFFIX}`;
+  }
+  redisWatermarkKey(urnPrefix, keyType, id) {
+    return `${this.keyPrefix}${redisClusterHashTag(invalidationPrefix(urnPrefix, keyType, id))}#watermark`;
+  }
+  redisWatermarkKeyFromKey(key) {
+    return this.redisWatermarkKey(key.urnPrefix, key.keyType, key.id);
+  }
+  async resolveClient() {
+    if (this.clientPromise === null) {
+      if (this.createClient === null) {
+        throw new Error("Redis client has not been configured");
+      }
+      this.clientPromise = Promise.resolve(this.createClient());
+    }
+    try {
+      return await this.clientPromise;
+    } catch (error) {
+      if (this.createClient !== null) {
+        this.clientPromise = null;
+      }
+      throw error;
+    }
+  }
+  serializerFor(key) {
+    return key.serializer ?? this.defaultSerializer;
+  }
+  async resolveRemoteLayerConfig(key, keyConfig) {
+    const config = keyConfig === void 0 ? await fetchKeyConfig(this.configProvider, key) : keyConfig;
+    return await resolveLayerConfigResult({
+      config,
+      key,
+      layer: "remote" /* REMOTE */,
+      rampSampler: this.rampSampler
+    });
+  }
+  async resolveRemoteTtlSec(key) {
+    const layerConfig = await this.resolveRemoteLayerConfig(key);
+    return layerConfig.status === "enabled" ? layerConfig.config.ttlSec : null;
+  }
+  recordMetric(record) {
+    if (this.metrics === null) {
+      return;
+    }
+    try {
+      record(this.metrics);
+    } catch {
+    }
+  }
+};
+function payloadSize(payload) {
+  return Buffer.isBuffer(payload) ? payload.byteLength : Buffer.byteLength(payload);
+}
+function elapsedSeconds(startMs) {
+  return Math.max((performance2.now() - startMs) / 1e3, 0);
+}
+
+// src/dialcache.ts
+var DEFAULT_LOCAL_MAX_SIZE = 1e4;
+var defaultConfigProvider = () => null;
+var defaultLogger = console;
+var DialCache = class {
+  context = new DialCacheContext();
+  localCache;
+  useCases = /* @__PURE__ */ new Set();
+  configProvider;
+  urnPrefix;
+  logger;
+  rampSampler;
+  redisCache;
+  metrics;
+  inFlight = /* @__PURE__ */ new Map();
+  constructor(config = {}) {
+    const localMaxSize = config.localMaxSize ?? DEFAULT_LOCAL_MAX_SIZE;
+    if (!Number.isSafeInteger(localMaxSize) || localMaxSize < 0) {
+      throw new RangeError("DialCache localMaxSize must be a nonnegative safe integer");
+    }
+    this.configProvider = config.cacheConfigProvider ?? defaultConfigProvider;
+    this.urnPrefix = config.urnPrefix ?? "urn";
+    this.logger = config.logger ?? defaultLogger;
+    this.rampSampler = config.rampSampler ?? deterministicRampSampler;
+    const metrics = config.metrics === false ? null : config.metrics ?? createPrometheusDialCacheMetrics({
+      prefix: config.metricsPrefix ?? "",
+      ...config.metricsRegistry === void 0 ? {} : { registry: config.metricsRegistry }
+    });
+    this.metrics = safeMetrics(metrics);
+    this.localCache = new LocalCache(this.configProvider, this.rampSampler, localMaxSize);
+    this.redisCache = config.redis === void 0 ? null : new RedisCache({
+      configProvider: this.configProvider,
+      rampSampler: this.rampSampler,
+      redis: config.redis,
+      metrics: this.metrics
+    });
+  }
+  enable(fn) {
+    return this.context.enable(fn);
+  }
+  disable(fn) {
+    return this.context.disable(fn);
+  }
+  withEnabled(fn) {
+    return this.enable(fn);
+  }
+  withDisabled(fn) {
+    return this.disable(fn);
+  }
+  isEnabled() {
+    return this.context.isEnabled();
+  }
+  cached(fn, options) {
+    this.registerUseCase(options.useCase);
+    const run = async (...args) => {
+      const fallback = async () => await fn(...args);
+      const noLayerLabels = { useCase: options.useCase, keyType: options.keyType, layer: NO_CACHE_LAYER };
+      if (!this.isEnabled()) {
+        this.metrics?.disabled({ ...noLayerLabels, reason: "context" });
+        return await fallback();
+      }
+      let key;
+      try {
+        key = this.buildKey(options, options.cacheKey(...args));
+      } catch (error) {
+        this.logger.error("Could not construct DialCache key", error);
+        this.metrics?.error({
+          ...noLayerLabels,
+          error: errorName(error),
+          inFallback: false
+        });
+        return await this.callFallback(noLayerLabels, fallback);
+      }
+      let keyConfig;
+      try {
+        keyConfig = await fetchKeyConfig(this.configProvider, key);
+      } catch (error) {
+        this.logger.warn("Could not resolve DialCache key config", error);
+        this.metrics?.disabled({ ...noLayerLabels, reason: "config_error" });
+        return await this.callFallback(noLayerLabels, fallback);
+      }
+      const redisCache = this.redisCache;
+      return redisCache === null ? await this.getThroughLocalOnly(key, keyConfig, fallback) : await this.getThroughRedisChain(redisCache, key, keyConfig, fallback);
+    };
+    return run;
+  }
+  /**
+   * Writes a remote invalidation watermark for Redis-tracked entries.
+   *
+   * This does not synchronously evict local cache hits or untracked Redis values.
+   *
+   * @param futureBufferMs Nonnegative safe integer covering source lag and stale fallback work through the Redis write.
+   */
+  async invalidateRemote(keyType, id, futureBufferMs = 0) {
+    assertValidFutureBufferMs(futureBufferMs);
+    if (this.redisCache === null) {
+      return;
+    }
+    this.metrics?.invalidation({ keyType, layer: "remote" /* REMOTE */ });
+    try {
+      await this.redisCache.invalidate(keyType, String(id), futureBufferMs, this.urnPrefix);
+    } catch (error) {
+      this.logger.warn("Error writing DialCache invalidation watermark", error);
+      this.metrics?.error({
+        useCase: "watermark",
+        keyType,
+        layer: "remote" /* REMOTE */,
+        error: errorName(error),
+        inFallback: false
+      });
+      throw error;
+    }
+  }
+  async flushAll() {
+    await this.localCache.flushAll();
+    if (this.redisCache === null) {
+      return;
+    }
+    try {
+      await this.redisCache.flushAll();
+    } catch (error) {
+      this.logger.warn("Error flushing Redis cache", error);
+      this.metrics?.error({
+        useCase: "flushAll",
+        keyType: "all",
+        layer: "remote" /* REMOTE */,
+        error: errorName(error),
+        inFallback: false
+      });
+      throw error;
+    }
+  }
+  async getThroughLocalOnly(key, keyConfig, fallback) {
+    const local = await this.readLocal(key, keyConfig);
+    if (local.status === "hit") {
+      return local.value;
+    }
+    const runFallback = async () => {
+      const value = await this.callFallback(labelsFor(key, "local" /* LOCAL */), fallback);
+      if (local.status === "miss") {
+        await this.putLocalFailOpen(key, value, local.config);
+      }
+      return value;
+    };
+    return local.status === "miss" ? await this.singleFlight(key, runFallback) : await runFallback();
+  }
+  async getThroughRedisChain(redisCache, key, keyConfig, fallback) {
+    const local = await this.readLocal(key, keyConfig);
+    if (local.status === "hit") {
+      return local.value;
+    }
+    if (local.status === "miss") {
+      return await this.singleFlight(key, async () => await this.getThroughRemoteAfterLocal(redisCache, key, local, keyConfig, fallback));
+    }
+    const remoteLayer = await this.resolveRemoteLayerConfig(key, keyConfig);
+    if (remoteLayer.status === "disabled") {
+      return await this.finishRedisChain(redisCache, key, local, remoteLayer, fallback);
+    }
+    return await this.singleFlight(key, async () => {
+      const remote = await this.readRemoteWithResolvedConfig(redisCache, key, remoteLayer.config);
+      return await this.finishRedisChain(redisCache, key, local, remote, fallback);
+    });
+  }
+  async getThroughRemoteAfterLocal(redisCache, key, local, keyConfig, fallback) {
+    const remote = await this.readRemote(redisCache, key, keyConfig);
+    return await this.finishRedisChain(redisCache, key, local, remote, fallback);
+  }
+  async finishRedisChain(redisCache, key, local, remote, fallback) {
+    if (remote.status === "hit") {
+      if (local.status === "miss") {
+        await this.putLocalFailOpen(key, remote.value, local.config);
+      }
+      return remote.value;
+    }
+    const remoteErrored = remote.status === "disabled" && remote.reason === "config_error";
+    const runFallback = async () => {
+      const fallbackLayer = remote.status === "miss" || remoteErrored ? "remote" /* REMOTE */ : "local" /* LOCAL */;
+      const value = await this.callFallback(labelsFor(key, fallbackLayer), fallback);
+      const skipCacheWrite = (remote.status === "miss" || remote.status === "disabled") && remote.skipCacheWrite === true;
+      let suppressCacheWrite = skipCacheWrite;
+      if (!suppressCacheWrite && (remote.status === "miss" || remoteErrored)) {
+        try {
+          const wroteRemote = await redisCache.put(key, value, remote.status === "miss" ? remote.config : void 0);
+          suppressCacheWrite = wroteRemote === false;
+        } catch (error) {
+          this.logger.warn("Error putting value in Redis cache", error);
+          this.recordError(key, "remote" /* REMOTE */, error, false);
+          suppressCacheWrite = key.trackForInvalidation;
+        }
+      }
+      if (!suppressCacheWrite && local.status === "miss") {
+        await this.putLocalFailOpen(key, value, local.config);
+      }
+      return value;
+    };
+    return await runFallback();
+  }
+  async readLocal(key, keyConfig) {
+    const start = performance3.now();
+    try {
+      const result = await this.localCache.getIfPresentResult(key, keyConfig);
+      if (result.status === "disabled") {
+        this.metrics?.disabled({ ...labelsFor(key, "local" /* LOCAL */), reason: result.reason });
+        return result;
+      }
+      this.metrics?.request(labelsFor(key, "local" /* LOCAL */));
+      this.metrics?.observeGet(labelsFor(key, "local" /* LOCAL */), elapsedSeconds2(start));
+      if (result.status === "miss") {
+        this.metrics?.miss(labelsFor(key, "local" /* LOCAL */));
+      }
+      return result;
+    } catch (error) {
+      this.logger.error("Error getting value from local cache", error);
+      this.recordError(key, "local" /* LOCAL */, error, false);
+      this.metrics?.disabled({ ...labelsFor(key, "local" /* LOCAL */), reason: "config_error" });
+      return { status: "disabled", reason: "config_error" };
+    }
+  }
+  async resolveRemoteLayerConfig(key, keyConfig) {
+    try {
+      const result = await resolveLayerConfigResult({
+        config: keyConfig,
+        key,
+        layer: "remote" /* REMOTE */,
+        rampSampler: this.rampSampler
+      });
+      if (result.status === "disabled") {
+        this.metrics?.disabled({ ...labelsFor(key, "remote" /* REMOTE */), reason: result.reason });
+      }
+      return result;
+    } catch (error) {
+      this.logger.warn("Error resolving Redis cache config", error);
+      this.recordError(key, "remote" /* REMOTE */, error, false);
+      return { status: "disabled", reason: "config_error", ...key.trackForInvalidation ? { skipCacheWrite: true } : {} };
+    }
+  }
+  async readRemote(redisCache, key, keyConfig) {
+    const layerConfig = await this.resolveRemoteLayerConfig(key, keyConfig);
+    if (layerConfig.status === "disabled") {
+      return layerConfig;
+    }
+    return await this.readRemoteWithResolvedConfig(redisCache, key, layerConfig.config);
+  }
+  async readRemoteWithResolvedConfig(redisCache, key, layerConfig) {
+    const start = performance3.now();
+    try {
+      const result = await redisCache.getWithResolvedConfig(key, layerConfig);
+      this.metrics?.request(labelsFor(key, "remote" /* REMOTE */));
+      this.metrics?.observeGet(labelsFor(key, "remote" /* REMOTE */), elapsedSeconds2(start));
+      if (result.status === "miss") {
+        this.metrics?.miss(labelsFor(key, "remote" /* REMOTE */));
+      }
+      return result;
+    } catch (error) {
+      this.logger.warn("Error getting value from Redis cache", error);
+      this.recordError(key, "remote" /* REMOTE */, error, false);
+      return { status: "disabled", reason: "config_error", ...key.trackForInvalidation ? { skipCacheWrite: true } : {} };
+    }
+  }
+  async putLocalFailOpen(key, value, config) {
+    try {
+      await this.localCache.put(key, value, config);
+    } catch (error) {
+      this.logger.warn("Error putting value in local cache", error);
+      this.recordError(key, "local" /* LOCAL */, error, false);
+    }
+  }
+  async callFallback(labels, fallback) {
+    const start = performance3.now();
+    try {
+      return await fallback();
+    } catch (error) {
+      this.metrics?.error({ ...labels, error: errorName(error), inFallback: true });
+      throw error;
+    } finally {
+      this.metrics?.observeFallback(labels, elapsedSeconds2(start));
+    }
+  }
+  recordError(key, layer, error, inFallback) {
+    this.metrics?.error({ ...labelsFor(key, layer), error: errorName(error), inFallback });
+  }
+  registerUseCase(useCase) {
+    if (useCase === "watermark") {
+      throw new UseCaseNameIsReservedError(useCase);
+    }
+    if (this.useCases.has(useCase)) {
+      throw new UseCaseIsAlreadyRegisteredError(useCase);
+    }
+    this.useCases.add(useCase);
+  }
+  buildKey(options, cacheKey) {
+    const spec = typeof cacheKey === "object" ? cacheKey : { id: cacheKey };
+    return new DialCacheKey({
+      keyType: options.keyType,
+      id: String(spec.id),
+      useCase: options.useCase,
+      args: normalizeArgs(spec.args ?? {}),
+      urnPrefix: this.urnPrefix,
+      defaultConfig: options.defaultConfig ?? null,
+      serializer: options.serializer ?? null,
+      trackForInvalidation: options.trackForInvalidation ?? false
+    });
+  }
+  singleFlight(key, run) {
+    const existing = this.inFlight.get(key.urn);
+    if (existing !== void 0) {
+      this.metrics?.coalesced?.({ useCase: key.useCase, keyType: key.keyType });
+      return existing;
+    }
+    const promise = run();
+    this.inFlight.set(key.urn, promise);
+    const clear = () => {
+      this.inFlight.delete(key.urn);
+    };
+    void promise.then(clear, clear);
+    return promise;
+  }
+};
+function elapsedSeconds2(startMs) {
+  return Math.max((performance3.now() - startMs) / 1e3, 0);
+}
+function assertValidFutureBufferMs(futureBufferMs) {
+  if (!Number.isSafeInteger(futureBufferMs) || futureBufferMs < 0) {
+    throw new RangeError("DialCache invalidation futureBufferMs must be a nonnegative safe integer");
+  }
+}
+function safeMetrics(metrics) {
+  if (metrics === null) {
+    return null;
+  }
+  return {
+    request: (labels) => callMetric(() => metrics.request(labels)),
+    miss: (labels) => callMetric(() => metrics.miss(labels)),
+    disabled: (labels) => callMetric(() => metrics.disabled(labels)),
+    error: (labels) => callMetric(() => metrics.error(labels)),
+    invalidation: (labels) => callMetric(() => metrics.invalidation(labels)),
+    coalesced: (labels) => callMetric(() => metrics.coalesced?.(labels)),
+    observeGet: (labels, seconds) => callMetric(() => metrics.observeGet(labels, seconds)),
+    observeFallback: (labels, seconds) => callMetric(() => metrics.observeFallback(labels, seconds)),
+    observeSerialization: (labels, seconds) => callMetric(() => metrics.observeSerialization(labels, seconds)),
+    observeSize: (labels, bytes) => callMetric(() => metrics.observeSize(labels, bytes))
+  };
+}
+function callMetric(record) {
+  try {
+    record();
+  } catch {
+  }
+}
+export {
+  CacheLayer,
+  DEFAULT_WATERMARK_TTL_SEC,
+  DialCache,
+  DialCacheContext,
+  DialCacheError,
+  DialCacheKey,
+  DialCacheKeyConfig,
+  DialCacheRedisPayloadEncodingError,
+  DialCacheRedisPayloadError,
+  JsonSerializer,
+  MissingKeyConfigError,
+  PrometheusDialCacheMetrics,
+  UseCaseIsAlreadyRegisteredError,
+  UseCaseNameIsReservedError,
+  createPrometheusDialCacheMetrics,
+  deterministicRampSampler,
+  invalidationPrefix,
+  normalizeArgs,
+  randomRampSampler,
+  redisClusterHashTag
+};