layercache 1.0.0 → 1.0.1

package/dist/index.js

@@ -1,6 +1,81 @@
 // src/CacheStack.ts
 import { randomUUID } from "crypto";
 
+// src/internal/StoredValue.ts
+function isStoredValueEnvelope(value) {
+  return typeof value === "object" && value !== null && "__layercache" in value && value.__layercache === 1 && "kind" in value;
+}
+function createStoredValueEnvelope(options) {
+  const now = options.now ?? Date.now();
+  const freshTtlSeconds = normalizePositiveSeconds(options.freshTtlSeconds);
+  const staleWhileRevalidateSeconds = normalizePositiveSeconds(options.staleWhileRevalidateSeconds);
+  const staleIfErrorSeconds = normalizePositiveSeconds(options.staleIfErrorSeconds);
+  const freshUntil = freshTtlSeconds ? now + freshTtlSeconds * 1e3 : null;
+  const staleUntil = freshUntil && staleWhileRevalidateSeconds ? freshUntil + staleWhileRevalidateSeconds * 1e3 : null;
+  const errorUntil = freshUntil && staleIfErrorSeconds ? freshUntil + staleIfErrorSeconds * 1e3 : null;
+  return {
+    __layercache: 1,
+    kind: options.kind,
+    value: options.value,
+    freshUntil,
+    staleUntil,
+    errorUntil
+  };
+}
+function resolveStoredValue(stored, now = Date.now()) {
+  if (!isStoredValueEnvelope(stored)) {
+    return { state: "fresh", value: stored, stored };
+  }
+  if (stored.freshUntil === null || stored.freshUntil > now) {
+    return { state: "fresh", value: unwrapStoredValue(stored), stored, envelope: stored };
+  }
+  if (stored.staleUntil !== null && stored.staleUntil > now) {
+    return { state: "stale-while-revalidate", value: unwrapStoredValue(stored), stored, envelope: stored };
+  }
+  if (stored.errorUntil !== null && stored.errorUntil > now) {
+    return { state: "stale-if-error", value: unwrapStoredValue(stored), stored, envelope: stored };
+  }
+  return { state: "expired", value: null, stored, envelope: stored };
+}
+function unwrapStoredValue(stored) {
+  if (!isStoredValueEnvelope(stored)) {
+    return stored;
+  }
+  if (stored.kind === "empty") {
+    return null;
+  }
+  return stored.value ?? null;
+}
+function remainingStoredTtlSeconds(stored, now = Date.now()) {
+  if (!isStoredValueEnvelope(stored)) {
+    return void 0;
+  }
+  const expiry = maxExpiry(stored);
+  if (expiry === null) {
+    return void 0;
+  }
+  const remainingMs = expiry - now;
+  if (remainingMs <= 0) {
+    return 1;
+  }
+  return Math.max(1, Math.ceil(remainingMs / 1e3));
+}
+function maxExpiry(stored) {
+  const values = [stored.freshUntil, stored.staleUntil, stored.errorUntil].filter(
+    (value) => value !== null
+  );
+  if (values.length === 0) {
+    return null;
+  }
+  return Math.max(...values);
+}
+function normalizePositiveSeconds(value) {
+  if (!value || value <= 0) {
+    return void 0;
+  }
+  return value;
+}
+
 // src/invalidation/PatternMatcher.ts
 var PatternMatcher = class {
   static matches(pattern, value) {
@@ -93,6 +168,10 @@ var StampedeGuard = class {
 };
 
 // src/CacheStack.ts
+var DEFAULT_NEGATIVE_TTL_SECONDS = 60;
+var DEFAULT_SINGLE_FLIGHT_LEASE_MS = 3e4;
+var DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS = 5e3;
+var DEFAULT_SINGLE_FLIGHT_POLL_MS = 50;
 var EMPTY_METRICS = () => ({
   hits: 0,
   misses: 0,
@@ -100,7 +179,12 @@ var EMPTY_METRICS = () => ({
   sets: 0,
   deletes: 0,
   backfills: 0,
-  invalidations: 0
+  invalidations: 0,
+  staleHits: 0,
+  refreshes: 0,
+  refreshErrors: 0,
+  writeFailures: 0,
+  singleFlightWaits: 0
 });
 var DebugLogger = class {
   enabled;
@@ -112,7 +196,7 @@ var DebugLogger = class {
       return;
     }
     const suffix = context ? ` ${JSON.stringify(context)}` : "";
-    console.debug(`[cachestack] ${message}${suffix}`);
+    console.debug(`[layercache] ${message}${suffix}`);
   }
 };
 var CacheStack = class {
@@ -122,7 +206,7 @@ var CacheStack = class {
     if (layers.length === 0) {
       throw new Error("CacheStack requires at least one cache layer.");
     }
-    const debugEnv = process.env.DEBUG?.split(",").includes("cachestack:debug") ?? false;
+    const debugEnv = process.env.DEBUG?.split(",").includes("layercache:debug") ?? false;
     this.logger = typeof options.logger === "object" ? options.logger : new DebugLogger(Boolean(options.logger) || debugEnv);
     this.tagIndex = options.tagIndex ?? new TagIndex();
     this.startup = this.initialize();
@@ -136,49 +220,46 @@ var CacheStack = class {
   unsubscribeInvalidation;
   logger;
   tagIndex;
+  backgroundRefreshes = /* @__PURE__ */ new Map();
   async get(key, fetcher, options) {
     await this.startup;
-    const hit = await this.getFromLayers(key, options);
+    const hit = await this.readFromLayers(key, options, "allow-stale");
     if (hit.found) {
-      this.metrics.hits += 1;
-      return hit.value;
+      if (hit.state === "fresh") {
+        this.metrics.hits += 1;
+        return hit.value;
+      }
+      if (hit.state === "stale-while-revalidate") {
+        this.metrics.hits += 1;
+        this.metrics.staleHits += 1;
+        if (fetcher) {
+          this.scheduleBackgroundRefresh(key, fetcher, options);
+        }
+        return hit.value;
+      }
+      if (!fetcher) {
+        this.metrics.hits += 1;
+        this.metrics.staleHits += 1;
+        return hit.value;
+      }
+      try {
+        return await this.fetchWithGuards(key, fetcher, options);
+      } catch (error) {
+        this.metrics.staleHits += 1;
+        this.metrics.refreshErrors += 1;
+        this.logger.debug("stale-if-error", { key, error: this.formatError(error) });
+        return hit.value;
+      }
     }
     this.metrics.misses += 1;
     if (!fetcher) {
       return null;
     }
-    const runFetch = async () => {
-      const secondHit = await this.getFromLayers(key, options);
-      if (secondHit.found) {
-        this.metrics.hits += 1;
-        return secondHit.value;
-      }
-      this.metrics.fetches += 1;
-      const fetched = await fetcher();
-      if (fetched === null || fetched === void 0) {
-        return null;
-      }
-      await this.set(key, fetched, options);
-      return fetched;
-    };
-    if (this.options.stampedePrevention === false) {
-      return runFetch();
-    }
-    return this.stampedeGuard.execute(key, runFetch);
+    return this.fetchWithGuards(key, fetcher, options);
   }
   async set(key, value, options) {
     await this.startup;
-    await this.setAcrossLayers(key, value, options);
-    if (options?.tags) {
-      await this.tagIndex.track(key, options.tags);
-    } else {
-      await this.tagIndex.touch(key);
-    }
-    this.metrics.sets += 1;
-    this.logger.debug("set", { key, tags: options?.tags });
-    if (this.options.publishSetInvalidation !== false) {
-      await this.publishInvalidation({ scope: "key", keys: [key], sourceId: this.instanceId, operation: "write" });
-    }
+    await this.storeEntry(key, "value", value, options);
   }
   async delete(key) {
     await this.startup;
@@ -194,7 +275,48 @@ var CacheStack = class {
     await this.publishInvalidation({ scope: "clear", sourceId: this.instanceId, operation: "clear" });
   }
   async mget(entries) {
-    return Promise.all(entries.map((entry) => this.get(entry.key, entry.fetch, entry.options)));
+    if (entries.length === 0) {
+      return [];
+    }
+    const canFastPath = entries.every((entry) => entry.fetch === void 0 && entry.options === void 0);
+    if (!canFastPath) {
+      return Promise.all(entries.map((entry) => this.get(entry.key, entry.fetch, entry.options)));
+    }
+    await this.startup;
+    const pending = new Set(entries.map((_, index) => index));
+    const results = Array(entries.length).fill(null);
+    for (const layer of this.layers) {
+      const indexes = [...pending];
+      if (indexes.length === 0) {
+        break;
+      }
+      const keys = indexes.map((index) => entries[index].key);
+      const values = layer.getMany ? await layer.getMany(keys) : await Promise.all(keys.map((key) => this.readLayerEntry(layer, key)));
+      for (let offset = 0; offset < values.length; offset += 1) {
+        const index = indexes[offset];
+        const stored = values[offset];
+        if (stored === null) {
+          continue;
+        }
+        const resolved = resolveStoredValue(stored);
+        if (resolved.state === "expired") {
+          await layer.delete(entries[index].key);
+          continue;
+        }
+        await this.tagIndex.touch(entries[index].key);
+        await this.backfill(entries[index].key, stored, this.layers.indexOf(layer) - 1, entries[index].options);
+        results[index] = resolved.value;
+        pending.delete(index);
+        this.metrics.hits += 1;
+      }
+    }
+    if (pending.size > 0) {
+      for (const index of pending) {
+        await this.tagIndex.remove(entries[index].key);
+        this.metrics.misses += 1;
+      }
+    }
+    return results;
   }
   async mset(entries) {
     await Promise.all(entries.map((entry) => this.set(entry.key, entry.value, entry.options)));
@@ -220,6 +342,7 @@ var CacheStack = class {
   async disconnect() {
     await this.startup;
     await this.unsubscribeInvalidation?.();
+    await Promise.allSettled(this.backgroundRefreshes.values());
   }
   async initialize() {
     if (!this.options.invalidationBus) {
@@ -229,46 +352,225 @@ var CacheStack = class {
       await this.handleInvalidationMessage(message);
     });
   }
-  async getFromLayers(key, options) {
+  async fetchWithGuards(key, fetcher, options) {
+    const fetchTask = async () => {
+      const secondHit = await this.readFromLayers(key, options, "fresh-only");
+      if (secondHit.found) {
+        this.metrics.hits += 1;
+        return secondHit.value;
+      }
+      return this.fetchAndPopulate(key, fetcher, options);
+    };
+    const singleFlightTask = async () => {
+      if (!this.options.singleFlightCoordinator) {
+        return fetchTask();
+      }
+      return this.options.singleFlightCoordinator.execute(
+        key,
+        this.resolveSingleFlightOptions(),
+        fetchTask,
+        () => this.waitForFreshValue(key, fetcher, options)
+      );
+    };
+    if (this.options.stampedePrevention === false) {
+      return singleFlightTask();
+    }
+    return this.stampedeGuard.execute(key, singleFlightTask);
+  }
+  async waitForFreshValue(key, fetcher, options) {
+    const timeoutMs = this.options.singleFlightTimeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS;
+    const pollIntervalMs = this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS;
+    const deadline = Date.now() + timeoutMs;
+    this.metrics.singleFlightWaits += 1;
+    while (Date.now() < deadline) {
+      const hit = await this.readFromLayers(key, options, "fresh-only");
+      if (hit.found) {
+        this.metrics.hits += 1;
+        return hit.value;
+      }
+      await this.sleep(pollIntervalMs);
+    }
+    return this.fetchAndPopulate(key, fetcher, options);
+  }
+  async fetchAndPopulate(key, fetcher, options) {
+    this.metrics.fetches += 1;
+    const fetched = await fetcher();
+    if (fetched === null || fetched === void 0) {
+      if (!this.shouldNegativeCache(options)) {
+        return null;
+      }
+      await this.storeEntry(key, "empty", null, options);
+      return null;
+    }
+    await this.storeEntry(key, "value", fetched, options);
+    return fetched;
+  }
+  async storeEntry(key, kind, value, options) {
+    await this.writeAcrossLayers(key, kind, value, options);
+    if (options?.tags) {
+      await this.tagIndex.track(key, options.tags);
+    } else {
+      await this.tagIndex.touch(key);
+    }
+    this.metrics.sets += 1;
+    this.logger.debug("set", { key, kind, tags: options?.tags });
+    if (this.options.publishSetInvalidation !== false) {
+      await this.publishInvalidation({ scope: "key", keys: [key], sourceId: this.instanceId, operation: "write" });
+    }
+  }
+  async readFromLayers(key, options, mode) {
+    let sawRetainableValue = false;
     for (let index = 0; index < this.layers.length; index += 1) {
       const layer = this.layers[index];
-      const value = await layer.get(key);
-      if (value === null) {
+      const stored = await this.readLayerEntry(layer, key);
+      if (stored === null) {
+        continue;
+      }
+      const resolved = resolveStoredValue(stored);
+      if (resolved.state === "expired") {
+        await layer.delete(key);
+        continue;
+      }
+      sawRetainableValue = true;
+      if (mode === "fresh-only" && resolved.state !== "fresh") {
         continue;
       }
       await this.tagIndex.touch(key);
-      await this.backfill(key, value, index - 1, options);
-      this.logger.debug("hit", { key, layer: layer.name });
-      return { found: true, value };
+      await this.backfill(key, stored, index - 1, options);
+      this.logger.debug("hit", { key, layer: layer.name, state: resolved.state });
+      return { found: true, value: resolved.value, stored, state: resolved.state };
     }
-    await this.tagIndex.remove(key);
-    this.logger.debug("miss", { key });
-    return { found: false, value: null };
+    if (!sawRetainableValue) {
+      await this.tagIndex.remove(key);
+    }
+    this.logger.debug("miss", { key, mode });
+    return { found: false, value: null, stored: null, state: "miss" };
+  }
+  async readLayerEntry(layer, key) {
+    if (layer.getEntry) {
+      return layer.getEntry(key);
+    }
+    return layer.get(key);
   }
-  async backfill(key, value, upToIndex, options) {
+  async backfill(key, stored, upToIndex, options) {
     if (upToIndex < 0) {
       return;
     }
     for (let index = 0; index <= upToIndex; index += 1) {
       const layer = this.layers[index];
-      await layer.set(key, value, this.resolveTtl(layer.name, layer.defaultTtl, options?.ttl));
+      const ttl = remainingStoredTtlSeconds(stored) ?? this.resolveLayerSeconds(layer.name, options?.ttl, void 0, layer.defaultTtl);
+      await layer.set(key, stored, ttl);
       this.metrics.backfills += 1;
       this.logger.debug("backfill", { key, layer: layer.name });
     }
   }
-  async setAcrossLayers(key, value, options) {
-    await Promise.all(
-      this.layers.map((layer) => layer.set(key, value, this.resolveTtl(layer.name, layer.defaultTtl, options?.ttl)))
-    );
+  async writeAcrossLayers(key, kind, value, options) {
+    const now = Date.now();
+    const operations = this.layers.map((layer) => async () => {
+      const freshTtl = this.resolveFreshTtl(layer.name, kind, options, layer.defaultTtl);
+      const staleWhileRevalidate = this.resolveLayerSeconds(
+        layer.name,
+        options?.staleWhileRevalidate,
+        this.options.staleWhileRevalidate
+      );
+      const staleIfError = this.resolveLayerSeconds(
+        layer.name,
+        options?.staleIfError,
+        this.options.staleIfError
+      );
+      const payload = createStoredValueEnvelope({
+        kind,
+        value,
+        freshTtlSeconds: freshTtl,
+        staleWhileRevalidateSeconds: staleWhileRevalidate,
+        staleIfErrorSeconds: staleIfError,
+        now
+      });
+      const ttl = remainingStoredTtlSeconds(payload, now) ?? freshTtl;
+      await layer.set(key, payload, ttl);
+    });
+    await this.executeLayerOperations(operations, { key, action: kind === "empty" ? "negative-set" : "set" });
+  }
+  async executeLayerOperations(operations, context) {
+    if (this.options.writePolicy !== "best-effort") {
+      await Promise.all(operations.map((operation) => operation()));
+      return;
+    }
+    const results = await Promise.allSettled(operations.map((operation) => operation()));
+    const failures = results.filter((result) => result.status === "rejected");
+    if (failures.length === 0) {
+      return;
+    }
+    this.metrics.writeFailures += failures.length;
+    this.logger.debug("write-failure", {
+      ...context,
+      failures: failures.map((failure) => this.formatError(failure.reason))
+    });
+    if (failures.length === operations.length) {
+      throw new AggregateError(
+        failures.map((failure) => failure.reason),
+        `${context.action} failed for every cache layer`
+      );
+    }
+  }
+  resolveFreshTtl(layerName, kind, options, fallbackTtl) {
+    const baseTtl = kind === "empty" ? this.resolveLayerSeconds(
+      layerName,
+      options?.negativeTtl,
+      this.options.negativeTtl,
+      this.resolveLayerSeconds(layerName, options?.ttl, void 0, fallbackTtl) ?? DEFAULT_NEGATIVE_TTL_SECONDS
+    ) : this.resolveLayerSeconds(layerName, options?.ttl, void 0, fallbackTtl);
+    const jitter = this.resolveLayerSeconds(layerName, options?.ttlJitter, this.options.ttlJitter);
+    return this.applyJitter(baseTtl, jitter);
+  }
+  resolveLayerSeconds(layerName, override, globalDefault, fallback) {
+    if (override !== void 0) {
+      return this.readLayerNumber(layerName, override) ?? fallback;
+    }
+    if (globalDefault !== void 0) {
+      return this.readLayerNumber(layerName, globalDefault) ?? fallback;
+    }
+    return fallback;
   }
-  resolveTtl(layerName, fallbackTtl, ttlOverride) {
-    if (ttlOverride === void 0) {
-      return fallbackTtl;
+  readLayerNumber(layerName, value) {
+    if (typeof value === "number") {
+      return value;
     }
-    if (typeof ttlOverride === "number") {
-      return ttlOverride;
+    return value[layerName];
+  }
+  applyJitter(ttl, jitter) {
+    if (!ttl || ttl <= 0 || !jitter || jitter <= 0) {
+      return ttl;
     }
-    return ttlOverride[layerName] ?? fallbackTtl;
+    const delta = (Math.random() * 2 - 1) * jitter;
+    return Math.max(1, Math.round(ttl + delta));
+  }
+  shouldNegativeCache(options) {
+    return options?.negativeCache ?? this.options.negativeCaching ?? false;
+  }
+  scheduleBackgroundRefresh(key, fetcher, options) {
+    if (this.backgroundRefreshes.has(key)) {
+      return;
+    }
+    const refresh = (async () => {
+      this.metrics.refreshes += 1;
+      try {
+        await this.fetchWithGuards(key, fetcher, options);
+      } catch (error) {
+        this.metrics.refreshErrors += 1;
+        this.logger.debug("refresh-error", { key, error: this.formatError(error) });
+      } finally {
+        this.backgroundRefreshes.delete(key);
+      }
+    })();
+    this.backgroundRefreshes.set(key, refresh);
+  }
+  resolveSingleFlightOptions() {
+    return {
+      leaseMs: this.options.singleFlightLeaseMs ?? DEFAULT_SINGLE_FLIGHT_LEASE_MS,
+      waitTimeoutMs: this.options.singleFlightTimeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS,
+      pollIntervalMs: this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS
+    };
   }
   async deleteKeys(keys) {
     if (keys.length === 0) {
@@ -325,6 +627,15 @@ var CacheStack = class {
       }
     }
   }
+  formatError(error) {
+    if (error instanceof Error) {
+      return error.message;
+    }
+    return String(error);
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
 };
 
 // src/invalidation/RedisInvalidationBus.ts
@@ -335,7 +646,7 @@ var RedisInvalidationBus = class {
   constructor(options) {
     this.publisher = options.publisher;
     this.subscriber = options.subscriber ?? options.publisher.duplicate();
-    this.channel = options.channel ?? "cachestack:invalidation";
+    this.channel = options.channel ?? "layercache:invalidation";
   }
   async subscribe(handler) {
     const listener = async (_channel, payload) => {
@@ -361,7 +672,7 @@ var RedisTagIndex = class {
   scanCount;
   constructor(options) {
     this.client = options.client;
-    this.prefix = options.prefix ?? "cachestack:tag-index";
+    this.prefix = options.prefix ?? "layercache:tag-index";
     this.scanCount = options.scanCount ?? 100;
   }
   async touch(key) {
@@ -457,6 +768,10 @@ var MemoryLayer = class {
     this.maxSize = options.maxSize ?? 1e3;
   }
   async get(key) {
+    const value = await this.getEntry(key);
+    return unwrapStoredValue(value);
+  }
+  async getEntry(key) {
     const entry = this.entries.get(key);
     if (!entry) {
       return null;
@@ -469,6 +784,13 @@ var MemoryLayer = class {
     this.entries.set(key, entry);
     return entry.value;
   }
+  async getMany(keys) {
+    const values = [];
+    for (const key of keys) {
+      values.push(await this.getEntry(key));
+    }
+    return values;
+  }
   async set(key, value, ttl = this.defaultTtl) {
     this.entries.delete(key);
     this.entries.set(key, {
@@ -541,12 +863,36 @@ var RedisLayer = class {
     this.scanCount = options.scanCount ?? 100;
   }
   async get(key) {
+    const payload = await this.getEntry(key);
+    return unwrapStoredValue(payload);
+  }
+  async getEntry(key) {
     const payload = await this.client.getBuffer(this.withPrefix(key));
     if (payload === null) {
       return null;
     }
     return this.serializer.deserialize(payload);
   }
+  async getMany(keys) {
+    if (keys.length === 0) {
+      return [];
+    }
+    const pipeline = this.client.pipeline();
+    for (const key of keys) {
+      pipeline.getBuffer(this.withPrefix(key));
+    }
+    const results = await pipeline.exec();
+    if (results === null) {
+      return keys.map(() => null);
+    }
+    return results.map((result) => {
+      const [, payload] = result;
+      if (payload === null) {
+        return null;
+      }
+      return this.serializer.deserialize(payload);
+    });
+  }
   async set(key, value, ttl = this.defaultTtl) {
     const payload = this.serializer.serialize(value);
     const normalizedKey = this.withPrefix(key);
@@ -608,6 +954,36 @@ var MsgpackSerializer = class {
     return decode(normalized);
   }
 };
+
+// src/singleflight/RedisSingleFlightCoordinator.ts
+import { randomUUID as randomUUID2 } from "crypto";
+var RELEASE_SCRIPT = `
+if redis.call("get", KEYS[1]) == ARGV[1] then
+  return redis.call("del", KEYS[1])
+end
+return 0
+`;
+var RedisSingleFlightCoordinator = class {
+  client;
+  prefix;
+  constructor(options) {
+    this.client = options.client;
+    this.prefix = options.prefix ?? "layercache:singleflight";
+  }
+  async execute(key, options, worker, waiter) {
+    const lockKey = `${this.prefix}:${encodeURIComponent(key)}`;
+    const token = randomUUID2();
+    const acquired = await this.client.set(lockKey, token, "PX", options.leaseMs, "NX");
+    if (acquired === "OK") {
+      try {
+        return await worker();
+      } finally {
+        await this.client.eval(RELEASE_SCRIPT, 1, lockKey, token);
+      }
+    }
+    return waiter();
+  }
+};
 export {
   CacheStack,
   JsonSerializer,
@@ -616,6 +992,7 @@ export {
   PatternMatcher,
   RedisInvalidationBus,
   RedisLayer,
+  RedisSingleFlightCoordinator,
   RedisTagIndex,
   StampedeGuard,
   TagIndex

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "layercache",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Unified multi-layer caching for Node.js with memory, Redis, stampede prevention, and invalidation helpers.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flyingsquirrel0419/layercache"
+  },
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",