layercache 1.2.0 → 1.2.1

package/README.md

@@ -6,7 +6,7 @@
 [![npm downloads](https://img.shields.io/npm/dw/layercache)](https://www.npmjs.com/package/layercache)
 [![license](https://img.shields.io/npm/l/layercache)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-first-blue)](https://www.typescriptlang.org/)
-[![test coverage](https://img.shields.io/badge/tests-132%20passing-brightgreen)](https://github.com/flyingsquirrel0419/layercache)
+[![test coverage](https://img.shields.io/badge/tests-158%20passing-brightgreen)](https://github.com/flyingsquirrel0419/layercache)
 
 ```
 L1 hit  ~0.01 ms  ← served from memory, zero network
@@ -40,15 +40,22 @@ On a hit, the value is returned from the fastest layer that has it, and automati
 - **Layered reads & automatic backfill** — hits in slower layers propagate up
 - **Cache stampede prevention** — mutex-based deduplication per key
 - **Tag-based invalidation** — `set('user:123:posts', posts, { tags: ['user:123'] })` then `invalidateByTag('user:123')`
+- **Batch tag invalidation** — `invalidateByTags(['tenant:a', 'users'], 'all')` for OR/AND invalidation in one call
 - **Pattern invalidation** — `invalidateByPattern('user:*')`
+- **Prefix invalidation** — efficient `invalidateByPrefix('user:123:')` for hierarchical keys
+- **Generation-based invalidation** — `generation` prefixes keys with `vN:` and `bumpGeneration()` rotates the namespace instantly
 - **Per-layer TTL overrides** — different TTLs for memory vs. Redis in one call
+- **TTL policies** — align TTLs to time boundaries (`until-midnight`, `next-hour`, `{ alignTo }`, or a function)
 - **Negative caching** — cache known misses for a short TTL to protect the database
 - **Stale strategies** — `staleWhileRevalidate` and `staleIfError` as opt-in read behavior
 - **TTL jitter** — spread expirations to avoid synchronized stampedes
 - **Sliding & adaptive TTL** — extend TTL on every read or ramp it up for hot keys
 - **Refresh-ahead** — trigger background refresh when TTL drops below a threshold
+- **Fetcher rate limiting** — cap concurrent fetchers or requests per interval
 - **Best-effort writes** — tolerate partial layer write failures when desired
+- **Write-behind mode** — write local layers immediately and flush slower remote layers asynchronously
 - **Bulk reads** — `mget` uses layer-level `getMany()` when available
+- **Bulk writes** — `mset` uses layer-level `setMany()` when available
 - **Distributed tag index** — `RedisTagIndex` keeps tag state consistent across multiple servers
 - **Optional distributed single-flight** — plug in a coordinator to dedupe misses across instances
 - **Cross-server L1 invalidation** — Redis pub/sub bus flushes stale memory on other instances when you write or delete
@@ -59,17 +66,22 @@ On a hit, the value is returned from the fastest layer that has it, and automati
 - **Graceful degradation** — skip a failing layer for a configurable retry window
 - **Circuit breaker** — per-key or global; opens after N failures, recovers after cooldown
 - **Compression** — transparent async gzip/brotli in `RedisLayer` (non-blocking) with a byte threshold
+- **Serializer fallback chains** — transparently read legacy payloads (for example JSON) and rewrite them with the primary serializer
 - **Metrics & stats** — per-layer hit/miss counters, **per-layer latency tracking**, circuit-breaker trips, degraded operations; HTTP stats handler
+- **Health checks** — `cache.healthCheck()` returns per-layer health and latency
 - **Persistence** — `exportState` / `importState` for in-process snapshots; `persistToFile` / `restoreFromFile` for disk
-- **Admin CLI** — `layercache stats | keys | invalidate` against any Redis URL
-- **Framework integrations** — Express middleware, Fastify plugin, tRPC middleware, GraphQL resolver wrapper
+- **Admin CLI** — `layercache stats | keys | inspect | invalidate` against any Redis URL
+- **Framework integrations** — Express middleware, Fastify plugin, Hono middleware, tRPC middleware, GraphQL resolver wrapper
+- **OpenTelemetry plugin** — instrument `get` / `set` / invalidation flows with spans
 - **MessagePack serializer** — drop-in replacement for lower Redis memory usage
 - **NestJS module** — `CacheStackModule.forRoot(...)` and `forRootAsync(...)` with `@InjectCacheStack()`
 - **`getOrThrow()`** — throws `CacheMissError` instead of returning `null`, for strict use cases
 - **`inspect()`** — debug a key: see which layers hold it, remaining TTLs, tags, and staleness state
+- **MemoryLayer cleanup hooks** — periodic TTL cleanup and `onEvict` callbacks
 - **Conditional caching** — `shouldCache` predicate to skip caching specific fetcher results
-- **Nested namespaces** — `namespace('a').namespace('b')` for composable key prefixes
+- **Nested namespaces** — `namespace('a').namespace('b')` for composable key prefixes with namespace-scoped metrics
 - **Custom layers** — implement the 5-method `CacheLayer` interface to plug in Memcached, DynamoDB, or anything else
+- **Edge-safe entry point** — `layercache/edge` exports the non-Node helpers for Worker-style runtimes
 - **ESM + CJS** — works with both module systems, Node.js ≥ 18
 
 ---
@@ -168,6 +180,15 @@ await cache.set('user:123:posts', posts, { tags: ['user:123'] })
 await cache.invalidateByTag('user:123') // both keys gone
 ```
 
+### `cache.invalidateByTags(tags, mode?): Promise<void>`
+
+Delete keys that match any or all of a set of tags.
+
+```ts
+await cache.invalidateByTags(['tenant:a', 'users'], 'all') // keys tagged with both
+await cache.invalidateByTags(['users', 'posts'], 'any')    // keys tagged with either
+```
+
 ### `cache.invalidateByPattern(pattern): Promise<void>`
 
 Glob-style deletion against the tracked key set.
@@ -176,6 +197,16 @@ Glob-style deletion against the tracked key set.
 await cache.invalidateByPattern('user:*') // deletes user:1, user:2, …
 ```
 
+### `cache.invalidateByPrefix(prefix): Promise<void>`
+
+Prefer this over glob invalidation when your keys are hierarchical.
+
+```ts
+await cache.invalidateByPrefix('user:123:') // deletes user:123:profile, user:123:posts, ...
+```
+
+The prefix is matched as-is. You do not need to append `*`, and namespace helpers pass their namespace prefix directly.
+
 ### `cache.mget<T>(entries): Promise<Array<T | null>>`
 
 Concurrent multi-key fetch, each with its own optional fetcher.
@@ -195,6 +226,13 @@ const [user1, user2] = await cache.mget([
 const { hits, misses, fetches, staleHits, refreshes, writeFailures } = cache.getMetrics()
 ```
 
+### `cache.healthCheck(): Promise<CacheHealthCheckResult[]>`
+
+```ts
+const health = await cache.healthCheck()
+// [{ layer: 'memory', healthy: true, latencyMs: 0.03 }, ...]
+```
+
 ### `cache.resetMetrics(): void`
 
 Resets all counters to zero — useful for per-interval reporting.
@@ -229,6 +267,21 @@ const getUser = cache.wrap(
 )
 ```
 
+### Generation-based invalidation
+
+Add a generation prefix to every key and rotate it when you want to invalidate the whole cache namespace without scanning:
+
+```ts
+const cache = new CacheStack([...], { generation: 1 })
+
+await cache.set('user:123', user)
+cache.bumpGeneration() // now reads use v2:user:123
+```
+
+### OpenTelemetry note
+
+`createOpenTelemetryPlugin()` currently wraps a `CacheStack` instance's methods directly. Use one OpenTelemetry plugin per cache instance; if you need to compose multiple wrappers, install them in a fixed order and uninstall them in reverse order.
+
 ### `cache.warm(entries, options?)`
 
 Pre-populate layers at startup from a prioritised list. Higher `priority` values run first.
@@ -246,7 +299,7 @@ await cache.warm(
 
 ### `cache.namespace(prefix): CacheNamespace`
 
-Returns a scoped view with the same full API (`get`, `set`, `delete`, `clear`, `mget`, `wrap`, `warm`, `invalidateByTag`, `invalidateByPattern`, `getMetrics`). `clear()` only touches `prefix:*` keys.
+Returns a scoped view with the same full API (`get`, `set`, `delete`, `clear`, `mget`, `wrap`, `warm`, `invalidateByTag`, `invalidateByPattern`, `getMetrics`). `clear()` only touches `prefix:*` keys, and namespace metrics are serialized per `CacheStack` instance so unrelated caches do not block each other while metrics are collected.
 
 ```ts
 const users = cache.namespace('users')
@@ -305,6 +358,19 @@ const data = await cache.get('api:response', fetchFromApi, {
 // If fetchFromApi returns { status: 500 }, the value is returned but NOT cached
 ```
 
+### TTL policies
+
+Align expirations to calendar or boundary-based schedules:
+
+```ts
+await cache.set('daily-report', report, { ttlPolicy: 'until-midnight' })
+await cache.set('hourly-rollup', rollup, { ttlPolicy: 'next-hour' })
+await cache.set('aligned', value, { ttlPolicy: { alignTo: 300 } }) // next 5-minute boundary
+await cache.set('custom', value, {
+  ttlPolicy: ({ key, value }) => key.startsWith('hot:') ? 30 : 300
+})
+```
+
 ---
 
 ## Negative + stale caching

package/dist/chunk-46UH7LNM.js

@@ -0,0 +1,312 @@
+import {
+  PatternMatcher,
+  unwrapStoredValue
+} from "./chunk-ZMDB5KOK.js";
+
+// src/layers/MemoryLayer.ts
+var MemoryLayer = class {
+  name;
+  defaultTtl;
+  isLocal = true;
+  maxSize;
+  evictionPolicy;
+  onEvict;
+  entries = /* @__PURE__ */ new Map();
+  cleanupTimer;
+  constructor(options = {}) {
+    this.name = options.name ?? "memory";
+    this.defaultTtl = options.ttl;
+    this.maxSize = options.maxSize ?? 1e3;
+    this.evictionPolicy = options.evictionPolicy ?? "lru";
+    this.onEvict = options.onEvict;
+    if (options.cleanupIntervalMs && options.cleanupIntervalMs > 0) {
+      this.cleanupTimer = setInterval(() => {
+        this.pruneExpired();
+      }, options.cleanupIntervalMs);
+      this.cleanupTimer.unref?.();
+    }
+  }
+  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;
+    }
+    if (this.isExpired(entry)) {
+      this.entries.delete(key);
+      return null;
+    }
+    if (this.evictionPolicy === "lru") {
+      this.entries.delete(key);
+      entry.accessCount += 1;
+      this.entries.set(key, entry);
+    } else if (this.evictionPolicy === "lfu") {
+      entry.accessCount += 1;
+    }
+    return entry.value;
+  }
+  async getMany(keys) {
+    const values = [];
+    for (const key of keys) {
+      values.push(await this.getEntry(key));
+    }
+    return values;
+  }
+  async setMany(entries) {
+    for (const entry of entries) {
+      await this.set(entry.key, entry.value, entry.ttl);
+    }
+  }
+  async set(key, value, ttl = this.defaultTtl) {
+    this.entries.delete(key);
+    this.entries.set(key, {
+      value,
+      expiresAt: ttl && ttl > 0 ? Date.now() + ttl * 1e3 : null,
+      accessCount: 0,
+      insertedAt: Date.now()
+    });
+    while (this.entries.size > this.maxSize) {
+      this.evict();
+    }
+  }
+  async has(key) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return false;
+    }
+    if (this.isExpired(entry)) {
+      this.entries.delete(key);
+      return false;
+    }
+    return true;
+  }
+  async ttl(key) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return null;
+    }
+    if (this.isExpired(entry)) {
+      this.entries.delete(key);
+      return null;
+    }
+    if (entry.expiresAt === null) {
+      return null;
+    }
+    return Math.max(0, Math.ceil((entry.expiresAt - Date.now()) / 1e3));
+  }
+  async size() {
+    this.pruneExpired();
+    return this.entries.size;
+  }
+  async delete(key) {
+    this.entries.delete(key);
+  }
+  async deleteMany(keys) {
+    for (const key of keys) {
+      this.entries.delete(key);
+    }
+  }
+  async clear() {
+    this.entries.clear();
+  }
+  async ping() {
+    return true;
+  }
+  async dispose() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = void 0;
+    }
+  }
+  async keys() {
+    this.pruneExpired();
+    return [...this.entries.keys()];
+  }
+  exportState() {
+    this.pruneExpired();
+    return [...this.entries.entries()].map(([key, entry]) => ({
+      key,
+      value: entry.value,
+      expiresAt: entry.expiresAt
+    }));
+  }
+  importState(entries) {
+    for (const entry of entries) {
+      if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+        continue;
+      }
+      this.entries.set(entry.key, {
+        value: entry.value,
+        expiresAt: entry.expiresAt,
+        accessCount: 0,
+        insertedAt: Date.now()
+      });
+    }
+    while (this.entries.size > this.maxSize) {
+      this.evict();
+    }
+  }
+  evict() {
+    if (this.evictionPolicy === "lru" || this.evictionPolicy === "fifo") {
+      const oldestKey = this.entries.keys().next().value;
+      if (oldestKey !== void 0) {
+        const entry = this.entries.get(oldestKey);
+        this.entries.delete(oldestKey);
+        if (entry) {
+          this.onEvict?.(oldestKey, unwrapStoredValue(entry.value));
+        }
+      }
+      return;
+    }
+    let victimKey;
+    let minCount = Number.POSITIVE_INFINITY;
+    let minInsertedAt = Number.POSITIVE_INFINITY;
+    for (const [key, entry] of this.entries.entries()) {
+      if (entry.accessCount < minCount || entry.accessCount === minCount && entry.insertedAt < minInsertedAt) {
+        minCount = entry.accessCount;
+        minInsertedAt = entry.insertedAt;
+        victimKey = key;
+      }
+    }
+    if (victimKey !== void 0) {
+      const victim = this.entries.get(victimKey);
+      this.entries.delete(victimKey);
+      if (victim) {
+        this.onEvict?.(victimKey, unwrapStoredValue(victim.value));
+      }
+    }
+  }
+  pruneExpired() {
+    for (const [key, entry] of this.entries.entries()) {
+      if (this.isExpired(entry)) {
+        this.entries.delete(key);
+      }
+    }
+  }
+  isExpired(entry) {
+    return entry.expiresAt !== null && entry.expiresAt <= Date.now();
+  }
+};
+
+// src/invalidation/TagIndex.ts
+var TagIndex = class {
+  tagToKeys = /* @__PURE__ */ new Map();
+  keyToTags = /* @__PURE__ */ new Map();
+  knownKeys = /* @__PURE__ */ new Set();
+  maxKnownKeys;
+  constructor(options = {}) {
+    this.maxKnownKeys = options.maxKnownKeys;
+  }
+  async touch(key) {
+    this.knownKeys.add(key);
+    this.pruneKnownKeysIfNeeded();
+  }
+  async track(key, tags) {
+    this.knownKeys.add(key);
+    this.pruneKnownKeysIfNeeded();
+    if (tags.length === 0) {
+      return;
+    }
+    const existingTags = this.keyToTags.get(key);
+    if (existingTags) {
+      for (const tag of existingTags) {
+        this.tagToKeys.get(tag)?.delete(key);
+      }
+    }
+    const tagSet = new Set(tags);
+    this.keyToTags.set(key, tagSet);
+    for (const tag of tagSet) {
+      const keys = this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set();
+      keys.add(key);
+      this.tagToKeys.set(tag, keys);
+    }
+  }
+  async remove(key) {
+    this.removeKey(key);
+  }
+  async keysForTag(tag) {
+    return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
+  }
+  async keysForPrefix(prefix) {
+    return [...this.knownKeys].filter((key) => key.startsWith(prefix));
+  }
+  async tagsForKey(key) {
+    return [...this.keyToTags.get(key) ?? /* @__PURE__ */ new Set()];
+  }
+  async matchPattern(pattern) {
+    return [...this.knownKeys].filter((key) => PatternMatcher.matches(pattern, key));
+  }
+  async clear() {
+    this.tagToKeys.clear();
+    this.keyToTags.clear();
+    this.knownKeys.clear();
+  }
+  pruneKnownKeysIfNeeded() {
+    if (this.maxKnownKeys === void 0 || this.knownKeys.size <= this.maxKnownKeys) {
+      return;
+    }
+    const toRemove = Math.ceil(this.maxKnownKeys * 0.1);
+    let removed = 0;
+    for (const key of this.knownKeys) {
+      if (removed >= toRemove) {
+        break;
+      }
+      this.removeKey(key);
+      removed += 1;
+    }
+  }
+  removeKey(key) {
+    this.knownKeys.delete(key);
+    const tags = this.keyToTags.get(key);
+    if (!tags) {
+      return;
+    }
+    for (const tag of tags) {
+      const keys = this.tagToKeys.get(tag);
+      if (!keys) {
+        continue;
+      }
+      keys.delete(key);
+      if (keys.size === 0) {
+        this.tagToKeys.delete(tag);
+      }
+    }
+    this.keyToTags.delete(key);
+  }
+};
+
+// src/integrations/hono.ts
+function createHonoCacheMiddleware(cache, options = {}) {
+  const allowedMethods = new Set((options.methods ?? ["GET"]).map((method) => method.toUpperCase()));
+  return async (context, next) => {
+    const method = (context.req.method ?? "GET").toUpperCase();
+    if (!allowedMethods.has(method)) {
+      await next();
+      return;
+    }
+    const key = options.keyResolver ? options.keyResolver(context.req) : `${method}:${context.req.path ?? context.req.url ?? "/"}`;
+    const cached = await cache.get(key, void 0, options);
+    if (cached !== null) {
+      context.header?.("x-cache", "HIT");
+      context.header?.("content-type", "application/json; charset=utf-8");
+      context.json(cached);
+      return;
+    }
+    const originalJson = context.json.bind(context);
+    context.json = (body, status) => {
+      context.header?.("x-cache", "MISS");
+      void cache.set(key, body, options);
+      return originalJson(body, status);
+    };
+    await next();
+  };
+}
+
+export {
+  MemoryLayer,
+  TagIndex,
+  createHonoCacheMiddleware
+};

package/dist/{chunk-BWM4MU2X.js → chunk-GF47Y3XR.js}

@@ -1,40 +1,6 @@
-// src/invalidation/PatternMatcher.ts
-var PatternMatcher = class _PatternMatcher {
-  /**
-   * Tests whether a glob-style pattern matches a value.
-   * Supports `*` (any sequence of characters) and `?` (any single character).
-   * Uses a linear-time algorithm to avoid ReDoS vulnerabilities.
-   */
-  static matches(pattern, value) {
-    return _PatternMatcher.matchLinear(pattern, value);
-  }
-  /**
-   * Linear-time glob matching using dynamic programming.
-   * Avoids catastrophic backtracking that RegExp-based glob matching can cause.
-   */
-  static matchLinear(pattern, value) {
-    const m = pattern.length;
-    const n = value.length;
-    const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(false));
-    dp[0][0] = true;
-    for (let i = 1; i <= m; i++) {
-      if (pattern[i - 1] === "*") {
-        dp[i][0] = dp[i - 1]?.[0];
-      }
-    }
-    for (let i = 1; i <= m; i++) {
-      for (let j = 1; j <= n; j++) {
-        const pc = pattern[i - 1];
-        if (pc === "*") {
-          dp[i][j] = dp[i - 1]?.[j] || dp[i]?.[j - 1];
-        } else if (pc === "?" || pc === value[j - 1]) {
-          dp[i][j] = dp[i - 1]?.[j - 1];
-        }
-      }
-    }
-    return dp[m]?.[n];
-  }
-};
+import {
+  PatternMatcher
+} from "./chunk-ZMDB5KOK.js";
 
 // src/invalidation/RedisTagIndex.ts
 var RedisTagIndex = class {
@@ -80,6 +46,16 @@ var RedisTagIndex = class {
   async keysForTag(tag) {
     return this.client.smembers(this.tagKeysKey(tag));
   }
+  async keysForPrefix(prefix) {
+    const matches = [];
+    let cursor = "0";
+    do {
+      const [nextCursor, keys] = await this.client.sscan(this.knownKeysKey(), cursor, "COUNT", this.scanCount);
+      cursor = nextCursor;
+      matches.push(...keys.filter((key) => key.startsWith(prefix)));
+    } while (cursor !== "0");
+    return matches;
+  }
   async tagsForKey(key) {
     return this.client.smembers(this.keyTagsKey(key));
   }
@@ -130,6 +106,5 @@ var RedisTagIndex = class {
 };
 
 export {
-  PatternMatcher,
   RedisTagIndex
 };

package/dist/chunk-ZMDB5KOK.js

@@ -0,0 +1,159 @@
+// 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,
+    freshTtlSeconds: freshTtlSeconds ?? null,
+    staleWhileRevalidateSeconds: staleWhileRevalidateSeconds ?? null,
+    staleIfErrorSeconds: staleIfErrorSeconds ?? null
+  };
+}
+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 remainingFreshTtlSeconds(stored, now = Date.now()) {
+  if (!isStoredValueEnvelope(stored) || stored.freshUntil === null) {
+    return void 0;
+  }
+  const remainingMs = stored.freshUntil - now;
+  if (remainingMs <= 0) {
+    return 0;
+  }
+  return Math.max(1, Math.ceil(remainingMs / 1e3));
+}
+function refreshStoredEnvelope(stored, now = Date.now()) {
+  if (!isStoredValueEnvelope(stored)) {
+    return stored;
+  }
+  return createStoredValueEnvelope({
+    kind: stored.kind,
+    value: stored.value,
+    freshTtlSeconds: stored.freshTtlSeconds ?? void 0,
+    staleWhileRevalidateSeconds: stored.staleWhileRevalidateSeconds ?? void 0,
+    staleIfErrorSeconds: stored.staleIfErrorSeconds ?? void 0,
+    now
+  });
+}
+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 _PatternMatcher {
+  /**
+   * Tests whether a glob-style pattern matches a value.
+   * Supports `*` (any sequence of characters) and `?` (any single character).
+   * Uses a two-pointer algorithm to avoid ReDoS vulnerabilities and
+   * quadratic memory usage on long patterns/keys.
+   */
+  static matches(pattern, value) {
+    return _PatternMatcher.matchLinear(pattern, value);
+  }
+  /**
+   * Linear-time glob matching with O(1) extra memory.
+   */
+  static matchLinear(pattern, value) {
+    let patternIndex = 0;
+    let valueIndex = 0;
+    let starIndex = -1;
+    let backtrackValueIndex = 0;
+    while (valueIndex < value.length) {
+      const patternChar = pattern[patternIndex];
+      const valueChar = value[valueIndex];
+      if (patternChar === "*" && patternIndex < pattern.length) {
+        starIndex = patternIndex;
+        patternIndex += 1;
+        backtrackValueIndex = valueIndex;
+        continue;
+      }
+      if (patternChar === "?" || patternChar === valueChar) {
+        patternIndex += 1;
+        valueIndex += 1;
+        continue;
+      }
+      if (starIndex !== -1) {
+        patternIndex = starIndex + 1;
+        backtrackValueIndex += 1;
+        valueIndex = backtrackValueIndex;
+        continue;
+      }
+      return false;
+    }
+    while (patternIndex < pattern.length && pattern[patternIndex] === "*") {
+      patternIndex += 1;
+    }
+    return patternIndex === pattern.length;
+  }
+};
+
+export {
+  isStoredValueEnvelope,
+  createStoredValueEnvelope,
+  resolveStoredValue,
+  unwrapStoredValue,
+  remainingStoredTtlSeconds,
+  remainingFreshTtlSeconds,
+  refreshStoredEnvelope,
+  PatternMatcher
+};