layercache 1.2.2 → 1.2.3

package/dist/{edge-DLpdQN0W.d.cts → edge-B_rUqDy6.d.ts}

@@ -177,6 +177,7 @@ interface CacheStackOptions {
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
     generation?: number;
+    generationCleanup?: boolean | CacheGenerationCleanupOptions;
     broadcastL1Invalidation?: boolean;
     /**
      * @deprecated Use `broadcastL1Invalidation` instead.
@@ -195,11 +196,13 @@ interface CacheStackOptions {
     writeStrategy?: 'write-through' | 'write-behind';
     writeBehind?: CacheWriteBehindOptions;
     fetcherRateLimit?: CacheRateLimitOptions;
+    backgroundRefreshTimeoutMs?: number;
     singleFlightCoordinator?: CacheSingleFlightCoordinator;
     singleFlightLeaseMs?: number;
     singleFlightTimeoutMs?: number;
     singleFlightPollMs?: number;
     singleFlightRenewIntervalMs?: number;
+    snapshotBaseDir?: string | false;
     /**
      * Maximum number of entries in `accessProfiles` and `circuitBreakers` maps
      * before the oldest entries are pruned. Prevents unbounded memory growth.
@@ -212,6 +215,9 @@ interface CacheAdaptiveTtlOptions {
     step?: number | LayerTtlMap;
     maxTtl?: number | LayerTtlMap;
 }
+interface CacheGenerationCleanupOptions {
+    batchSize?: number;
+}
 type CacheTtlPolicy = 'until-midnight' | 'next-hour' | {
     alignTo: number;
 } | ((context: CacheTtlPolicyContext) => number | undefined);
@@ -415,7 +421,7 @@ interface TagIndexOptions {
     /**
      * Maximum number of keys tracked in `knownKeys`. When exceeded, the oldest
      * 10 % of keys are pruned to keep memory bounded.
-     * Defaults to unlimited.
+     * Defaults to 100,000.
      */
     maxKnownKeys?: number;
 }
@@ -424,6 +430,8 @@ declare class TagIndex implements CacheTagIndex {
     private readonly keyToTags;
     private readonly knownKeys;
     private readonly maxKnownKeys;
+    private nextNodeId;
+    private readonly root;
     constructor(options?: TagIndexOptions);
     touch(key: string): Promise<void>;
     track(key: string, tags: string[]): Promise<void>;
@@ -433,8 +441,14 @@ declare class TagIndex implements CacheTagIndex {
     tagsForKey(key: string): Promise<string[]>;
     matchPattern(pattern: string): Promise<string[]>;
     clear(): Promise<void>;
+    private createTrieNode;
+    private insertKnownKey;
+    private findNode;
+    private collectFromNode;
+    private collectPatternMatches;
     private pruneKnownKeysIfNeeded;
     private removeKey;
+    private removeKnownKey;
 }
 
 declare class CacheNamespace {
@@ -505,6 +519,7 @@ declare class CacheStack extends EventEmitter {
     private readonly logger;
     private readonly tagIndex;
     private readonly fetchRateLimiter;
+    private readonly snapshotSerializer;
     private readonly backgroundRefreshes;
     private readonly layerDegradedUntil;
     private readonly ttlResolver;
@@ -513,6 +528,7 @@ declare class CacheStack extends EventEmitter {
     private readonly writeBehindQueue;
     private writeBehindTimer?;
     private writeBehindFlushPromise?;
+    private generationCleanupPromise?;
     private isDisconnecting;
     private disconnectPromise?;
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
@@ -523,6 +539,7 @@ declare class CacheStack extends EventEmitter {
      * and no `fetcher` is provided.
      */
     get<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
+    private getPrepared;
     /**
      * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
      * Fetches and caches the value if not already present.
@@ -581,6 +598,11 @@ declare class CacheStack extends EventEmitter {
      */
     getHitRate(): CacheHitRateSnapshot;
     healthCheck(): Promise<CacheHealthCheckResult[]>;
+    /**
+     * Rotates the active generation prefix used for all future cache keys.
+     * Previous-generation keys remain in the underlying layers until they expire,
+     * unless `generationCleanup` is enabled to prune them in the background.
+     */
     bumpGeneration(nextGeneration?: number): number;
     /**
      * Returns detailed metadata about a single cache key: which layers contain it,
@@ -608,6 +630,7 @@ declare class CacheStack extends EventEmitter {
     private resolveLayerSeconds;
     private shouldNegativeCache;
     private scheduleBackgroundRefresh;
+    private runBackgroundRefresh;
     private resolveSingleFlightOptions;
     private deleteKeys;
     private publishInvalidation;
@@ -615,7 +638,14 @@ declare class CacheStack extends EventEmitter {
     private getTagsForKey;
     private formatError;
     private sleep;
+    private withTimeout;
     private shouldBroadcastL1Invalidation;
+    private collectKeysWithPrefix;
+    private collectKeysMatchingPattern;
+    private shouldCleanupGenerations;
+    private generationCleanupBatchSize;
+    private scheduleGenerationCleanup;
+    private cleanupGeneration;
     private initializeWriteBehind;
     private shouldWriteBehind;
     private enqueueWriteBehind;
@@ -643,12 +673,15 @@ declare class CacheStack extends EventEmitter {
     private applyFreshReadPolicies;
     private shouldSkipLayer;
     private handleLayerFailure;
+    private reportRecoverableLayerFailure;
     private isGracefulDegradationEnabled;
     private recordCircuitFailure;
     private isNegativeStoredValue;
     private emitError;
     private serializeKeyPart;
     private isCacheSnapshotEntries;
+    private sanitizeSnapshotValue;
+    private validateSnapshotFilePath;
     private normalizeForSerialization;
 }
 

package/dist/edge.cjs

@@ -29,7 +29,30 @@ module.exports = __toCommonJS(edge_exports);
 
 // src/internal/StoredValue.ts
 function isStoredValueEnvelope(value) {
-  return typeof value === "object" && value !== null && "__layercache" in value && value.__layercache === 1 && "kind" in value;
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const v = value;
+  if (v.__layercache !== 1) {
+    return false;
+  }
+  if (v.kind !== "value" && v.kind !== "empty") {
+    return false;
+  }
+  if (v.freshUntil !== null && typeof v.freshUntil !== "number") {
+    return false;
+  }
+  if (v.staleUntil !== null && typeof v.staleUntil !== "number") {
+    return false;
+  }
+  if (v.errorUntil !== null && typeof v.errorUntil !== "number") {
+    return false;
+  }
+  const maxTimestamp = Date.now() + 10 * 365 * 24 * 60 * 60 * 1e3;
+  if (typeof v.freshUntil === "number" && v.freshUntil > maxTimestamp) {
+    return false;
+  }
+  return true;
 }
 function unwrapStoredValue(stored) {
   if (!isStoredValueEnvelope(stored)) {
@@ -87,16 +110,10 @@ var MemoryLayer = class {
     return entry.value;
   }
   async getMany(keys) {
-    const values = [];
-    for (const key of keys) {
-      values.push(await this.getEntry(key));
-    }
-    return values;
+    return Promise.all(keys.map((key) => this.getEntry(key)));
   }
   async setMany(entries) {
-    for (const entry of entries) {
-      await this.set(entry.key, entry.value, entry.ttl);
-    }
+    await Promise.all(entries.map((entry) => this.set(entry.key, entry.value, entry.ttl)));
   }
   async set(key, value, ttl = this.defaultTtl) {
     this.entries.delete(key);
@@ -283,15 +300,17 @@ var TagIndex = class {
   keyToTags = /* @__PURE__ */ new Map();
   knownKeys = /* @__PURE__ */ new Set();
   maxKnownKeys;
+  nextNodeId = 1;
+  root = this.createTrieNode();
   constructor(options = {}) {
-    this.maxKnownKeys = options.maxKnownKeys;
+    this.maxKnownKeys = options.maxKnownKeys ?? 1e5;
   }
   async touch(key) {
-    this.knownKeys.add(key);
+    this.insertKnownKey(key);
     this.pruneKnownKeysIfNeeded();
   }
   async track(key, tags) {
-    this.knownKeys.add(key);
+    this.insertKnownKey(key);
     this.pruneKnownKeysIfNeeded();
     if (tags.length === 0) {
       return;
@@ -317,18 +336,104 @@ var TagIndex = class {
     return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
   }
   async keysForPrefix(prefix) {
-    return [...this.knownKeys].filter((key) => key.startsWith(prefix));
+    const node = this.findNode(prefix);
+    if (!node) {
+      return [];
+    }
+    const matches = [];
+    this.collectFromNode(node, prefix, matches);
+    return matches;
   }
   async tagsForKey(key) {
     return [...this.keyToTags.get(key) ?? /* @__PURE__ */ new Set()];
   }
   async matchPattern(pattern) {
-    return [...this.knownKeys].filter((key) => PatternMatcher.matches(pattern, key));
+    const matches = /* @__PURE__ */ new Set();
+    this.collectPatternMatches(this.root, "", pattern, 0, matches, /* @__PURE__ */ new Set());
+    return [...matches];
   }
   async clear() {
     this.tagToKeys.clear();
     this.keyToTags.clear();
     this.knownKeys.clear();
+    this.root.children.clear();
+    this.root.terminal = false;
+    this.nextNodeId = this.root.id + 1;
+  }
+  createTrieNode() {
+    return {
+      id: this.nextNodeId++,
+      terminal: false,
+      children: /* @__PURE__ */ new Map()
+    };
+  }
+  insertKnownKey(key) {
+    if (this.knownKeys.has(key)) {
+      return;
+    }
+    this.knownKeys.add(key);
+    let node = this.root;
+    for (const character of key) {
+      let child = node.children.get(character);
+      if (!child) {
+        child = this.createTrieNode();
+        node.children.set(character, child);
+      }
+      node = child;
+    }
+    node.terminal = true;
+  }
+  findNode(prefix) {
+    let node = this.root;
+    for (const character of prefix) {
+      node = node.children.get(character);
+      if (!node) {
+        return void 0;
+      }
+    }
+    return node;
+  }
+  collectFromNode(node, prefix, matches) {
+    if (node.terminal) {
+      matches.push(prefix);
+    }
+    for (const [character, child] of node.children) {
+      this.collectFromNode(child, `${prefix}${character}`, matches);
+    }
+  }
+  collectPatternMatches(node, prefix, pattern, patternIndex, matches, visited) {
+    const stateKey = `${node.id}:${patternIndex}`;
+    if (visited.has(stateKey)) {
+      return;
+    }
+    visited.add(stateKey);
+    if (patternIndex === pattern.length) {
+      if (node.terminal) {
+        matches.add(prefix);
+      }
+      return;
+    }
+    const patternChar = pattern[patternIndex];
+    if (patternChar === void 0) {
+      return;
+    }
+    if (patternChar === "*") {
+      this.collectPatternMatches(node, prefix, pattern, patternIndex + 1, matches, visited);
+      for (const [character, child2] of node.children) {
+        this.collectPatternMatches(child2, `${prefix}${character}`, pattern, patternIndex, matches, visited);
+      }
+      return;
+    }
+    if (patternChar === "?") {
+      for (const [character, child2] of node.children) {
+        this.collectPatternMatches(child2, `${prefix}${character}`, pattern, patternIndex + 1, matches, visited);
+      }
+      return;
+    }
+    const child = node.children.get(patternChar);
+    if (child) {
+      this.collectPatternMatches(child, `${prefix}${patternChar}`, pattern, patternIndex + 1, matches, visited);
+    }
   }
   pruneKnownKeysIfNeeded() {
     if (this.maxKnownKeys === void 0 || this.knownKeys.size <= this.maxKnownKeys) {
@@ -345,7 +450,7 @@ var TagIndex = class {
     }
   }
   removeKey(key) {
-    this.knownKeys.delete(key);
+    this.removeKnownKey(key);
     const tags = this.keyToTags.get(key);
     if (!tags) {
       return;
@@ -362,6 +467,34 @@ var TagIndex = class {
     }
     this.keyToTags.delete(key);
   }
+  removeKnownKey(key) {
+    if (!this.knownKeys.delete(key)) {
+      return;
+    }
+    const path = [];
+    let node = this.root;
+    for (const character of key) {
+      const child = node.children.get(character);
+      if (!child) {
+        return;
+      }
+      path.push([node, character]);
+      node = child;
+    }
+    node.terminal = false;
+    for (let index = path.length - 1; index >= 0; index -= 1) {
+      const entry = path[index];
+      if (!entry) {
+        continue;
+      }
+      const [parent, character] = entry;
+      const child = parent.children.get(character);
+      if (!child || child.terminal || child.children.size > 0) {
+        break;
+      }
+      parent.children.delete(character);
+    }
+  }
 };
 
 // src/integrations/hono.ts
@@ -373,7 +506,8 @@ function createHonoCacheMiddleware(cache, options = {}) {
       await next();
       return;
     }
-    const key = options.keyResolver ? options.keyResolver(context.req) : `${method}:${context.req.path ?? context.req.url ?? "/"}`;
+    const rawPath = context.req.path ?? context.req.url ?? "/";
+    const key = options.keyResolver ? options.keyResolver(context.req) : `${method}:${normalizeUrl(rawPath)}`;
     const cached = await cache.get(key, void 0, options);
     if (cached !== null) {
       context.header?.("x-cache", "HIT");
@@ -384,12 +518,26 @@ function createHonoCacheMiddleware(cache, options = {}) {
     const originalJson = context.json.bind(context);
     context.json = (body, status) => {
       context.header?.("x-cache", "MISS");
-      void cache.set(key, body, options);
+      cache.set(key, body, options).catch((err) => {
+        cache.emit("error", {
+          operation: "set",
+          error: err instanceof Error ? err.message : String(err)
+        });
+      });
       return originalJson(body, status);
     };
     await next();
   };
 }
+function normalizeUrl(url) {
+  try {
+    const parsed = new URL(url, "http://localhost");
+    parsed.searchParams.sort();
+    return decodeURIComponent(parsed.pathname) + parsed.search;
+  } catch {
+    return url;
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   MemoryLayer,

package/dist/edge.d.cts

@@ -1,2 +1,2 @@
-export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-DLpdQN0W.cjs';
+export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-B_rUqDy6.cjs';
 import 'node:events';

package/dist/edge.d.ts

@@ -1,2 +1,2 @@
-export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-DLpdQN0W.js';
+export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-B_rUqDy6.js';
 import 'node:events';

package/dist/edge.js

@@ -2,10 +2,10 @@ import {
   MemoryLayer,
   TagIndex,
   createHonoCacheMiddleware
-} from "./chunk-46UH7LNM.js";
+} from "./chunk-KOYGHLVP.js";
 import {
   PatternMatcher
-} from "./chunk-ZMDB5KOK.js";
+} from "./chunk-7V7XAB74.js";
 export {
   MemoryLayer,
   PatternMatcher,