layercache 1.2.0 → 1.2.2

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

@@ -1,59 +1,27 @@
-// 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 {
   client;
   prefix;
   scanCount;
+  knownKeysShards;
   constructor(options) {
     this.client = options.client;
     this.prefix = options.prefix ?? "layercache:tag-index";
     this.scanCount = options.scanCount ?? 100;
+    this.knownKeysShards = normalizeKnownKeysShards(options.knownKeysShards);
   }
   async touch(key) {
-    await this.client.sadd(this.knownKeysKey(), key);
+    await this.client.sadd(this.knownKeysKeyFor(key), key);
   }
   async track(key, tags) {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
     const pipeline = this.client.pipeline();
-    pipeline.sadd(this.knownKeysKey(), key);
+    pipeline.sadd(this.knownKeysKeyFor(key), key);
     for (const tag of existingTags) {
       pipeline.srem(this.tagKeysKey(tag), key);
     }
@@ -70,7 +38,7 @@ var RedisTagIndex = class {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
     const pipeline = this.client.pipeline();
-    pipeline.srem(this.knownKeysKey(), key);
+    pipeline.srem(this.knownKeysKeyFor(key), key);
     pipeline.del(keyTagsKey);
     for (const tag of existingTags) {
       pipeline.srem(this.tagKeysKey(tag), key);
@@ -80,24 +48,38 @@ var RedisTagIndex = class {
   async keysForTag(tag) {
     return this.client.smembers(this.tagKeysKey(tag));
   }
+  async keysForPrefix(prefix) {
+    const matches = [];
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(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));
   }
   async matchPattern(pattern) {
     const matches = [];
-    let cursor = "0";
-    do {
-      const [nextCursor, keys] = await this.client.sscan(
-        this.knownKeysKey(),
-        cursor,
-        "MATCH",
-        pattern,
-        "COUNT",
-        this.scanCount
-      );
-      cursor = nextCursor;
-      matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
-    } while (cursor !== "0");
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(
+          knownKeysKey,
+          cursor,
+          "MATCH",
+          pattern,
+          "COUNT",
+          this.scanCount
+        );
+        cursor = nextCursor;
+        matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
+      } while (cursor !== "0");
+    }
     return matches;
   }
   async clear() {
@@ -118,8 +100,17 @@ var RedisTagIndex = class {
     } while (cursor !== "0");
     return matches;
   }
-  knownKeysKey() {
-    return `${this.prefix}:keys`;
+  knownKeysKeyFor(key) {
+    if (this.knownKeysShards === 1) {
+      return `${this.prefix}:keys`;
+    }
+    return `${this.prefix}:keys:${simpleHash(key) % this.knownKeysShards}`;
+  }
+  knownKeysKeys() {
+    if (this.knownKeysShards === 1) {
+      return [`${this.prefix}:keys`];
+    }
+    return Array.from({ length: this.knownKeysShards }, (_, index) => `${this.prefix}:keys:${index}`);
   }
   keyTagsKey(key) {
     return `${this.prefix}:key:${encodeURIComponent(key)}`;
@@ -128,8 +119,23 @@ var RedisTagIndex = class {
     return `${this.prefix}:tag:${encodeURIComponent(tag)}`;
   }
 };
+function normalizeKnownKeysShards(value) {
+  if (value === void 0) {
+    return 1;
+  }
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error("RedisTagIndex.knownKeysShards must be a positive integer.");
+  }
+  return value;
+}
+function simpleHash(value) {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = hash * 31 + value.charCodeAt(index) >>> 0;
+  }
+  return hash;
+}
 
 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
+};

package/dist/cli.cjs

@@ -36,41 +36,80 @@ __export(cli_exports, {
 module.exports = __toCommonJS(cli_exports);
 var import_ioredis = __toESM(require("ioredis"), 1);
 
+// src/internal/StoredValue.ts
+function isStoredValueEnvelope(value) {
+  return typeof value === "object" && value !== null && "__layercache" in value && value.__layercache === 1 && "kind" in value;
+}
+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;
+}
+
 // 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.
+   * 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 using dynamic programming.
-   * Avoids catastrophic backtracking that RegExp-based glob matching can cause.
+   * Linear-time glob matching with O(1) extra memory.
    */
   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];
+    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;
       }
-    }
-    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];
-        }
+      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 dp[m]?.[n];
+    return patternIndex === pattern.length;
   }
 };
 
@@ -79,19 +118,21 @@ var RedisTagIndex = class {
   client;
   prefix;
   scanCount;
+  knownKeysShards;
   constructor(options) {
     this.client = options.client;
     this.prefix = options.prefix ?? "layercache:tag-index";
     this.scanCount = options.scanCount ?? 100;
+    this.knownKeysShards = normalizeKnownKeysShards(options.knownKeysShards);
   }
   async touch(key) {
-    await this.client.sadd(this.knownKeysKey(), key);
+    await this.client.sadd(this.knownKeysKeyFor(key), key);
   }
   async track(key, tags) {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
     const pipeline = this.client.pipeline();
-    pipeline.sadd(this.knownKeysKey(), key);
+    pipeline.sadd(this.knownKeysKeyFor(key), key);
     for (const tag of existingTags) {
       pipeline.srem(this.tagKeysKey(tag), key);
     }
@@ -108,7 +149,7 @@ var RedisTagIndex = class {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
     const pipeline = this.client.pipeline();
-    pipeline.srem(this.knownKeysKey(), key);
+    pipeline.srem(this.knownKeysKeyFor(key), key);
     pipeline.del(keyTagsKey);
     for (const tag of existingTags) {
       pipeline.srem(this.tagKeysKey(tag), key);
@@ -118,24 +159,38 @@ var RedisTagIndex = class {
   async keysForTag(tag) {
     return this.client.smembers(this.tagKeysKey(tag));
   }
+  async keysForPrefix(prefix) {
+    const matches = [];
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(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));
   }
   async matchPattern(pattern) {
     const matches = [];
-    let cursor = "0";
-    do {
-      const [nextCursor, keys] = await this.client.sscan(
-        this.knownKeysKey(),
-        cursor,
-        "MATCH",
-        pattern,
-        "COUNT",
-        this.scanCount
-      );
-      cursor = nextCursor;
-      matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
-    } while (cursor !== "0");
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(
+          knownKeysKey,
+          cursor,
+          "MATCH",
+          pattern,
+          "COUNT",
+          this.scanCount
+        );
+        cursor = nextCursor;
+        matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
+      } while (cursor !== "0");
+    }
     return matches;
   }
   async clear() {
@@ -156,8 +211,17 @@ var RedisTagIndex = class {
     } while (cursor !== "0");
     return matches;
   }
-  knownKeysKey() {
-    return `${this.prefix}:keys`;
+  knownKeysKeyFor(key) {
+    if (this.knownKeysShards === 1) {
+      return `${this.prefix}:keys`;
+    }
+    return `${this.prefix}:keys:${simpleHash(key) % this.knownKeysShards}`;
+  }
+  knownKeysKeys() {
+    if (this.knownKeysShards === 1) {
+      return [`${this.prefix}:keys`];
+    }
+    return Array.from({ length: this.knownKeysShards }, (_, index) => `${this.prefix}:keys:${index}`);
   }
   keyTagsKey(key) {
     return `${this.prefix}:key:${encodeURIComponent(key)}`;
@@ -166,6 +230,22 @@ var RedisTagIndex = class {
     return `${this.prefix}:tag:${encodeURIComponent(tag)}`;
   }
 };
+function normalizeKnownKeysShards(value) {
+  if (value === void 0) {
+    return 1;
+  }
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error("RedisTagIndex.knownKeysShards must be a positive integer.");
+  }
+  return value;
+}
+function simpleHash(value) {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = hash * 31 + value.charCodeAt(index) >>> 0;
+  }
+  return hash;
+}
 
 // src/cli.ts
 var CONNECT_TIMEOUT_MS = 5e3;
@@ -228,6 +308,31 @@ async function main(argv = process.argv.slice(2)) {
 `);
       return;
     }
+    if (args.command === "inspect") {
+      if (!args.key) {
+        throw new Error("inspect requires --key <key>.");
+      }
+      const payload = await redis.getBuffer(args.key);
+      const ttl = await redis.ttl(args.key);
+      const decoded = decodeInspectablePayload(payload);
+      process.stdout.write(
+        `${JSON.stringify(
+          {
+            key: args.key,
+            exists: payload !== null,
+            ttlSeconds: ttl >= 0 ? ttl : null,
+            sizeBytes: payload?.byteLength ?? 0,
+            isEnvelope: isStoredValueEnvelope(decoded),
+            state: payload === null ? null : resolveStoredValue(decoded).state,
+            preview: summarizeInspectableValue(decoded)
+          },
+          null,
+          2
+        )}
+`
+      );
+      return;
+    }
     printUsage();
     process.exitCode = 1;
   } catch (error) {
@@ -268,6 +373,9 @@ function parseArgs(argv) {
     } else if (token === "--tag") {
       parsed.tag = value;
       index += 1;
+    } else if (token === "--key") {
+      parsed.key = value;
+      index += 1;
     } else if (token === "--tag-index-prefix") {
       parsed.tagIndexPrefix = value;
       index += 1;
@@ -294,9 +402,32 @@ async function scanKeys(redis, pattern) {
 }
 function printUsage() {
   process.stdout.write(
-    "Usage:\n  layercache stats --redis <url> [--pattern <glob>]\n  layercache keys --redis <url> [--pattern <glob>]\n  layercache invalidate --redis <url> [--pattern <glob> | --tag <tag>] [--tag-index-prefix <prefix>]\n\nOptions:\n  --redis <url>               Redis connection URL (e.g. redis://localhost:6379)\n  --pattern <glob>            Glob pattern to filter keys (default: *)\n  --tag <tag>                 Invalidate by tag name\n  --tag-index-prefix <prefix> Redis key prefix for tag index (default: layercache:tag-index)\n"
+    "Usage:\n  layercache stats --redis <url> [--pattern <glob>]\n  layercache keys --redis <url> [--pattern <glob>]\n  layercache inspect --redis <url> --key <key>\n  layercache invalidate --redis <url> [--pattern <glob> | --tag <tag>] [--tag-index-prefix <prefix>]\n\nOptions:\n  --redis <url>               Redis connection URL (e.g. redis://localhost:6379)\n  --pattern <glob>            Glob pattern to filter keys (default: *)\n  --key <key>                 Exact cache key to inspect\n  --tag <tag>                 Invalidate by tag name\n  --tag-index-prefix <prefix> Redis key prefix for tag index (default: layercache:tag-index)\n"
   );
 }
+function decodeInspectablePayload(payload) {
+  if (payload === null) {
+    return null;
+  }
+  const text = payload.toString("utf8");
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text.length > 256 ? `${text.slice(0, 256)}...` : text;
+  }
+}
+function summarizeInspectableValue(value) {
+  if (isStoredValueEnvelope(value)) {
+    return {
+      kind: value.kind,
+      value: value.value,
+      freshUntil: value.freshUntil,
+      staleUntil: value.staleUntil,
+      errorUntil: value.errorUntil
+    };
+  }
+  return value;
+}
 if (process.argv[1]?.includes("cli.")) {
   void main();
 }