layercache 1.1.0 → 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/dist/{chunk-QUB5VZFZ.js → chunk-BWM4MU2X.js}

@@ -80,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

@@ -118,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";
@@ -211,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)}
 `);
@@ -219,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)}
 `);
@@ -272,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";

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   RedisTagIndex
-} from "./chunk-QUB5VZFZ.js";
+} from "./chunk-BWM4MU2X.js";
 
 // src/cli.ts
 import Redis from "ioredis";
@@ -51,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)}
 `);
@@ -59,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)}
 `);
@@ -112,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";