layercache 1.2.6 → 1.2.8

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-328_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-397_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=20260409" 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 ?? "*");
@@ -528,6 +528,17 @@ function summarizeInspectableValue(value) {
   }
   return value;
 }
+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]?.includes("cli.")) {
   void main();
 }

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 ?? "*");
@@ -186,6 +186,17 @@ function summarizeInspectableValue(value) {
   }
   return value;
 }
+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]?.includes("cli.")) {
   void main();
 }

package/dist/{edge-DLstcDMn.d.cts → edge-DBs8Ko5W.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,17 +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 layerDegradedUntil;
-    private readonly keyEpochs;
+    private readonly maintenance;
     private readonly ttlResolver;
     private readonly circuitBreakerManager;
+    private nextOperationId;
     private currentGeneration?;
-    private readonly writeBehindQueue;
-    private writeBehindTimer?;
-    private writeBehindFlushPromise?;
-    private generationCleanupPromise?;
-    private clearEpoch;
     private isDisconnecting;
     private disconnectPromise?;
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
@@ -643,8 +657,6 @@ declare class CacheStack extends EventEmitter {
     private readFromLayers;
     private readLayerEntry;
     private backfill;
-    private writeAcrossLayers;
-    private executeLayerOperations;
     private resolveFreshTtl;
     private resolveLayerSeconds;
     private shouldNegativeCache;
@@ -659,25 +671,17 @@ declare class CacheStack extends EventEmitter {
     private sleep;
     private withTimeout;
     private shouldBroadcastL1Invalidation;
-    private shouldCleanupGenerations;
-    private generationCleanupBatchSize;
+    private observeOperation;
     private scheduleGenerationCleanup;
     private cleanupGeneration;
     private initializeWriteBehind;
     private shouldWriteBehind;
-    private beginClearEpoch;
-    private currentKeyEpoch;
-    private bumpKeyEpochs;
-    private isWriteOutdated;
     private enqueueWriteBehind;
     private flushWriteBehindQueue;
-    private buildLayerSetEntry;
-    private intersectKeys;
+    private runWriteBehindBatch;
     private qualifyKey;
     private qualifyPattern;
     private stripQualifiedKey;
-    private generationPrefix;
-    private deleteKeysFromLayers;
     private validateConfiguration;
     private validateWriteOptions;
     private assertActive;
@@ -690,14 +694,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-DLstcDMn.d.ts → edge-DBs8Ko5W.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,17 +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 layerDegradedUntil;
-    private readonly keyEpochs;
+    private readonly maintenance;
     private readonly ttlResolver;
     private readonly circuitBreakerManager;
+    private nextOperationId;
     private currentGeneration?;
-    private readonly writeBehindQueue;
-    private writeBehindTimer?;
-    private writeBehindFlushPromise?;
-    private generationCleanupPromise?;
-    private clearEpoch;
     private isDisconnecting;
     private disconnectPromise?;
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
@@ -643,8 +657,6 @@ declare class CacheStack extends EventEmitter {
     private readFromLayers;
     private readLayerEntry;
     private backfill;
-    private writeAcrossLayers;
-    private executeLayerOperations;
     private resolveFreshTtl;
     private resolveLayerSeconds;
     private shouldNegativeCache;
@@ -659,25 +671,17 @@ declare class CacheStack extends EventEmitter {
     private sleep;
     private withTimeout;
     private shouldBroadcastL1Invalidation;
-    private shouldCleanupGenerations;
-    private generationCleanupBatchSize;
+    private observeOperation;
     private scheduleGenerationCleanup;
     private cleanupGeneration;
     private initializeWriteBehind;
     private shouldWriteBehind;
-    private beginClearEpoch;
-    private currentKeyEpoch;
-    private bumpKeyEpochs;
-    private isWriteOutdated;
     private enqueueWriteBehind;
     private flushWriteBehindQueue;
-    private buildLayerSetEntry;
-    private intersectKeys;
+    private runWriteBehindBatch;
     private qualifyKey;
     private qualifyPattern;
     private stripQualifiedKey;
-    private generationPrefix;
-    private deleteKeysFromLayers;
     private validateConfiguration;
     private validateWriteOptions;
     private assertActive;
@@ -690,14 +694,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-DLstcDMn.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-DBs8Ko5W.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-DLstcDMn.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-DBs8Ko5W.js';
 import 'node:events';