layercache 1.3.4 → 2.0.0

package/benchmarks/slow-redis-latency.ts

@@ -1,309 +0,0 @@
-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

@@ -1,29 +0,0 @@
-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

@@ -1,47 +0,0 @@
-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/stampede.ts

@@ -1,26 +0,0 @@
-import Redis from 'ioredis-mock'
-import { CacheStack, MemoryLayer, RedisLayer } from '../src'
-
-async function main(): Promise<void> {
-  const redis = new Redis()
-  const cache = new CacheStack([new MemoryLayer({ ttl: 60 }), new RedisLayer({ client: redis, ttl: 300 })])
-
-  let executions = 0
-
-  await Promise.all(
-    Array.from({ length: 100 }, () =>
-      cache.get('stampede:key', async () => {
-        executions += 1
-        await new Promise((resolve) => setTimeout(resolve, 10))
-        return { ok: true }
-      })
-    )
-  )
-
-  console.table({
-    concurrentRequests: 100,
-    fetcherExecutions: executions
-  })
-}
-
-void main()

package/benchmarks/stats.ts

@@ -1,46 +0,0 @@
-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

@@ -1,77 +0,0 @@
-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/examples/express-api/index.ts

@@ -1,31 +0,0 @@
-import express from 'express'
-import Redis from 'ioredis'
-import { CacheStack, MemoryLayer, RedisLayer } from '../../src'
-
-const redis = new Redis(process.env.REDIS_URL)
-const cache = new CacheStack([
-  new MemoryLayer({ ttl: 30, maxSize: 5_000 }),
-  new RedisLayer({ client: redis, ttl: 300 })
-])
-
-const app = express()
-
-app.get('/users/:id', async (req, res) => {
-  const user = await cache.get(
-    `user:${req.params.id}`,
-    async () => {
-      return {
-        id: Number(req.params.id),
-        name: `User ${req.params.id}`,
-        source: 'db'
-      }
-    },
-    {
-      tags: ['user', `user:${req.params.id}`]
-    }
-  )
-
-  res.json(user)
-})
-
-app.listen(3000)

package/examples/nextjs-api-routes/route.ts

@@ -1,16 +0,0 @@
-import Redis from 'ioredis'
-import { CacheStack, MemoryLayer, RedisLayer } from '../../src'
-
-const redis = new Redis(process.env.REDIS_URL)
-const cache = new CacheStack([new MemoryLayer({ ttl: 15 }), new RedisLayer({ client: redis, ttl: 120 })])
-
-export async function GET(_request: Request, context: { params: { id: string } }): Promise<Response> {
-  const data = await cache.get(`user:${context.params.id}`, async () => {
-    return {
-      id: Number(context.params.id),
-      cachedAt: new Date().toISOString()
-    }
-  })
-
-  return Response.json(data)
-}