layercache 1.1.0 → 1.2.1

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;
   }
 };
 
@@ -118,6 +157,19 @@ 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));
+  }
   async matchPattern(pattern) {
     const matches = [];
     let cursor = "0";
@@ -211,7 +263,7 @@ async function main(argv = process.argv.slice(2)) {
         const tagIndex = new RedisTagIndex({ client: redis, prefix: args.tagIndexPrefix ?? "layercache:tag-index" });
         const keys2 = await tagIndex.keysForTag(args.tag);
         if (keys2.length > 0) {
-          await redis.del(...keys2);
+          await batchDelete(redis, keys2);
         }
         process.stdout.write(`${JSON.stringify({ deletedKeys: keys2.length, tag: args.tag }, null, 2)}
 `);
@@ -219,12 +271,37 @@ async function main(argv = process.argv.slice(2)) {
       }
       const keys = await scanKeys(redis, args.pattern ?? "*");
       if (keys.length > 0) {
-        await redis.del(...keys);
+        await batchDelete(redis, keys);
       }
       process.stdout.write(`${JSON.stringify({ deletedKeys: keys.length, pattern: args.pattern ?? "*" }, null, 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) {
@@ -265,6 +342,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;
@@ -272,6 +352,13 @@ function parseArgs(argv) {
   }
   return parsed;
 }
+var BATCH_DELETE_SIZE = 500;
+async function batchDelete(redis, keys) {
+  for (let i = 0; i < keys.length; i += BATCH_DELETE_SIZE) {
+    const batch = keys.slice(i, i + BATCH_DELETE_SIZE);
+    await redis.del(...batch);
+  }
+}
 async function scanKeys(redis, pattern) {
   const keys = [];
   let cursor = "0";
@@ -284,9 +371,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();
 }

package/dist/cli.js

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
 import {
   RedisTagIndex
-} from "./chunk-QUB5VZFZ.js";
+} from "./chunk-GF47Y3XR.js";
+import {
+  isStoredValueEnvelope,
+  resolveStoredValue
+} from "./chunk-ZMDB5KOK.js";
 
 // src/cli.ts
 import Redis from "ioredis";
@@ -51,7 +55,7 @@ async function main(argv = process.argv.slice(2)) {
         const tagIndex = new RedisTagIndex({ client: redis, prefix: args.tagIndexPrefix ?? "layercache:tag-index" });
         const keys2 = await tagIndex.keysForTag(args.tag);
         if (keys2.length > 0) {
-          await redis.del(...keys2);
+          await batchDelete(redis, keys2);
         }
         process.stdout.write(`${JSON.stringify({ deletedKeys: keys2.length, tag: args.tag }, null, 2)}
 `);
@@ -59,12 +63,37 @@ async function main(argv = process.argv.slice(2)) {
       }
       const keys = await scanKeys(redis, args.pattern ?? "*");
       if (keys.length > 0) {
-        await redis.del(...keys);
+        await batchDelete(redis, keys);
       }
       process.stdout.write(`${JSON.stringify({ deletedKeys: keys.length, pattern: args.pattern ?? "*" }, null, 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) {
@@ -105,6 +134,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;
@@ -112,6 +144,13 @@ function parseArgs(argv) {
   }
   return parsed;
 }
+var BATCH_DELETE_SIZE = 500;
+async function batchDelete(redis, keys) {
+  for (let i = 0; i < keys.length; i += BATCH_DELETE_SIZE) {
+    const batch = keys.slice(i, i + BATCH_DELETE_SIZE);
+    await redis.del(...batch);
+  }
+}
 async function scanKeys(redis, pattern) {
   const keys = [];
   let cursor = "0";
@@ -124,9 +163,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();
 }