layercache 1.3.3 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "layercache",
-  "version": "1.3.3",
+  "version": "1.4.0",
   "description": "Production-ready multi-layer caching for Node.js. Stack memory + Redis + disk behind one API with stampede prevention, tag invalidation, stale serving, and full observability.",
   "keywords": [
     "cache",
@@ -52,18 +52,18 @@
     }
   },
   "files": [
-    "dist",
-    "examples",
-    "benchmarks"
+    "dist"
   ],
   "engines": {
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/cli.ts src/edge.ts --format esm,cjs --dts",
+    "build": "tsup src/index.ts src/cli.ts src/edge.ts --format esm,cjs --dts --clean",
     "build:all": "npm run build",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "test:integration": "node ./scripts/run-integration-tests.mjs",
+    "test:all": "npm test && npm run test:integration",
     "test:watch": "vitest",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
@@ -93,7 +93,7 @@
     "@types/autocannon": "^7.12.7",
     "@types/node": "^22.15.2",
     "@vitest/coverage-v8": "^4.1.2",
-    "autocannon": "^8.0.0",
+    "autocannon": "^2.0.1",
     "ioredis": "^5.6.1",
     "ioredis-mock": "^8.13.0",
     "tsup": "^8.5.0",

package/benchmarks/direct.ts

@@ -1,221 +0,0 @@
-import { performance } from 'node:perf_hooks'
-import type { Redis } from 'ioredis'
-import { CacheStack, MemoryLayer, RedisLayer, RedisSingleFlightCoordinator } from '../src'
-import { resolveBenchmarkFixturePath } from './paths'
-import { createRedisClient, ensureRedisContainer, stopRedisContainer, waitForRedisReady } from './redis'
-import { type ScenarioSummary, createCountedFetcher, runConcurrent, summarizeScenario } from './scenario-utils'
-import { ensureFixtureFile, loadUserFromFixture } from './workload'
-
-const USER_ID = 4242
-const COLD_SAMPLES = 15
-const WARM_SAMPLES = 120
-const STAMPEDE_CONCURRENCY = 75
-const STAMPEDE_RUNS = 5
-
-type BenchmarkMode = 'no-cache' | 'memory' | 'layered'
-
-interface FlattenedResult extends ScenarioSummary {
-  mode: BenchmarkMode
-  scenario: string
-}
-
-type CacheRunner = {
-  read: <T>(key: string, fetcher: () => Promise<T>) => Promise<T>
-  clear: () => Promise<void>
-  disconnect?: () => Promise<void>
-}
-
-function createOriginFetcher(fixturePath: string) {
-  return createCountedFetcher(async (userId: number) => loadUserFromFixture(fixturePath, userId))
-}
-
-function createNoCacheRunner(): CacheRunner {
-  return {
-    read: async <T>(_key: string, fetcher: () => Promise<T>) => fetcher(),
-    clear: async () => {}
-  }
-}
-
-function createMemoryRunner(): CacheRunner {
-  const cache = new CacheStack([new MemoryLayer({ ttl: 60, maxSize: 2_000 })], {
-    stampedePrevention: true
-  })
-
-  return {
-    read: async <T>(key: string, fetcher: () => Promise<T>) => {
-      const value = await cache.get(key, fetcher)
-      if (value === null) {
-        throw new Error(`Cache unexpectedly returned null for ${key}`)
-      }
-
-      return value
-    },
-    clear: async () => {
-      await cache.clear()
-    },
-    disconnect: async () => {
-      await cache.disconnect()
-    }
-  }
-}
-
-function createLayeredRunner(redis: Redis): CacheRunner {
-  const cache = new CacheStack(
-    [
-      new MemoryLayer({ ttl: 60, maxSize: 2_000 }),
-      new RedisLayer({ client: redis, ttl: 300, prefix: 'layercache-bench:direct:' })
-    ],
-    {
-      stampedePrevention: true,
-      singleFlightCoordinator: new RedisSingleFlightCoordinator({
-        client: redis,
-        prefix: 'layercache-bench:direct:single-flight:'
-      })
-    }
-  )
-
-  return {
-    read: async <T>(key: string, fetcher: () => Promise<T>) => {
-      const value = await cache.get(key, fetcher)
-      if (value === null) {
-        throw new Error(`Cache unexpectedly returned null for ${key}`)
-      }
-
-      return value
-    },
-    clear: async () => {
-      await cache.clear()
-      await redis.flushdb()
-    },
-    disconnect: async () => {
-      await cache.disconnect()
-    }
-  }
-}
-
-async function measure<TResult>(task: () => Promise<TResult>): Promise<{ durationMs: number; result: TResult }> {
-  const startedAt = process.hrtime.bigint()
-  const result = await task()
-  const durationMs = Number(process.hrtime.bigint() - startedAt) / 1_000_000
-
-  return { durationMs, result }
-}
-
-async function runColdMiss(mode: BenchmarkMode, runner: CacheRunner, fixturePath: string): Promise<FlattenedResult> {
-  const samples: number[] = []
-  let fetchCount = 0
-
-  for (let index = 0; index < COLD_SAMPLES; index += 1) {
-    await runner.clear()
-    const origin = createOriginFetcher(fixturePath)
-    const { durationMs } = await measure(() => runner.read(`user:${USER_ID}`, () => origin.run(USER_ID)))
-    samples.push(durationMs)
-    fetchCount += origin.getCount()
-  }
-
-  return {
-    ...summarizeScenario('cold-miss', samples, fetchCount),
-    mode,
-    scenario: 'cold-miss'
-  }
-}
-
-async function runWarmHit(mode: BenchmarkMode, runner: CacheRunner, fixturePath: string): Promise<FlattenedResult> {
-  const samples: number[] = []
-  const warmOrigin = createOriginFetcher(fixturePath)
-
-  await runner.clear()
-  await runner.read(`user:${USER_ID}`, () => warmOrigin.run(USER_ID))
-
-  const measuredOrigin = createOriginFetcher(fixturePath)
-  for (let index = 0; index < WARM_SAMPLES; index += 1) {
-    const { durationMs } = await measure(() => runner.read(`user:${USER_ID}`, () => measuredOrigin.run(USER_ID)))
-    samples.push(durationMs)
-  }
-
-  return {
-    ...summarizeScenario('warm-hit', samples, measuredOrigin.getCount()),
-    mode,
-    scenario: 'warm-hit'
-  }
-}
-
-async function runStampede(mode: BenchmarkMode, runner: CacheRunner, fixturePath: string): Promise<FlattenedResult> {
-  const samples: number[] = []
-  let fetchCount = 0
-
-  for (let index = 0; index < STAMPEDE_RUNS; index += 1) {
-    await runner.clear()
-    const origin = createOriginFetcher(fixturePath)
-    const { durationMs } = await measure(() =>
-      runConcurrent(STAMPEDE_CONCURRENCY, () => runner.read(`user:${USER_ID}`, () => origin.run(USER_ID)))
-    )
-
-    samples.push(durationMs)
-    fetchCount += origin.getCount()
-  }
-
-  return {
-    ...summarizeScenario('stampede', samples, fetchCount),
-    mode,
-    scenario: 'stampede'
-  }
-}
-
-async function main(): Promise<void> {
-  const fixturePath = resolveBenchmarkFixturePath()
-  await ensureFixtureFile(fixturePath)
-  await ensureRedisContainer()
-
-  await waitForRedisReady()
-  const redis = createRedisClient()
-  await redis.ping()
-
-  const runners: Record<BenchmarkMode, CacheRunner> = {
-    'no-cache': createNoCacheRunner(),
-    memory: createMemoryRunner(),
-    layered: createLayeredRunner(redis)
-  }
-
-  try {
-    const results = [
-      await runColdMiss('no-cache', runners['no-cache'], fixturePath),
-      await runColdMiss('memory', runners.memory, fixturePath),
-      await runColdMiss('layered', runners.layered, fixturePath),
-      await runWarmHit('no-cache', runners['no-cache'], fixturePath),
-      await runWarmHit('memory', runners.memory, fixturePath),
-      await runWarmHit('layered', runners.layered, fixturePath),
-      await runStampede('no-cache', runners['no-cache'], fixturePath),
-      await runStampede('memory', runners.memory, fixturePath),
-      await runStampede('layered', runners.layered, fixturePath)
-    ]
-
-    console.table(
-      results.map((result) => ({
-        mode: result.mode,
-        scenario: result.scenario,
-        avgMs: result.avgMs,
-        p95Ms: result.p95Ms,
-        minMs: result.minMs,
-        maxMs: result.maxMs,
-        fetchCount: result.fetchCount
-      }))
-    )
-
-    console.log(JSON.stringify({ type: 'direct-benchmark', results }, null, 2))
-  } finally {
-    await Promise.all(
-      Object.values(runners)
-        .map((runner) => runner.disconnect)
-        .filter((value): value is NonNullable<typeof value> => Boolean(value))
-        .map((disconnect) => disconnect())
-    )
-    await redis.quit()
-    await stopRedisContainer()
-  }
-}
-
-void main().catch((error) => {
-  console.error(error)
-  process.exitCode = 1
-})

package/benchmarks/edge-utils.ts

@@ -1,28 +0,0 @@
-export interface OutageResult {
-  scenario: string
-  success: boolean
-  latencyMs: number
-  error: string | null
-}
-
-function round(value: number): number {
-  return Number(value.toFixed(3))
-}
-
-export function buildPayloadString(bytes: number): string {
-  return 'x'.repeat(bytes)
-}
-
-export function normalizeOutageResult(
-  scenario: string,
-  success: boolean,
-  latencyMs: number,
-  error?: string
-): OutageResult {
-  return {
-    scenario,
-    success,
-    latencyMs: round(latencyMs),
-    error: error ?? null
-  }
-}