layercache 1.2.7 → 1.2.9

package/README.md

@@ -15,8 +15,8 @@
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-green" alt="license"></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-first-3178C6?logo=typescript&logoColor=white" alt="TypeScript"></a>
   <img src="https://img.shields.io/badge/Node.js-%E2%89%A5_20-339933?logo=nodedotjs&logoColor=white" alt="Node.js >= 20">
-  <img src="https://img.shields.io/badge/tests-393_passing-brightgreen" alt="tests">
-  <a href="https://coveralls.io/github/flyingsquirrel0419/layercache?branch=main"><img src="https://coveralls.io/repos/github/flyingsquirrel0419/layercache/badge.svg?branch=main" alt="Coveralls"></a>
+  <img src="https://img.shields.io/badge/tests-411_passing-brightgreen" alt="tests">
+  <a href="https://coveralls.io/github/flyingsquirrel0419/layercache?branch=main"><img src="https://coveralls.io/repos/github/flyingsquirrel0419/layercache/badge.svg?branch=main&t=20260410" alt="Coveralls"></a>
 </p>
 
 <p align="center">
@@ -163,7 +163,7 @@ const cache = new CacheStack([
 | **Per-layer latency** | Avg, max, and sample count using Welford's algorithm |
 | **Health checks** | Async health endpoint per layer with latency measurement |
 | **Event hooks** | `hit`, `miss`, `set`, `delete`, `stale-serve`, `stampede-dedupe`, `backfill`, `warm`, `error` |
-| **OpenTelemetry** | Distributed tracing support |
+| **OpenTelemetry** | Hook-based distributed tracing support without method monkey-patching |
 | **Prometheus exporter** | Metrics export including latency gauges |
 | **HTTP stats handler** | JSON endpoint for dashboards |
 | **Admin CLI** | `npx layercache stats\|keys\|invalidate` for Redis-backed caches |
@@ -183,7 +183,7 @@ layercache plugs into the frameworks you already use:
 | **GraphQL** | `cacheGraphqlResolver(cache, prefix, resolver, opts)` - field resolver wrapper |
 | **NestJS** | `@cachestack/nestjs` - `CacheStackModule.forRoot()`, `@Cacheable()` decorator |
 | **Next.js** | Works natively with App Router and API routes |
-| **OpenTelemetry** | `createOpenTelemetryPlugin(cache, tracer)` - distributed tracing spans |
+| **OpenTelemetry** | `createOpenTelemetryPlugin(cache, tracer)` - event-driven tracing spans without monkey-patching |
 
 <details>
 <summary><b>Express example</b></summary>

package/dist/cli.cjs

@@ -373,7 +373,7 @@ async function main(argv = process.argv.slice(2)) {
   try {
     await redis.connect().catch((error) => {
       const message = error instanceof Error ? error.message : String(error);
-      throw new Error(`Failed to connect to Redis: ${message}`);
+      throw new Error(`Failed to connect to Redis at ${maskRedisUrl(redisUrl)}: ${message}`);
     });
     if (args.command === "stats") {
       const keys = await scanKeys(redis, args.pattern ?? "*");
@@ -465,6 +465,11 @@ function parseArgs(argv) {
     const token = rest[index];
     const value = rest[index + 1];
     if (token === "--redis") {
+      if (!value || value.startsWith("--")) {
+        process.stderr.write("Error: --redis requires a value (e.g. redis://localhost:6379)\n");
+        process.exitCode = 1;
+        return parsed;
+      }
       parsed.redisUrl = value;
       index += 1;
     } else if (token === "--pattern") {
@@ -484,6 +489,7 @@ function parseArgs(argv) {
   return parsed;
 }
 var BATCH_DELETE_SIZE = 500;
+var SCAN_MAX_KEYS = 1e6;
 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);
@@ -497,6 +503,13 @@ async function scanKeys(redis, pattern) {
     const [nextCursor, batch] = await redis.scan(cursor, "MATCH", pattern, "COUNT", 100);
     cursor = nextCursor;
     keys.push(...batch);
+    if (keys.length >= SCAN_MAX_KEYS) {
+      process.stderr.write(
+        `Warning: stopped scanning after ${SCAN_MAX_KEYS} keys. Use a more specific --pattern to narrow results.
+`
+      );
+      return keys;
+    }
   } while (cursor !== "0");
   return keys;
 }
@@ -528,7 +541,18 @@ function summarizeInspectableValue(value) {
   }
   return value;
 }
-if (process.argv[1]?.includes("cli.")) {
+function maskRedisUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.password) {
+      parsed.password = "***";
+    }
+    return parsed.toString();
+  } catch {
+    return url.replace(/:([^@/]+)@/, ":***@");
+  }
+}
+if (process.argv[1]?.endsWith("cli.cjs") || process.argv[1]?.endsWith("cli.js")) {
   void main();
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/cli.js

@@ -31,7 +31,7 @@ async function main(argv = process.argv.slice(2)) {
   try {
     await redis.connect().catch((error) => {
       const message = error instanceof Error ? error.message : String(error);
-      throw new Error(`Failed to connect to Redis: ${message}`);
+      throw new Error(`Failed to connect to Redis at ${maskRedisUrl(redisUrl)}: ${message}`);
     });
     if (args.command === "stats") {
       const keys = await scanKeys(redis, args.pattern ?? "*");
@@ -123,6 +123,11 @@ function parseArgs(argv) {
     const token = rest[index];
     const value = rest[index + 1];
     if (token === "--redis") {
+      if (!value || value.startsWith("--")) {
+        process.stderr.write("Error: --redis requires a value (e.g. redis://localhost:6379)\n");
+        process.exitCode = 1;
+        return parsed;
+      }
       parsed.redisUrl = value;
       index += 1;
     } else if (token === "--pattern") {
@@ -142,6 +147,7 @@ function parseArgs(argv) {
   return parsed;
 }
 var BATCH_DELETE_SIZE = 500;
+var SCAN_MAX_KEYS = 1e6;
 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);
@@ -155,6 +161,13 @@ async function scanKeys(redis, pattern) {
     const [nextCursor, batch] = await redis.scan(cursor, "MATCH", pattern, "COUNT", 100);
     cursor = nextCursor;
     keys.push(...batch);
+    if (keys.length >= SCAN_MAX_KEYS) {
+      process.stderr.write(
+        `Warning: stopped scanning after ${SCAN_MAX_KEYS} keys. Use a more specific --pattern to narrow results.
+`
+      );
+      return keys;
+    }
   } while (cursor !== "0");
   return keys;
 }
@@ -186,7 +199,18 @@ function summarizeInspectableValue(value) {
   }
   return value;
 }
-if (process.argv[1]?.includes("cli.")) {
+function maskRedisUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.password) {
+      parsed.password = "***";
+    }
+    return parsed.toString();
+  } catch {
+    return url.replace(/:([^@/]+)@/, ":***@");
+  }
+}
+if (process.argv[1]?.endsWith("cli.cjs") || process.argv[1]?.endsWith("cli.js")) {
   void main();
 }
 export {

package/dist/{edge-BMmPVqaD.d.cts → edge-BXWTKlI1.d.cts}

@@ -352,6 +352,21 @@ interface CacheStackEvents {
     warm: {
         key: string;
     };
+    /** Fired immediately before a high-level cache operation begins. */
+    'operation-start': {
+        id: number;
+        name: string;
+        attributes?: Record<string, unknown>;
+    };
+    /** Fired after a high-level cache operation finishes. */
+    'operation-end': {
+        id: number;
+        name: string;
+        attributes?: Record<string, unknown>;
+        success: boolean;
+        result?: 'null';
+        error?: unknown;
+    };
     /** Fired when an error occurs (layer failure, circuit breaker, etc.). */
     error: {
         operation: string;
@@ -537,11 +552,16 @@ declare class CacheStack extends EventEmitter {
     private readonly keyDiscovery;
     private readonly fetchRateLimiter;
     private readonly snapshotSerializer;
+    private readonly invalidation;
+    private readonly layerWriter;
+    private readonly snapshots;
     private readonly backgroundRefreshes;
+    private readonly backgroundRefreshAbort;
     private readonly layerDegradedUntil;
     private readonly maintenance;
     private readonly ttlResolver;
     private readonly circuitBreakerManager;
+    private nextOperationId;
     private currentGeneration?;
     private isDisconnecting;
     private disconnectPromise?;
@@ -638,8 +658,6 @@ declare class CacheStack extends EventEmitter {
     private readFromLayers;
     private readLayerEntry;
     private backfill;
-    private writeAcrossLayers;
-    private executeLayerOperations;
     private resolveFreshTtl;
     private resolveLayerSeconds;
     private shouldNegativeCache;
@@ -654,6 +672,7 @@ declare class CacheStack extends EventEmitter {
     private sleep;
     private withTimeout;
     private shouldBroadcastL1Invalidation;
+    private observeOperation;
     private scheduleGenerationCleanup;
     private cleanupGeneration;
     private initializeWriteBehind;
@@ -661,12 +680,9 @@ declare class CacheStack extends EventEmitter {
     private enqueueWriteBehind;
     private flushWriteBehindQueue;
     private runWriteBehindBatch;
-    private buildLayerSetEntry;
-    private intersectKeys;
     private qualifyKey;
     private qualifyPattern;
     private stripQualifiedKey;
-    private deleteKeysFromLayers;
     private validateConfiguration;
     private validateWriteOptions;
     private assertActive;
@@ -679,14 +695,9 @@ declare class CacheStack extends EventEmitter {
     private recordCircuitFailure;
     private isNegativeStoredValue;
     private emitError;
-    private isCacheSnapshotEntries;
-    private sanitizeSnapshotValue;
     private snapshotMaxBytes;
     private snapshotMaxEntries;
     private invalidationMaxKeys;
-    private collectKeysForTag;
-    private assertWithinInvalidationKeyLimit;
-    private visitExportEntries;
 }
 
 interface HonoLikeRequest {

package/dist/{edge-BMmPVqaD.d.ts → edge-BXWTKlI1.d.ts}

@@ -352,6 +352,21 @@ interface CacheStackEvents {
     warm: {
         key: string;
     };
+    /** Fired immediately before a high-level cache operation begins. */
+    'operation-start': {
+        id: number;
+        name: string;
+        attributes?: Record<string, unknown>;
+    };
+    /** Fired after a high-level cache operation finishes. */
+    'operation-end': {
+        id: number;
+        name: string;
+        attributes?: Record<string, unknown>;
+        success: boolean;
+        result?: 'null';
+        error?: unknown;
+    };
     /** Fired when an error occurs (layer failure, circuit breaker, etc.). */
     error: {
         operation: string;
@@ -537,11 +552,16 @@ declare class CacheStack extends EventEmitter {
     private readonly keyDiscovery;
     private readonly fetchRateLimiter;
     private readonly snapshotSerializer;
+    private readonly invalidation;
+    private readonly layerWriter;
+    private readonly snapshots;
     private readonly backgroundRefreshes;
+    private readonly backgroundRefreshAbort;
     private readonly layerDegradedUntil;
     private readonly maintenance;
     private readonly ttlResolver;
     private readonly circuitBreakerManager;
+    private nextOperationId;
     private currentGeneration?;
     private isDisconnecting;
     private disconnectPromise?;
@@ -638,8 +658,6 @@ declare class CacheStack extends EventEmitter {
     private readFromLayers;
     private readLayerEntry;
     private backfill;
-    private writeAcrossLayers;
-    private executeLayerOperations;
     private resolveFreshTtl;
     private resolveLayerSeconds;
     private shouldNegativeCache;
@@ -654,6 +672,7 @@ declare class CacheStack extends EventEmitter {
     private sleep;
     private withTimeout;
     private shouldBroadcastL1Invalidation;
+    private observeOperation;
     private scheduleGenerationCleanup;
     private cleanupGeneration;
     private initializeWriteBehind;
@@ -661,12 +680,9 @@ declare class CacheStack extends EventEmitter {
     private enqueueWriteBehind;
     private flushWriteBehindQueue;
     private runWriteBehindBatch;
-    private buildLayerSetEntry;
-    private intersectKeys;
     private qualifyKey;
     private qualifyPattern;
     private stripQualifiedKey;
-    private deleteKeysFromLayers;
     private validateConfiguration;
     private validateWriteOptions;
     private assertActive;
@@ -679,14 +695,9 @@ declare class CacheStack extends EventEmitter {
     private recordCircuitFailure;
     private isNegativeStoredValue;
     private emitError;
-    private isCacheSnapshotEntries;
-    private sanitizeSnapshotValue;
     private snapshotMaxBytes;
     private snapshotMaxEntries;
     private invalidationMaxKeys;
-    private collectKeysForTag;
-    private assertWithinInvalidationKeyLimit;
-    private visitExportEntries;
 }
 
 interface HonoLikeRequest {

package/dist/edge.d.cts

@@ -1,2 +1,2 @@
-export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-BMmPVqaD.cjs';
+export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-BXWTKlI1.cjs';
 import 'node:events';

package/dist/edge.d.ts

@@ -1,2 +1,2 @@
-export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-BMmPVqaD.js';
+export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-BXWTKlI1.js';
 import 'node:events';