@logtape/logtape 1.2.0-dev.343 → 1.2.0-dev.347

package/src/sink.test.ts

@@ -2207,3 +2207,384 @@ test("fingersCrossed() - context isolation after trigger", () => {
   assertEquals(buffer[2], req2Debug);
   assertEquals(buffer[3], req2Error);
 });
+
+test("fingersCrossed() - TTL-based buffer cleanup", async () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    isolateByContext: {
+      keys: ["requestId"],
+      bufferTtlMs: 100, // 100ms TTL
+      cleanupIntervalMs: 50, // cleanup every 50ms
+    },
+  }) as Sink & Disposable;
+
+  try {
+    // Create records with different request IDs
+    const req1Record: LogRecord = {
+      ...debug,
+      properties: { requestId: "req-1" },
+      timestamp: Date.now(),
+    };
+    const req2Record: LogRecord = {
+      ...debug,
+      properties: { requestId: "req-2" },
+      timestamp: Date.now(),
+    };
+
+    // Add records to buffers
+    sink(req1Record);
+    sink(req2Record);
+
+    // Wait for TTL to expire and cleanup to run
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    // Add a new record after TTL expiry
+    const req3Record: LogRecord = {
+      ...debug,
+      properties: { requestId: "req-3" },
+      timestamp: Date.now(),
+    };
+    sink(req3Record);
+
+    // Trigger an error for req-1 (should not flush expired req-1 buffer)
+    const req1Error: LogRecord = {
+      ...error,
+      properties: { requestId: "req-1" },
+      timestamp: Date.now(),
+    };
+    sink(req1Error);
+
+    // Should only have req-1 error (req-1 debug was cleaned up by TTL)
+    assertEquals(buffer.length, 1);
+    assertEquals(buffer[0], req1Error);
+
+    // Trigger an error for req-3 (should flush req-3 buffer)
+    buffer.length = 0; // Clear buffer
+    const req3Error: LogRecord = {
+      ...error,
+      properties: { requestId: "req-3" },
+      timestamp: Date.now(),
+    };
+    sink(req3Error);
+
+    // Should have both req-3 debug and error
+    assertEquals(buffer.length, 2);
+    assertEquals(buffer[0], req3Record);
+    assertEquals(buffer[1], req3Error);
+  } finally {
+    // Clean up timer
+    sink[Symbol.dispose]();
+  }
+});
+
+test("fingersCrossed() - TTL disabled when bufferTtlMs is zero", () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    isolateByContext: {
+      keys: ["requestId"],
+      bufferTtlMs: 0, // TTL disabled
+    },
+  });
+
+  // Should return a regular sink without disposal functionality
+  assertEquals("dispose" in sink, false);
+
+  // Add a record
+  const record: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-1" },
+  };
+  sink(record);
+
+  // Trigger should work normally
+  const errorRecord: LogRecord = {
+    ...error,
+    properties: { requestId: "req-1" },
+  };
+  sink(errorRecord);
+
+  assertEquals(buffer.length, 2);
+  assertEquals(buffer[0], record);
+  assertEquals(buffer[1], errorRecord);
+});
+
+test("fingersCrossed() - TTL disabled when bufferTtlMs is undefined", () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    isolateByContext: {
+      keys: ["requestId"],
+      // bufferTtlMs not specified
+    },
+  });
+
+  // Should return a regular sink without disposal functionality
+  assertEquals("dispose" in sink, false);
+});
+
+test("fingersCrossed() - LRU-based buffer eviction", () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    isolateByContext: {
+      keys: ["requestId"],
+      maxContexts: 2, // Only keep 2 context buffers
+    },
+  });
+
+  // Step 1: Add req-1
+  const req1Record: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-1" },
+  };
+  sink(req1Record);
+
+  // Step 2: Add req-2
+  const req2Record: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-2" },
+  };
+  sink(req2Record);
+
+  // Step 3: Add req-3 (should evict req-1)
+  const req3Record: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-3" },
+  };
+  sink(req3Record);
+
+  // Test req-1 was evicted by triggering error
+  const req1Error: LogRecord = {
+    ...error,
+    properties: { requestId: "req-1" },
+  };
+  sink(req1Error);
+
+  // If req-1 was evicted, should only have error (length=1)
+  // If req-1 wasn't evicted, should have debug+error (length=2)
+  assertEquals(buffer.length, 1, "req-1 should have been evicted by LRU");
+  assertEquals(buffer[0], req1Error);
+});
+
+test("fingersCrossed() - LRU eviction order with access updates", async () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    isolateByContext: {
+      keys: ["requestId"],
+      maxContexts: 2,
+    },
+  });
+
+  // Add two contexts with time gap to ensure different timestamps
+  const req1Record: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-1" },
+  };
+  sink(req1Record); // req-1 is oldest
+
+  // Small delay to ensure different lastAccess times
+  await new Promise((resolve) => setTimeout(resolve, 1));
+
+  const req2Record: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-2" },
+  };
+  sink(req2Record); // req-2 is newest
+
+  // Access req-1 again after another delay to make it more recent
+  await new Promise((resolve) => setTimeout(resolve, 1));
+
+  const req1Second: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-1" },
+  };
+  sink(req1Second); // Now req-2 is oldest, req-1 is newest
+
+  // Add third context - should evict req-2 (now the oldest)
+  const req3Record: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-3" },
+  };
+  sink(req3Record);
+
+  // Verify req-2 was evicted
+  const req2Error: LogRecord = {
+    ...error,
+    properties: { requestId: "req-2" },
+  };
+  sink(req2Error);
+
+  // Should only have error record (no buffered records)
+  assertEquals(buffer.length, 1, "req-2 should have been evicted");
+  assertEquals(buffer[0], req2Error);
+});
+
+test("fingersCrossed() - LRU disabled when maxContexts is zero", () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    isolateByContext: {
+      keys: ["requestId"],
+      maxContexts: 0, // LRU disabled
+    },
+  });
+
+  // Create many contexts - should not be limited
+  for (let i = 0; i < 100; i++) {
+    const record: LogRecord = {
+      ...debug,
+      properties: { requestId: `req-${i}` },
+    };
+    sink(record);
+  }
+
+  // Trigger the last context
+  const errorRecord: LogRecord = {
+    ...error,
+    properties: { requestId: "req-99" },
+  };
+  sink(errorRecord);
+
+  // Should have both debug and error records
+  assertEquals(buffer.length, 2);
+  assertEquals(buffer[0].properties?.requestId, "req-99");
+  assertEquals(buffer[1], errorRecord);
+});
+
+test("fingersCrossed() - LRU disabled when maxContexts is undefined", () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    isolateByContext: {
+      keys: ["requestId"],
+      // maxContexts not specified
+    },
+  });
+
+  // Should work normally without LRU limits
+  const record: LogRecord = {
+    ...debug,
+    properties: { requestId: "req-1" },
+  };
+  sink(record);
+
+  const errorRecord: LogRecord = {
+    ...error,
+    properties: { requestId: "req-1" },
+  };
+  sink(errorRecord);
+
+  assertEquals(buffer.length, 2);
+  assertEquals(buffer[0], record);
+  assertEquals(buffer[1], errorRecord);
+});
+
+test("fingersCrossed() - Combined TTL and LRU functionality", async () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    isolateByContext: {
+      keys: ["requestId"],
+      maxContexts: 2, // LRU limit
+      bufferTtlMs: 100, // TTL limit
+      cleanupIntervalMs: 50, // cleanup interval
+    },
+  }) as Sink & Disposable;
+
+  try {
+    // Create records for multiple contexts
+    const req1Record: LogRecord = {
+      ...debug,
+      properties: { requestId: "req-1" },
+      timestamp: Date.now(),
+    };
+    const req2Record: LogRecord = {
+      ...debug,
+      properties: { requestId: "req-2" },
+      timestamp: Date.now(),
+    };
+
+    // Add two contexts (within LRU limit)
+    sink(req1Record);
+    sink(req2Record);
+
+    // Wait for TTL to expire
+    await new Promise((resolve) => setTimeout(resolve, 150));
+
+    // Add a third context (should work because TTL cleaned up old ones)
+    const req3Record: LogRecord = {
+      ...debug,
+      properties: { requestId: "req-3" },
+      timestamp: Date.now(),
+    };
+    sink(req3Record);
+
+    // Trigger req-1 (should not find buffered records due to TTL expiry)
+    const req1Error: LogRecord = {
+      ...error,
+      properties: { requestId: "req-1" },
+      timestamp: Date.now(),
+    };
+    sink(req1Error);
+
+    // Should only have the error record
+    assertEquals(buffer.length, 1);
+    assertEquals(buffer[0], req1Error);
+
+    // Clear buffer and trigger req-3 (should have recent record)
+    buffer.length = 0;
+    const req3Error: LogRecord = {
+      ...error,
+      properties: { requestId: "req-3" },
+      timestamp: Date.now(),
+    };
+    sink(req3Error);
+
+    // Should have both debug and error records
+    assertEquals(buffer.length, 2);
+    assertEquals(buffer[0], req3Record);
+    assertEquals(buffer[1], req3Error);
+  } finally {
+    sink[Symbol.dispose]();
+  }
+});
+
+test("fingersCrossed() - LRU priority over TTL for active contexts", () => {
+  const buffer: LogRecord[] = [];
+  const sink = fingersCrossed(buffer.push.bind(buffer), {
+    isolateByContext: {
+      keys: ["requestId"],
+      maxContexts: 2,
+      bufferTtlMs: 10000, // Long TTL (10 seconds)
+    },
+  }) as Sink & Disposable;
+
+  try {
+    // Create 3 contexts quickly (before TTL expires)
+    const req1Record: LogRecord = {
+      ...debug,
+      properties: { requestId: "req-1" },
+    };
+    const req2Record: LogRecord = {
+      ...debug,
+      properties: { requestId: "req-2" },
+    };
+    const req3Record: LogRecord = {
+      ...debug,
+      properties: { requestId: "req-3" },
+    };
+
+    sink(req1Record); // LRU position: oldest
+    sink(req2Record); // LRU position: middle
+    sink(req3Record); // LRU position: newest, should evict req-1 due to LRU
+
+    // Now trigger req-2 (should have buffered record)
+    const req2Error: LogRecord = {
+      ...error,
+      properties: { requestId: "req-2" },
+    };
+    sink(req2Error);
+
+    // Should have both debug and error records
+    assertEquals(buffer.length, 2);
+    assertEquals(buffer[0], req2Record);
+    assertEquals(buffer[1], req2Error);
+  } finally {
+    sink[Symbol.dispose]();
+  }
+});

package/src/sink.ts

@@ -513,6 +513,17 @@ export interface FingersCrossedOptions {
    * })
    * ```
    *
+   * @example With TTL-based buffer cleanup
+   * ```typescript
+   * fingersCrossed(sink, {
+   *   isolateByContext: {
+   *     keys: ['requestId'],
+   *     bufferTtlMs: 30000,        // 30 seconds
+   *     cleanupIntervalMs: 10000   // cleanup every 10 seconds
+   *   }
+   * })
+   * ```
+   *
    * @default `undefined` (no context isolation)
    * @since 1.2.0
    */
@@ -522,9 +533,65 @@ export interface FingersCrossedOptions {
      * Buffers will be separate for different combinations of these context values.
      */
     readonly keys: readonly string[];
+
+    /**
+     * Maximum number of context buffers to maintain simultaneously.
+     * When this limit is exceeded, the least recently used (LRU) buffers
+     * will be evicted to make room for new ones.
+     *
+     * This provides memory protection in high-concurrency scenarios where
+     * many different context values might be active simultaneously.
+     *
+     * When set to 0 or undefined, no limit is enforced.
+     *
+     * @default `undefined` (no limit)
+     * @since 1.2.0
+     */
+    readonly maxContexts?: number;
+
+    /**
+     * Time-to-live for context buffers in milliseconds.
+     * Buffers that haven't been accessed for this duration will be automatically
+     * cleaned up to prevent memory leaks in long-running applications.
+     *
+     * When set to 0 or undefined, buffers will never expire based on time.
+     *
+     * @default `undefined` (no TTL)
+     * @since 1.2.0
+     */
+    readonly bufferTtlMs?: number;
+
+    /**
+     * Interval in milliseconds for running cleanup operations.
+     * The cleanup process removes expired buffers based on {@link bufferTtlMs}.
+     *
+     * This option is ignored if {@link bufferTtlMs} is not set.
+     *
+     * @default `30000` (30 seconds)
+     * @since 1.2.0
+     */
+    readonly cleanupIntervalMs?: number;
   };
 }
 
+/**
+ * Metadata for context-based buffer tracking.
+ * Used internally by {@link fingersCrossed} to manage buffer lifecycle with LRU support.
+ * @since 1.2.0
+ */
+interface BufferMetadata {
+  /**
+   * The actual log records buffer.
+   */
+  readonly buffer: LogRecord[];
+
+  /**
+   * Timestamp of the last access to this buffer (in milliseconds).
+   * Used for LRU-based eviction when {@link FingersCrossedOptions.isolateByContext.maxContexts} is set.
+   */
+  lastAccess: number;
+}
+
 /**
  * Creates a sink that buffers log records until a trigger level is reached.
  * This pattern, known as "fingers crossed" logging, keeps detailed debug logs
@@ -563,12 +630,19 @@ export interface FingersCrossedOptions {
 export function fingersCrossed(
   sink: Sink,
   options: FingersCrossedOptions = {},
-): Sink {
+): Sink | (Sink & Disposable) {
   const triggerLevel = options.triggerLevel ?? "error";
   const maxBufferSize = Math.max(0, options.maxBufferSize ?? 1000);
   const isolateByCategory = options.isolateByCategory;
   const isolateByContext = options.isolateByContext;
 
+  // TTL and LRU configuration
+  const bufferTtlMs = isolateByContext?.bufferTtlMs;
+  const cleanupIntervalMs = isolateByContext?.cleanupIntervalMs ?? 30000;
+  const maxContexts = isolateByContext?.maxContexts;
+  const hasTtl = bufferTtlMs != null && bufferTtlMs > 0;
+  const hasLru = maxContexts != null && maxContexts > 0;
+
   // Validate trigger level early
   try {
     compareLogLevel("trace", triggerLevel); // Test with any valid level
@@ -685,6 +759,52 @@ export function fingersCrossed(
     return { category: parseCategoryKey(categoryPart), context: contextPart };
   }
 
+  // TTL-based cleanup function
+  function cleanupExpiredBuffers(buffers: Map<string, BufferMetadata>): void {
+    if (!hasTtl) return;
+
+    const now = Date.now();
+    const expiredKeys: string[] = [];
+
+    for (const [key, metadata] of buffers) {
+      if (metadata.buffer.length === 0) continue;
+
+      // Use the timestamp of the last (most recent) record in the buffer
+      const lastRecordTimestamp =
+        metadata.buffer[metadata.buffer.length - 1].timestamp;
+      if (now - lastRecordTimestamp > bufferTtlMs!) {
+        expiredKeys.push(key);
+      }
+    }
+
+    // Remove expired buffers
+    for (const key of expiredKeys) {
+      buffers.delete(key);
+    }
+  }
+
+  // LRU-based eviction function
+  function evictLruBuffers(
+    buffers: Map<string, BufferMetadata>,
+    numToEvict?: number,
+  ): void {
+    if (!hasLru) return;
+
+    // Use provided numToEvict or calculate based on current size vs limit
+    const toEvict = numToEvict ?? Math.max(0, buffers.size - maxContexts!);
+    if (toEvict <= 0) return;
+
+    // Sort by lastAccess timestamp (oldest first)
+    const sortedEntries = Array.from(buffers.entries())
+      .sort(([, a], [, b]) => a.lastAccess - b.lastAccess);
+
+    // Remove the oldest buffers
+    for (let i = 0; i < toEvict; i++) {
+      const [key] = sortedEntries[i];
+      buffers.delete(key);
+    }
+  }
+
   // Buffer management
   if (!isolateByCategory && !isolateByContext) {
     // Single global buffer
@@ -722,10 +842,18 @@ export function fingersCrossed(
     };
   } else {
     // Category and/or context-isolated buffers
-    const buffers = new Map<string, LogRecord[]>();
+    const buffers = new Map<string, BufferMetadata>();
     const triggered = new Set<string>();
 
-    return (record: LogRecord) => {
+    // Set up TTL cleanup timer if enabled
+    let cleanupTimer: ReturnType<typeof setInterval> | null = null;
+    if (hasTtl) {
+      cleanupTimer = setInterval(() => {
+        cleanupExpiredBuffers(buffers);
+      }, cleanupIntervalMs);
+    }
+
+    const fingersCrossedSink = (record: LogRecord) => {
       const bufferKey = getBufferKey(record.category, record.properties);
 
       // Check if this buffer is already triggered
@@ -783,9 +911,9 @@ export function fingersCrossed(
         // Flush matching buffers
         const allRecordsToFlush: LogRecord[] = [];
         for (const key of keysToFlush) {
-          const buffer = buffers.get(key);
-          if (buffer) {
-            allRecordsToFlush.push(...buffer);
+          const metadata = buffers.get(key);
+          if (metadata) {
+            allRecordsToFlush.push(...metadata.buffer);
             buffers.delete(key);
             triggered.add(key);
           }
@@ -804,19 +932,45 @@ export function fingersCrossed(
         sink(record);
       } else {
         // Buffer the record
-        let buffer = buffers.get(bufferKey);
-        if (!buffer) {
-          buffer = [];
-          buffers.set(bufferKey, buffer);
+        const now = Date.now();
+        let metadata = buffers.get(bufferKey);
+        if (!metadata) {
+          // Apply LRU eviction if adding new buffer would exceed capacity
+          if (hasLru && buffers.size >= maxContexts!) {
+            // Calculate how many buffers to evict to make room for the new one
+            const numToEvict = buffers.size - maxContexts! + 1;
+            evictLruBuffers(buffers, numToEvict);
+          }
+
+          metadata = {
+            buffer: [],
+            lastAccess: now,
+          };
+          buffers.set(bufferKey, metadata);
+        } else {
+          // Update last access time for LRU
+          metadata.lastAccess = now;
         }
 
-        buffer.push(record);
+        metadata.buffer.push(record);
 
         // Enforce max buffer size per buffer
-        while (buffer.length > maxBufferSize) {
-          buffer.shift();
+        while (metadata.buffer.length > maxBufferSize) {
+          metadata.buffer.shift();
         }
       }
     };
+
+    // Add disposal functionality to clean up timer
+    if (cleanupTimer !== null) {
+      (fingersCrossedSink as Sink & Disposable)[Symbol.dispose] = () => {
+        if (cleanupTimer !== null) {
+          clearInterval(cleanupTimer);
+          cleanupTimer = null;
+        }
+      };
+    }
+
+    return fingersCrossedSink;
   }
 }