layercache 1.0.2 → 1.2.0

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-49%20passing-brightgreen)](https://github.com/flyingsquirrel0419/layercache)
+[![test coverage](https://img.shields.io/badge/tests-132%20passing-brightgreen)](https://github.com/flyingsquirrel0419/layercache)
 
 ```
 L1 hit  ~0.01 ms  ← served from memory, zero network
@@ -58,13 +58,17 @@ On a hit, the value is returned from the fastest layer that has it, and automati
 - **Event hooks** — `EventEmitter`-based events for hits, misses, stale serves, errors, and more
 - **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 gzip/brotli in `RedisLayer` with a byte threshold
-- **Metrics & stats** — per-layer hit/miss counters, circuit-breaker trips, degraded operations; HTTP stats handler
+- **Compression** — transparent async gzip/brotli in `RedisLayer` (non-blocking) with a byte threshold
+- **Metrics & stats** — per-layer hit/miss counters, **per-layer latency tracking**, circuit-breaker trips, degraded operations; HTTP stats handler
 - **Persistence** — `exportState` / `importState` for in-process snapshots; `persistToFile` / `restoreFromFile` for disk
 - **Admin CLI** — `layercache stats | keys | invalidate` against any Redis URL
-- **Framework integrations** — Fastify plugin, tRPC middleware, GraphQL resolver wrapper
+- **Framework integrations** — Express middleware, Fastify plugin, tRPC middleware, GraphQL resolver wrapper
 - **MessagePack serializer** — drop-in replacement for lower Redis memory usage
-- **NestJS module** — `CacheStackModule.forRoot(...)` with `@InjectCacheStack()`
+- **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
+- **Conditional caching** — `shouldCache` predicate to skip caching specific fetcher results
+- **Nested namespaces** — `namespace('a').namespace('b')` for composable key prefixes
 - **Custom layers** — implement the 5-method `CacheLayer` interface to plug in Memcached, DynamoDB, or anything else
 - **ESM + CJS** — works with both module systems, Node.js ≥ 18
 
@@ -250,6 +254,55 @@ const posts = cache.namespace('posts')
 
 await users.set('123', userData)          // stored as "users:123"
 await users.clear()                       // only deletes "users:*"
+
+// Nested namespaces
+const tenant = cache.namespace('tenant:abc')
+const posts = tenant.namespace('posts')
+await posts.set('1', postData)            // stored as "tenant:abc:posts:1"
+```
+
+### `cache.getOrThrow<T>(key, fetcher?, options?): Promise<T>`
+
+Like `get()`, but throws `CacheMissError` instead of returning `null`. Useful when you know the value must exist (e.g. after a warm-up).
+
+```ts
+import { CacheMissError } from 'layercache'
+
+try {
+  const config = await cache.getOrThrow<Config>('app:config')
+} catch (err) {
+  if (err instanceof CacheMissError) {
+    console.error(`Missing key: ${err.key}`)
+  }
+}
+```
+
+### `cache.inspect(key): Promise<CacheInspectResult | null>`
+
+Returns detailed metadata about a cache key for debugging. Returns `null` if the key is not in any layer.
+
+```ts
+const info = await cache.inspect('user:123')
+// {
+//   key: 'user:123',
+//   foundInLayers: ['memory', 'redis'],
+//   freshTtlSeconds: 45,
+//   staleTtlSeconds: 75,
+//   errorTtlSeconds: 345,
+//   isStale: false,
+//   tags: ['user', 'user:123']
+// }
+```
+
+### Conditional caching with `shouldCache`
+
+Skip caching specific results without affecting the return value:
+
+```ts
+const data = await cache.get('api:response', fetchFromApi, {
+  shouldCache: (value) => (value as any).status === 200
+})
+// If fetchFromApi returns { status: 500 }, the value is returned but NOT cached
 ```
 
 ---
@@ -591,6 +644,26 @@ cache.on('error', ({ event, context }) => logger.error(event, context))
 
 ## Framework integrations
 
+### Express
+
+```ts
+import { CacheStack, MemoryLayer, createExpressCacheMiddleware } from 'layercache'
+
+const cache = new CacheStack([new MemoryLayer({ ttl: 60 })])
+
+// Automatically caches GET responses as JSON
+app.get('/api/users', createExpressCacheMiddleware(cache, { ttl: 30 }), (req, res) => {
+  res.json(await db.getUsers())
+})
+
+// Custom key resolver + tag support
+app.get('/api/user/:id', createExpressCacheMiddleware(cache, {
+  keyResolver: (req) => `user:${req.url}`,
+  tags: ['users'],
+  ttl: 60
+}), handler)
+```
+
 ### tRPC
 
 ```ts
@@ -699,6 +772,25 @@ import { CacheStackModule } from '@cachestack/nestjs'
 export class AppModule {}
 ```
 
+Async configuration (resolve dependencies from DI):
+
+```ts
+@Module({
+  imports: [
+    CacheStackModule.forRootAsync({
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        layers: [
+          new MemoryLayer({ ttl: 20 }),
+          new RedisLayer({ client: new Redis(config.get('REDIS_URL')), ttl: 300 })
+        ]
+      })
+    })
+  ]
+})
+export class AppModule {}
+```
+
 ```ts
 // your.service.ts
 import { InjectCacheStack } from '@cachestack/nestjs'

package/benchmarks/latency.ts

@@ -1,5 +1,5 @@
-import Redis from 'ioredis-mock'
 import { performance } from 'node:perf_hooks'
+import Redis from 'ioredis-mock'
 import { CacheStack, MemoryLayer, RedisLayer } from '../src'
 
 async function main(): Promise<void> {

package/benchmarks/stampede.ts

@@ -3,10 +3,7 @@ import { CacheStack, MemoryLayer, RedisLayer } from '../src'
 
 async function main(): Promise<void> {
   const redis = new Redis()
-  const cache = new CacheStack([
-    new MemoryLayer({ ttl: 60 }),
-    new RedisLayer({ client: redis, ttl: 300 })
-  ])
+  const cache = new CacheStack([new MemoryLayer({ ttl: 60 }), new RedisLayer({ client: redis, ttl: 300 })])
 
   let executions = 0
 

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

@@ -1,9 +1,38 @@
 // src/invalidation/PatternMatcher.ts
-var PatternMatcher = class {
+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) {
-    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
-    const regex = new RegExp(`^${escaped.replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
-    return regex.test(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];
   }
 };
 
@@ -51,6 +80,9 @@ var RedisTagIndex = class {
   async keysForTag(tag) {
     return this.client.smembers(this.tagKeysKey(tag));
   }
+  async tagsForKey(key) {
+    return this.client.smembers(this.keyTagsKey(key));
+  }
   async matchPattern(pattern) {
     const matches = [];
     let cursor = "0";

package/dist/cli.cjs

@@ -37,11 +37,40 @@ module.exports = __toCommonJS(cli_exports);
 var import_ioredis = __toESM(require("ioredis"), 1);
 
 // src/invalidation/PatternMatcher.ts
-var PatternMatcher = class {
+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) {
-    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
-    const regex = new RegExp(`^${escaped.replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
-    return regex.test(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];
   }
 };
 
@@ -89,6 +118,9 @@ var RedisTagIndex = class {
   async keysForTag(tag) {
     return this.client.smembers(this.tagKeysKey(tag));
   }
+  async tagsForKey(key) {
+    return this.client.smembers(this.keyTagsKey(key));
+  }
   async matchPattern(pattern) {
     const matches = [];
     let cursor = "0";
@@ -136,6 +168,7 @@ var RedisTagIndex = class {
 };
 
 // src/cli.ts
+var CONNECT_TIMEOUT_MS = 5e3;
 async function main(argv = process.argv.slice(2)) {
   const args = parseArgs(argv);
   if (!args.command || !args.redisUrl) {
@@ -143,8 +176,25 @@ async function main(argv = process.argv.slice(2)) {
     process.exitCode = 1;
     return;
   }
-  const redis = new import_ioredis.default(args.redisUrl);
+  const redisUrl = validateRedisUrl(args.redisUrl);
+  if (!redisUrl) {
+    process.stderr.write(
+      `Error: invalid Redis URL "${args.redisUrl}". Expected format: redis://[user:password@]host[:port][/db]
+`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const redis = new import_ioredis.default(redisUrl, {
+    connectTimeout: CONNECT_TIMEOUT_MS,
+    lazyConnect: true,
+    enableReadyCheck: false
+  });
   try {
+    await redis.connect().catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to connect to Redis at "${redisUrl}": ${message}`);
+    });
     if (args.command === "stats") {
       const keys = await scanKeys(redis, args.pattern ?? "*");
       process.stdout.write(`${JSON.stringify({ totalKeys: keys.length, pattern: args.pattern ?? "*" }, null, 2)}
@@ -153,8 +203,10 @@ async function main(argv = process.argv.slice(2)) {
     }
     if (args.command === "keys") {
       const keys = await scanKeys(redis, args.pattern ?? "*");
-      process.stdout.write(`${keys.join("\n")}
+      if (keys.length > 0) {
+        process.stdout.write(`${keys.join("\n")}
 `);
+      }
       return;
     }
     if (args.command === "invalidate") {
@@ -162,7 +214,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)}
 `);
@@ -170,7 +222,7 @@ 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)}
 `);
@@ -178,10 +230,29 @@ async function main(argv = process.argv.slice(2)) {
     }
     printUsage();
     process.exitCode = 1;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Error: ${message}
+`);
+    process.exitCode = 1;
   } finally {
     redis.disconnect();
   }
 }
+function validateRedisUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "redis:" && parsed.protocol !== "rediss:") {
+      return null;
+    }
+    return url;
+  } catch {
+    if (/^[A-Za-z0-9._-]+(:\d+)?$/.test(url)) {
+      return url;
+    }
+    return null;
+  }
+}
 function parseArgs(argv) {
   const [command, ...rest] = argv;
   const parsed = { command };
@@ -204,6 +275,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";
@@ -216,7 +294,7 @@ 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"
+    "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"
   );
 }
 if (process.argv[1]?.includes("cli.")) {

package/dist/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import {
   RedisTagIndex
-} from "./chunk-IILH5XTS.js";
+} from "./chunk-BWM4MU2X.js";
 
 // src/cli.ts
 import Redis from "ioredis";
+var CONNECT_TIMEOUT_MS = 5e3;
 async function main(argv = process.argv.slice(2)) {
   const args = parseArgs(argv);
   if (!args.command || !args.redisUrl) {
@@ -12,8 +13,25 @@ async function main(argv = process.argv.slice(2)) {
     process.exitCode = 1;
     return;
   }
-  const redis = new Redis(args.redisUrl);
+  const redisUrl = validateRedisUrl(args.redisUrl);
+  if (!redisUrl) {
+    process.stderr.write(
+      `Error: invalid Redis URL "${args.redisUrl}". Expected format: redis://[user:password@]host[:port][/db]
+`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const redis = new Redis(redisUrl, {
+    connectTimeout: CONNECT_TIMEOUT_MS,
+    lazyConnect: true,
+    enableReadyCheck: false
+  });
   try {
+    await redis.connect().catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to connect to Redis at "${redisUrl}": ${message}`);
+    });
     if (args.command === "stats") {
       const keys = await scanKeys(redis, args.pattern ?? "*");
       process.stdout.write(`${JSON.stringify({ totalKeys: keys.length, pattern: args.pattern ?? "*" }, null, 2)}
@@ -22,8 +40,10 @@ async function main(argv = process.argv.slice(2)) {
     }
     if (args.command === "keys") {
       const keys = await scanKeys(redis, args.pattern ?? "*");
-      process.stdout.write(`${keys.join("\n")}
+      if (keys.length > 0) {
+        process.stdout.write(`${keys.join("\n")}
 `);
+      }
       return;
     }
     if (args.command === "invalidate") {
@@ -31,7 +51,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)}
 `);
@@ -39,7 +59,7 @@ 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)}
 `);
@@ -47,10 +67,29 @@ async function main(argv = process.argv.slice(2)) {
     }
     printUsage();
     process.exitCode = 1;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Error: ${message}
+`);
+    process.exitCode = 1;
   } finally {
     redis.disconnect();
   }
 }
+function validateRedisUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "redis:" && parsed.protocol !== "rediss:") {
+      return null;
+    }
+    return url;
+  } catch {
+    if (/^[A-Za-z0-9._-]+(:\d+)?$/.test(url)) {
+      return url;
+    }
+    return null;
+  }
+}
 function parseArgs(argv) {
   const [command, ...rest] = argv;
   const parsed = { command };
@@ -73,6 +112,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";
@@ -85,7 +131,7 @@ 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"
+    "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"
   );
 }
 if (process.argv[1]?.includes("cli.")) {