Cache Behavior Simulator

Modern, beginner‑friendly tool to understand and test caching in Next.js and any web app: ISR, stale‑while‑revalidate, CDN/edge behavior. Includes a dark‑themed dashboard (Vite + React + Tailwind + shadcn‑style UI) and a powerful interactive CLI for stress/caching tests.

Features

• Dark, modern dashboard to simulate 20+ requests over a timeline
• Visualize cache hits, misses, and background revalidation
• Plain‑English explanations and quick insights (hit ratio, estimated latency)
• Interactive CLI (TUI) to scan routes and run stress/caching tests against any app
• Ready to publish to npm and run via npx

Demo (screenshots)

• Dashboard: timeline chart, insights, explanation
• CLI: route scan, URL selection, results table

Add screenshots to /docs/ and reference here once available.

Quick Start (Dashboard)

# 1) Install deps
npm install

# 2) Run dev
npm run dev
# open the printed URL (e.g., http://localhost:5173)

Build and serve the static UI locally:

npm run build
node bin/cache-sim.mjs serve --port 8792
# open http://localhost:8792

Use It In Any App (npx)

After publishing to npm, anyone can run:

# Serve the UI on a port (defaults to 8792)
npx cache-behavior-simulator serve --port 8792

# Or, interactive CLI to stress-test URLs
npx cache-behavior-simulator run

The CLI will:

• Ask your framework (Next.js App Router/Pages Router/Other)
• Scan app/**/page.tsx or pages/** (if applicable) to infer URLs
• Let you add/override URLs (e.g. http://localhost:3000, /blog, /docs)
• Run configurable load (total requests + concurrency)
• Print a clean summary table (avg/p50/p90/p99; hits/misses via Age/Cache‑Control heuristic)

You can also install locally into a project and add a script:

npm i -D cache-behavior-simulator

{
  "scripts": {
    "cache:serve": "cache-sim serve --port 8792",
    "cache:test": "cache-sim run"
  }
}

How The Simulation Works (Dashboard)

• 20 requests spread across 0–120 seconds (configurable in roadmap)
• Inputs:
  • fetch cache: force-cache, default, no-store
  • revalidate seconds (Next.js ISR)
  • Cache-Control header (e.g., s-maxage=30, stale-while-revalidate=10)
• Logic:
  • no-store → always miss
  • force-cache/default → honor TTL and SWR windows
  • Background revalidation occurs during SWR window
• Output:
  • Timeline dataset: { request, time, status: 'hit'|'miss'|'revalidating' }[]
  • Plain‑English explanation and quick insights (hit ratio, avg latency estimate)

Embedding API

You can use the pure simulation function in your own tooling/tests.

import { simulateCache } from 'cache-behavior-simulator/dist/simulate.js'
// OR if using this repo directly:
// import { simulateCache } from './src/lib/simulateCache'

const result = simulateCache({
  cacheOption: 'force-cache',
  revalidateSeconds: 30,
  cacheControlHeader: 's-maxage=30, stale-while-revalidate=10',
  // optional knobs for latency modeling
  originLatencyMs: 400,
  cacheHitLatencyMs: 50,
  revalidationDurationSec: 2,
})

console.log(result.points)       // timeline data
console.log(result.explanation)  // plain-English summary
console.log(result.metrics)      // quick metrics (hit ratio, avg latency)

Next.js Cheatsheet

• fetch cache
  • force-cache → serve from cache until TTL
  • no-store → always fetch fresh
  • default → framework decides per request
• ISR
  • revalidate: N or export const revalidate = N → revalidate in background after N seconds
• Headers
  • Cache-Control: s-maxage=N, stale-while-revalidate=M controls CDN/edge behavior

CLI Reference

# Serve the UI (static build)
cache-sim serve --port 8792
cache-behavior-simulator serve --port 8792  # alias

# Interactive stress/caching tests
cache-sim run
cache-behavior-simulator run                # alias

• Route scanning (Next.js App/Pages Router)
• URL entry override
• Configurable total requests and concurrency
• Heuristic cache hit detection via Age and Cache-Control

Note: For best results, run your app locally (e.g., http://localhost:3000) with production‑like cache headers.

Project Structure

src/
  components/
    SimulatorForm.tsx
    TimelineChart.tsx
    Explanation.tsx
    Insights.tsx
    Onboarding.tsx
    ui/ (shadcn-style primitives)
  lib/
    simulateCache.ts
  main.tsx
  index.css
bin/
  cache-sim.mjs          # CLI entry (serve + run)
cli/
  run.mjs                # Interactive tests (scan + stress)

Contributing

• Install: npm install
• Dev UI: npm run dev
• Build UI: npm run build
• Run CLI: node bin/cache-sim.mjs run

PRs welcome! Ideas:

• Multi-layer cache modeling (browser + edge + server)
• Import real headers/timings JSON
• Traffic patterns (bursty, Poisson)
• Per-route configs and combined dashboards
• Export reports (Markdown/JSON/PDF)

Publish to npm & Push to GitHub

1. Update metadata in package.json (name, author, homepage, repository).
2. Build:

npm run build

3. Publish to npm:

npm login
npm version patch   # or minor/major
npm publish

4. Push to GitHub:

git init
git remote add origin https://github.com/korybantes/cache-behavior-simulator.git
git add .
git commit -m "feat: initial release"
git branch -M main
git push -u origin main

5. Try from another app:

npx cache-behavior-simulator serve --port 8792
# or
npx cache-behavior-simulator run

License

MIT © You