layercache 1.2.8 → 1.3.0

package/benchmarks/slow-redis-latency.ts

@@ -0,0 +1,309 @@
+import { Redis } from 'ioredis'
+import { CacheStack, MemoryLayer, RedisLayer, RedisSingleFlightCoordinator } from '../src'
+import {
+  REDIS_PORT,
+  ensureRedisContainer,
+  pauseRedisContainer,
+  stopRedisContainer,
+  unpauseRedisContainer,
+  waitForRedisReady
+} from './redis'
+import { startRedisLatencyProxy } from './redis-latency-proxy'
+import { buildDelayLabel } from './slow-redis-utils'
+
+const LATENCY_LEVELS = [0, 100, 500] as const
+const TIMEOUT_MS = 6_000
+const COMMAND_TIMEOUT_MS = 200
+
+interface SlowRedisResult {
+  delayLabel: string
+  scenario: string
+  success: boolean
+  latencyMs: number
+  error: string | null
+}
+
+interface LayeredCacheContext {
+  cache: CacheStack
+  memory: MemoryLayer
+}
+
+function round(value: number): number {
+  return Number(value.toFixed(3))
+}
+
+function normalizeResult(
+  delayLabel: string,
+  scenario: string,
+  success: boolean,
+  latencyMs: number,
+  error?: string
+): SlowRedisResult {
+  return {
+    delayLabel,
+    scenario,
+    success,
+    latencyMs: round(latencyMs),
+    error: error ?? null
+  }
+}
+
+function createBenchmarkRedis(port: number): Redis {
+  const client = new Redis({
+    host: '127.0.0.1',
+    port,
+    lazyConnect: true,
+    maxRetriesPerRequest: 1,
+    connectTimeout: 6_000,
+    enableOfflineQueue: false,
+    autoResendUnfulfilledCommands: false,
+    retryStrategy: () => null
+  })
+
+  client.on('error', () => {})
+  return client
+}
+
+async function measure<TResult>(task: () => Promise<TResult>): Promise<{ durationMs: number; result: TResult }> {
+  const startedAt = process.hrtime.bigint()
+  const result = await task()
+
+  return {
+    durationMs: Number(process.hrtime.bigint() - startedAt) / 1_000_000,
+    result
+  }
+}
+
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<T>((_, reject) => {
+      setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs)
+    })
+  ])
+}
+
+function createLayeredCache(redis: Redis, prefix: string, gracefulDegradation: boolean): LayeredCacheContext {
+  const memory = new MemoryLayer({ ttl: 60, maxSize: 50 })
+  const cache = new CacheStack(
+    [
+      memory,
+      new RedisLayer({
+        client: redis,
+        ttl: 300,
+        prefix: `${prefix}:cache:`,
+        commandTimeoutMs: COMMAND_TIMEOUT_MS
+      })
+    ],
+    {
+      stampedePrevention: true,
+      ...(gracefulDegradation ? { gracefulDegradation: { retryAfterMs: 10_000 } } : {}),
+      singleFlightCoordinator: new RedisSingleFlightCoordinator({
+        client: redis,
+        prefix: `${prefix}:sf:`,
+        commandTimeoutMs: COMMAND_TIMEOUT_MS
+      })
+    }
+  )
+
+  return {
+    cache,
+    memory
+  }
+}
+
+async function runSlowRedisAtDelay(delayMs: number): Promise<SlowRedisResult[]> {
+  const delayLabel = buildDelayLabel(delayMs)
+  const proxy = await startRedisLatencyProxy(REDIS_PORT)
+
+  const strictRedis = createBenchmarkRedis(proxy.port)
+  const gracefulRedis = createBenchmarkRedis(proxy.port)
+
+  await Promise.all([strictRedis.connect(), gracefulRedis.connect()])
+  await Promise.all([strictRedis.ping(), gracefulRedis.ping()])
+
+  const strict = createLayeredCache(strictRedis, `slow:strict:${delayMs}:${Date.now()}`, false)
+  const graceful = createLayeredCache(gracefulRedis, `slow:graceful:${delayMs}:${Date.now()}`, true)
+
+  try {
+    await strict.cache.get('warm:key', async () => ({ source: 'origin', delayMs }), { ttl: 60 })
+    await graceful.cache.get('warm:key', async () => ({ source: 'origin', delayMs }), { ttl: 60 })
+    proxy.setLatencyMs(delayMs)
+
+    const hotStrict = await measure(() =>
+      withTimeout(strict.cache.get('warm:key'), TIMEOUT_MS, `${delayLabel} strict hot`)
+    )
+      .then(({ durationMs }) => normalizeResult(delayLabel, 'strict-hot-hit', true, durationMs))
+      .catch((error) =>
+        normalizeResult(delayLabel, 'strict-hot-hit', false, 0, error instanceof Error ? error.message : String(error))
+      )
+
+    const hotGraceful = await measure(() =>
+      withTimeout(graceful.cache.get('warm:key'), TIMEOUT_MS, `${delayLabel} graceful hot`)
+    )
+      .then(({ durationMs }) => normalizeResult(delayLabel, 'graceful-hot-hit', true, durationMs))
+      .catch((error) =>
+        normalizeResult(
+          delayLabel,
+          'graceful-hot-hit',
+          false,
+          0,
+          error instanceof Error ? error.message : String(error)
+        )
+      )
+
+    await Promise.all([strict.memory.clear().catch(() => undefined), graceful.memory.clear().catch(() => undefined)])
+
+    const l2Strict = await measure(() =>
+      withTimeout(strict.cache.get('warm:key'), TIMEOUT_MS, `${delayLabel} strict l2`)
+    )
+      .then(({ durationMs }) => normalizeResult(delayLabel, 'strict-l2-hit', true, durationMs))
+      .catch((error) =>
+        normalizeResult(delayLabel, 'strict-l2-hit', false, 0, error instanceof Error ? error.message : String(error))
+      )
+
+    const l2Graceful = await measure(() =>
+      withTimeout(graceful.cache.get('warm:key'), TIMEOUT_MS, `${delayLabel} graceful l2`)
+    )
+      .then(({ durationMs }) => normalizeResult(delayLabel, 'graceful-l2-hit', true, durationMs))
+      .catch((error) =>
+        normalizeResult(delayLabel, 'graceful-l2-hit', false, 0, error instanceof Error ? error.message : String(error))
+      )
+
+    const coldStrict = await measure(() =>
+      withTimeout(
+        strict.cache.get('cold:key', async () => ({ source: 'origin', delayMs }), { ttl: 60 }),
+        TIMEOUT_MS,
+        `${delayLabel} strict cold`
+      )
+    )
+      .then(({ durationMs }) => normalizeResult(delayLabel, 'strict-cold-miss', true, durationMs))
+      .catch((error) =>
+        normalizeResult(
+          delayLabel,
+          'strict-cold-miss',
+          false,
+          0,
+          error instanceof Error ? error.message : String(error)
+        )
+      )
+
+    const coldGraceful = await measure(() =>
+      withTimeout(
+        graceful.cache.get('cold:key', async () => ({ source: 'origin', delayMs }), { ttl: 60 }),
+        TIMEOUT_MS,
+        `${delayLabel} graceful cold`
+      )
+    )
+      .then(({ durationMs }) => normalizeResult(delayLabel, 'graceful-cold-miss', true, durationMs))
+      .catch((error) =>
+        normalizeResult(
+          delayLabel,
+          'graceful-cold-miss',
+          false,
+          0,
+          error instanceof Error ? error.message : String(error)
+        )
+      )
+
+    return [hotStrict, hotGraceful, l2Strict, l2Graceful, coldStrict, coldGraceful]
+  } finally {
+    await strict.cache.disconnect().catch(() => {})
+    await graceful.cache.disconnect().catch(() => {})
+    await strictRedis.quit().catch(() => {})
+    await gracefulRedis.quit().catch(() => {})
+    await proxy.close().catch(() => {})
+  }
+}
+
+async function runDeadRedisContrast(): Promise<SlowRedisResult[]> {
+  const strictRedis = createBenchmarkRedis(REDIS_PORT)
+  const gracefulRedis = createBenchmarkRedis(REDIS_PORT)
+
+  await Promise.all([strictRedis.connect(), gracefulRedis.connect()])
+  await Promise.all([strictRedis.ping(), gracefulRedis.ping()])
+
+  const strict = createLayeredCache(strictRedis, `dead:strict:${Date.now()}`, false)
+  const graceful = createLayeredCache(gracefulRedis, `dead:graceful:${Date.now()}`, true)
+
+  try {
+    await strict.cache.get('warm:key', async () => ({ source: 'origin' }), { ttl: 60 })
+    await graceful.cache.get('warm:key', async () => ({ source: 'origin' }), { ttl: 60 })
+
+    await pauseRedisContainer()
+
+    const strictCold = await measure(() =>
+      withTimeout(
+        strict.cache.get('cold:key', async () => ({ source: 'origin' }), { ttl: 60 }),
+        2_000,
+        'dead strict cold'
+      )
+    )
+      .then(({ durationMs }) => normalizeResult('dead', 'dead-strict-cold-miss', true, durationMs))
+      .catch((error) =>
+        normalizeResult(
+          'dead',
+          'dead-strict-cold-miss',
+          false,
+          0,
+          error instanceof Error ? error.message : String(error)
+        )
+      )
+
+    const gracefulCold = await measure(() =>
+      withTimeout(
+        graceful.cache.get('cold:key', async () => ({ source: 'origin' }), { ttl: 60 }),
+        2_000,
+        'dead graceful cold'
+      )
+    )
+      .then(({ durationMs }) => normalizeResult('dead', 'dead-graceful-cold-miss', true, durationMs))
+      .catch((error) =>
+        normalizeResult(
+          'dead',
+          'dead-graceful-cold-miss',
+          false,
+          0,
+          error instanceof Error ? error.message : String(error)
+        )
+      )
+
+    return [strictCold, gracefulCold]
+  } finally {
+    await unpauseRedisContainer().catch(() => {})
+    await waitForRedisReady()
+    await strict.cache.disconnect().catch(() => {})
+    await graceful.cache.disconnect().catch(() => {})
+    await strictRedis.quit().catch(() => {})
+    await gracefulRedis.quit().catch(() => {})
+  }
+}
+
+async function main(): Promise<void> {
+  await ensureRedisContainer()
+  await waitForRedisReady()
+
+  try {
+    const slowRedisResults: SlowRedisResult[] = []
+    for (const delayMs of LATENCY_LEVELS) {
+      slowRedisResults.push(...(await runSlowRedisAtDelay(delayMs)))
+    }
+
+    await stopRedisContainer()
+    await ensureRedisContainer()
+    await waitForRedisReady()
+
+    const deadRedisResults = await runDeadRedisContrast()
+
+    console.table(slowRedisResults.concat(deadRedisResults))
+    console.log(JSON.stringify({ type: 'slow-redis-latency', slowRedisResults, deadRedisResults }, null, 2))
+  } finally {
+    await unpauseRedisContainer().catch(() => {})
+    await stopRedisContainer()
+  }
+}
+
+void main().catch((error) => {
+  console.error(error)
+  process.exitCode = 1
+})

package/benchmarks/slow-redis-utils.ts

@@ -0,0 +1,29 @@
+export interface GcMetricsSummary {
+  gcCount: number
+  gcTotalMs: number
+  gcMaxMs: number
+}
+
+function round(value: number): number {
+  return Number(value.toFixed(3))
+}
+
+export function buildDelayLabel(delayMs: number): string {
+  return `${delayMs}ms`
+}
+
+export function summarizeGcMetrics(durationsMs: number[]): GcMetricsSummary {
+  if (durationsMs.length === 0) {
+    return {
+      gcCount: 0,
+      gcTotalMs: 0,
+      gcMaxMs: 0
+    }
+  }
+
+  return {
+    gcCount: durationsMs.length,
+    gcTotalMs: round(durationsMs.reduce((sum, duration) => sum + duration, 0)),
+    gcMaxMs: round(Math.max(...durationsMs))
+  }
+}

package/benchmarks/slow-redis.ts

@@ -0,0 +1,47 @@
+import { execFile } from 'node:child_process'
+import { join } from 'node:path'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+async function runTsx(scriptName: string): Promise<string> {
+  const tsxPath = join(process.cwd(), 'node_modules', '.bin', 'tsx')
+  const scriptPath = join(process.cwd(), 'benchmarks', scriptName)
+  const { stdout } = await execFileAsync(tsxPath, [scriptPath], {
+    cwd: process.cwd(),
+    maxBuffer: 50 * 1024 * 1024
+  })
+
+  return stdout.trim()
+}
+
+function extractJsonBlock(output: string): unknown {
+  const lines = output.trim().split('\n')
+  const startIndex = lines.findIndex((line) => line.startsWith('{'))
+  if (startIndex === -1) {
+    throw new Error('Benchmark output did not contain a JSON block')
+  }
+
+  return JSON.parse(lines.slice(startIndex).join('\n'))
+}
+
+async function main(): Promise<void> {
+  const slowRedisOutput = await runTsx('slow-redis-latency.ts')
+  process.stdout.write(`${slowRedisOutput}\n`)
+
+  const memoryPressureOutput = await runTsx('memory-pressure.ts')
+  process.stdout.write(`${memoryPressureOutput}\n`)
+
+  const combined = {
+    type: 'slow-redis-memory-pressure-benchmark',
+    slowRedis: extractJsonBlock(slowRedisOutput),
+    memoryPressure: extractJsonBlock(memoryPressureOutput)
+  }
+
+  console.log(JSON.stringify(combined, null, 2))
+}
+
+void main().catch((error) => {
+  console.error(error)
+  process.exitCode = 1
+})

package/benchmarks/stats.ts

@@ -0,0 +1,46 @@
+export interface DurationSummary {
+  label: string
+  count: number
+  minMs: number
+  maxMs: number
+  avgMs: number
+  medianMs: number
+  p95Ms: number
+}
+
+function round(value: number): number {
+  return Number(value.toFixed(3))
+}
+
+export function quantile(samples: number[], percentile: number): number {
+  if (samples.length === 0) {
+    throw new Error('quantile requires at least one sample')
+  }
+
+  const sorted = [...samples].sort((left, right) => left - right)
+  const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * percentile) - 1))
+  const value = sorted[index]
+  if (value === undefined) {
+    throw new Error('quantile computed an invalid index')
+  }
+
+  return value
+}
+
+export function summarizeDurations(label: string, samples: number[]): DurationSummary {
+  if (samples.length === 0) {
+    throw new Error('summarizeDurations requires at least one sample')
+  }
+
+  const total = samples.reduce((sum, sample) => sum + sample, 0)
+
+  return {
+    label,
+    count: samples.length,
+    minMs: round(Math.min(...samples)),
+    maxMs: round(Math.max(...samples)),
+    avgMs: round(total / samples.length),
+    medianMs: round(quantile(samples, 0.5)),
+    p95Ms: round(quantile(samples, 0.95))
+  }
+}

package/benchmarks/workload.ts

@@ -0,0 +1,77 @@
+import { createHash } from 'node:crypto'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+export interface UserRecord {
+  id: number
+  email: string
+  name: string
+  profile: {
+    plan: string
+    region: string
+    score: number
+  }
+  tags: string[]
+}
+
+const REGIONS = ['us-east', 'eu-west', 'ap-northeast', 'sa-east'] as const
+const PLANS = ['starter', 'growth', 'enterprise'] as const
+
+export function buildUserDataset(count: number): UserRecord[] {
+  return Array.from({ length: count }, (_, index) => {
+    const id = index + 1
+    const plan = PLANS[index % PLANS.length] ?? PLANS[0]
+    const region = REGIONS[index % REGIONS.length] ?? REGIONS[0]
+
+    return {
+      id,
+      email: `user${id}@example.com`,
+      name: `User ${id}`,
+      profile: {
+        plan,
+        region,
+        score: (id * 37) % 1000
+      },
+      tags: [`segment-${id % 10}`, `cohort-${id % 4}`]
+    }
+  })
+}
+
+export function findUserById(users: UserRecord[], id: number): UserRecord {
+  const user = users.find((entry) => entry.id === id)
+  if (!user) {
+    throw new Error(`User ${id} not found`)
+  }
+
+  return user
+}
+
+export async function ensureFixtureFile(filePath: string, count = 5000): Promise<void> {
+  try {
+    await readFile(filePath, 'utf8')
+    return
+  } catch (error) {
+    if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') {
+      throw error
+    }
+  }
+
+  await mkdir(dirname(filePath), { recursive: true })
+  await writeFile(filePath, JSON.stringify(buildUserDataset(count)), 'utf8')
+}
+
+export async function loadUserFromFixture(filePath: string, userId: number, hashRounds = 600): Promise<UserRecord> {
+  const raw = await readFile(filePath, 'utf8')
+  const users = JSON.parse(raw) as UserRecord[]
+  const user = findUserById(users, userId)
+
+  let digest = JSON.stringify(user)
+  for (let index = 0; index < hashRounds; index += 1) {
+    digest = createHash('sha256').update(digest).digest('hex')
+  }
+
+  return {
+    ...user,
+    tags: [...user.tags, digest.slice(0, 12)]
+  }
+}

package/dist/cli.cjs

@@ -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;
 }
@@ -539,7 +552,7 @@ function maskRedisUrl(url) {
     return url.replace(/:([^@/]+)@/, ":***@");
   }
 }
-if (process.argv[1]?.includes("cli.")) {
+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

@@ -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;
 }
@@ -197,7 +210,7 @@ function maskRedisUrl(url) {
     return url.replace(/:([^@/]+)@/, ":***@");
   }
 }
-if (process.argv[1]?.includes("cli.")) {
+if (process.argv[1]?.endsWith("cli.cjs") || process.argv[1]?.endsWith("cli.js")) {
   void main();
 }
 export {

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

@@ -556,6 +556,7 @@ declare class CacheStack extends EventEmitter {
     private readonly layerWriter;
     private readonly snapshots;
     private readonly backgroundRefreshes;
+    private readonly backgroundRefreshAbort;
     private readonly layerDegradedUntil;
     private readonly maintenance;
     private readonly ttlResolver;

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

@@ -556,6 +556,7 @@ declare class CacheStack extends EventEmitter {
     private readonly layerWriter;
     private readonly snapshots;
     private readonly backgroundRefreshes;
+    private readonly backgroundRefreshAbort;
     private readonly layerDegradedUntil;
     private readonly maintenance;
     private readonly ttlResolver;

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-DBs8Ko5W.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-DBs8Ko5W.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';