ratelimit-engine 1.0.0 → 1.1.0

package/bin/cli.js

@@ -1,20 +1,28 @@
 #!/usr/bin/env node
 /**
  * ratelimit-engine CLI
- * Interactive wizard to simulate any built-in algorithm.
- * Usage: npx ratelimit-engine simulate
+ * Usage:
+ *   npx ratelimit-engine             — setup wizard
+ *   npx ratelimit-engine dashboard   — live 10ms dashboard
  */
 
 import * as readline from 'readline'
-import { FixedWindow }   from '../src/algorithms/FixedWindow.js'
-import { SlidingWindow } from '../src/algorithms/SlidingWindow.js'
-import { TokenBucket }   from '../src/algorithms/TokenBucket.js'
-import { LeakyBucket }   from '../src/algorithms/LeakyBucket.js'
-import { Composite }     from '../src/algorithms/Composite.js'
-import { MemoryStore }   from '../src/stores/MemoryStore.js'
-import { COMPOSITE_MODES } from '../src/constants/algorithms.js'
-
-// ── ANSI colours ─────────────────────────────────────────────────
+import * as fs from 'fs'
+import * as path from 'path'
+import { createRequire } from 'module'
+import { fileURLToPath }  from 'url'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+
+// ── Route subcommands ─────────────────────────────────────────────
+const subcommand = process.argv[2]
+if (subcommand === 'dashboard') {
+  // Dynamically import and run the dashboard
+  await import(new URL('./dashboard.js', import.meta.url))
+  process.exit(0)
+}
+
+// ── ANSI colours ──────────────────────────────────────────────────
 const C = {
   reset:   '\x1b[0m',
   bold:    '\x1b[1m',
@@ -24,19 +32,18 @@ const C = {
   yellow:  '\x1b[33m',
   cyan:    '\x1b[36m',
   magenta: '\x1b[35m',
-  white:   '\x1b[37m',
-  bgDark:  '\x1b[48;5;235m',
+  blue:    '\x1b[34m',
 }
 
 const bold    = (s) => `${C.bold}${s}${C.reset}`
 const dim     = (s) => `${C.dim}${s}${C.reset}`
 const green   = (s) => `${C.green}${s}${C.reset}`
-const red     = (s) => `${C.red}${s}${C.reset}`
 const cyan    = (s) => `${C.cyan}${s}${C.reset}`
 const yellow  = (s) => `${C.yellow}${s}${C.reset}`
 const magenta = (s) => `${C.magenta}${s}${C.reset}`
+const blue    = (s) => `${C.blue}${s}${C.reset}`
 
-// ── Readline helper ───────────────────────────────────────────────
+// ── Readline helpers ──────────────────────────────────────────────
 const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
 
 function ask(question) {
@@ -45,219 +52,270 @@ function ask(question) {
   })
 }
 
-function askNumber(question, defaultVal) {
-  return new Promise(async (resolve) => {
-    const raw = await ask(`${question} ${dim(`[${defaultVal}]`)}: `)
-    const num = parseInt(raw, 10)
-    resolve(isNaN(num) || num <= 0 ? defaultVal : num)
+async function askNumber(label, defaultVal) {
+  const raw = await ask(`  ${label} ${dim(`[${defaultVal}]`)}: `)
+  const num = parseInt(raw, 10)
+  return isNaN(num) || num <= 0 ? defaultVal : num
+}
+
+async function askChoice(choices) {
+  choices.forEach((c, i) => {
+    console.log(`  ${bold(cyan(String(i + 1)))}. ${bold(c.label.padEnd(18))} ${dim(c.desc)}`)
   })
+  const raw = await ask(`\n  Pick [1-${choices.length}]: `)
+  const idx = parseInt(raw, 10) - 1
+  if (isNaN(idx) || idx < 0 || idx >= choices.length) return choices[0]
+  return choices[idx]
 }
 
-// ── Algorithm menu ────────────────────────────────────────────────
+// ── Algorithm definitions ─────────────────────────────────────────
 const ALGORITHMS = [
-  {
-    key:   'token-bucket',
-    label: 'Token Bucket',
-    desc:  'Burst-friendly — refills tokens over time',
-    color: cyan,
-  },
-  {
-    key:   'fixed-window',
-    label: 'Fixed Window',
-    desc:  'Simple counter per time window',
-    color: green,
-  },
-  {
-    key:   'sliding-window',
-    label: 'Sliding Window',
-    desc:  'Smooth rolling window, no boundary spikes',
-    color: yellow,
-  },
-  {
-    key:   'leaky-bucket',
-    label: 'Leaky Bucket',
-    desc:  'Strict output rate, drops excess',
-    color: magenta,
-  },
-  {
-    key:   'composite',
-    label: 'Composite',
-    desc:  'Combine two algorithms (ALL / ANY)',
-    color: (s) => `\x1b[35m${s}${C.reset}`,
-  },
+  { key: 'TokenBucket',   label: 'Token Bucket',   desc: 'Burst-friendly — refills tokens over time' },
+  { key: 'FixedWindow',   label: 'Fixed Window',   desc: 'Simple counter per time window' },
+  { key: 'SlidingWindow', label: 'Sliding Window', desc: 'Smooth rolling window, no boundary spikes' },
+  { key: 'LeakyBucket',   label: 'Leaky Bucket',   desc: 'Strict output rate, drops excess' },
+  { key: 'Composite',     label: 'Composite',      desc: 'Combine two algorithms (ALL / ANY)' },
+]
+
+const STORES = [
+  { key: 'MemoryStore', label: 'Memory',  desc: 'In-process store — single instance' },
+  { key: 'RedisStore',  label: 'Redis',   desc: 'Distributed store — multi-instance / clustered' },
+]
+
+const FRAMEWORKS = [
+  { key: 'express',  label: 'Express',  desc: 'app.use(limiter.express())' },
+  { key: 'fastify',  label: 'Fastify',  desc: 'fastify.addHook("onRequest", limiter.fastify())' },
+  { key: 'manual',   label: 'Manual',   desc: 'limiter.check(ctx) — any framework' },
 ]
 
-// ── Build algorithm from user input ──────────────────────────────
-async function buildAlgorithm(key) {
+const KEY_STRATEGIES = [
+  { key: 'byIP',               label: 'By IP',         desc: 'One counter per client IP (default)' },
+  { key: 'byUser',             label: 'By User',        desc: 'One counter per authenticated user' },
+  { key: 'byRoute',            label: 'By Route',       desc: 'One counter per URL path' },
+  { key: 'compositeResolver',  label: 'IP + Route',     desc: 'Separate counter per IP+route combination' },
+]
+
+// ── Config collectors ─────────────────────────────────────────────
+async function collectAlgoConfig(key) {
   switch (key) {
-    case 'token-bucket': {
-      const capacity   = await askNumber('  Bucket capacity (max tokens)', 10)
-      const refillRate = await askNumber('  Refill rate (tokens/sec)', 2)
-      return new TokenBucket({ capacity, refillRate })
+    case 'TokenBucket': {
+      const capacity   = await askNumber('Token bucket capacity (burst size)', 100)
+      const refillRate = await askNumber('Refill rate (tokens/sec)', 10)
+      return { capacity, refillRate }
     }
-    case 'fixed-window': {
-      const limit    = await askNumber('  Max requests', 10)
-      const windowMs = (await askNumber('  Window (seconds)', 60)) * 1000
-      return new FixedWindow({ limit, windowMs })
+    case 'FixedWindow':
+    case 'SlidingWindow': {
+      const limit    = await askNumber('Max requests per window', 100)
+      const windowMs = (await askNumber('Window size (seconds)', 60)) * 1000
+      return { limit, windowMs }
     }
-    case 'sliding-window': {
-      const limit    = await askNumber('  Max requests', 10)
-      const windowMs = (await askNumber('  Window (seconds)', 60)) * 1000
-      return new SlidingWindow({ limit, windowMs })
+    case 'LeakyBucket': {
+      const capacity = await askNumber('Queue capacity (max queued requests)', 100)
+      const leakRate = await askNumber('Leak rate (requests/sec)', 10)
+      return { capacity, leakRate }
     }
-    case 'leaky-bucket': {
-      const capacity = await askNumber('  Bucket capacity (queue depth)', 10)
-      const leakRate = await askNumber('  Leak rate (requests/sec)', 2)
-      return new LeakyBucket({ capacity, leakRate })
-    }
-    case 'composite': {
-      console.log(`\n  ${bold('Primary algorithm:')}`)
-      const primaryKey  = await pickAlgorithm(ALGORITHMS.filter((a) => a.key !== 'composite'))
-      const primary     = await buildAlgorithm(primaryKey)
-
-      console.log(`\n  ${bold('Secondary algorithm:')}`)
-      const secondaryKey = await pickAlgorithm(ALGORITHMS.filter((a) => a.key !== 'composite'))
-      const secondary    = await buildAlgorithm(secondaryKey)
-
-      const modeRaw = await ask(`\n  Mode — ${cyan('1')} ALL (both must pass) / ${yellow('2')} ANY (one must pass) [1]: `)
-      const mode    = modeRaw === '2' ? COMPOSITE_MODES.ANY : COMPOSITE_MODES.ALL
-
-      return new Composite({ algorithms: [primary, secondary], mode })
+    case 'Composite': {
+      console.log(`\n  ${bold('Primary algorithm:')}\n`)
+      const primary = await askChoice(ALGORITHMS.filter((a) => a.key !== 'Composite'))
+      const primaryConfig = await collectAlgoConfig(primary.key)
+
+      console.log(`\n  ${bold('Secondary algorithm:')}\n`)
+      const secondary = await askChoice(ALGORITHMS.filter((a) => a.key !== 'Composite'))
+      const secondaryConfig = await collectAlgoConfig(secondary.key)
+
+      console.log(`\n  ${bold('Composite mode:')}\n`)
+      const mode = await askChoice([
+        { key: 'ALL', label: 'ALL', desc: 'Both algorithms must allow the request' },
+        { key: 'ANY', label: 'ANY', desc: 'At least one algorithm must allow the request' },
+      ])
+
+      return { primary: { key: primary.key, config: primaryConfig }, secondary: { key: secondary.key, config: secondaryConfig }, mode: mode.key }
     }
     default:
-      return new FixedWindow()
+      return {}
   }
 }
 
-async function pickAlgorithm(list = ALGORITHMS) {
-  list.forEach((a, i) => {
-    console.log(`  ${bold(cyan(String(i + 1)))}. ${bold(a.label.padEnd(18))} ${dim(a.desc)}`)
-  })
-
-  const raw = await ask(`\n  Pick [1-${list.length}]: `)
-  const idx = parseInt(raw, 10) - 1
-
-  if (isNaN(idx) || idx < 0 || idx >= list.length) {
-    console.log(dim('  Invalid choice — defaulting to Token Bucket'))
-    return 'token-bucket'
+// ── Code generators ───────────────────────────────────────────────
+function algoArgs(key, config) {
+  switch (key) {
+    case 'TokenBucket':
+      return `{ capacity: ${config.capacity}, refillRate: ${config.refillRate} }`
+    case 'FixedWindow':
+    case 'SlidingWindow':
+      return `{ limit: ${config.limit}, windowMs: ${config.windowMs} }`
+    case 'LeakyBucket':
+      return `{ capacity: ${config.capacity}, leakRate: ${config.leakRate} }`
+    default:
+      return '{}'
   }
-
-  return list[idx].key
 }
 
-// ── Table renderer ────────────────────────────────────────────────
-function renderTable(rows) {
-  const cols = [
-    { key: 'req',        label: 'Req',        width: 5  },
-    { key: 'time',       label: 'Time (ms)',  width: 10 },
-    { key: 'allowed',    label: 'Allowed',    width: 10 },
-    { key: 'remaining',  label: 'Remaining',  width: 11 },
-    { key: 'retryAfter', label: 'Retry (s)',  width: 10 },
-    { key: 'resetAt',    label: 'Resets At',  width: 12 },
-  ]
-
-  const divider = '+' + cols.map((c) => '-'.repeat(c.width + 2)).join('+') + '+'
-  const header  = '|' + cols.map((c) => ` ${bold(c.label.padEnd(c.width))} `).join('|') + '|'
-
-  console.log('\n' + divider)
-  console.log(header)
-  console.log(divider)
-
-  for (const row of rows) {
-    const allowed = row.allowed
-      ? green('✅ yes'.padEnd(10))
-      : red('❌ no'.padEnd(10))
-
-    const line = '|' + [
-      ` ${String(row.req).padEnd(cols[0].width)} `,
-      ` ${String(row.time).padEnd(cols[1].width)} `,
-      ` ${allowed} `,
-      ` ${String(row.remaining).padEnd(cols[3].width)} `,
-      ` ${String(row.retryAfter ?? '—').padEnd(cols[4].width)} `,
-      ` ${String(row.resetAt).padEnd(cols[5].width)} `,
-    ].join('|') + '|'
-
-    console.log(line)
+function generateConfig({ algoKey, algoConfig, storeKey, frameworkKey, keyStrategyKey, failOpen = true, customOnBlocked = null }) {
+  const isRedis     = storeKey === 'RedisStore'
+  const isComposite = algoKey === 'Composite'
+
+  const imports = isComposite
+    ? [algoKey, algoConfig.primary.key, algoConfig.secondary.key]
+    : [algoKey]
+
+  const allImports = [...new Set(['createLimiter', ...imports, storeKey, keyStrategyKey])]
+
+  const redisImport  = isRedis ? `\nimport Redis from 'ioredis'` : ''
+  const redisClient  = isRedis ? `\nconst redis = new Redis() // configure your Redis connection\n` : ''
+  const storeInit    = isRedis
+    ? `new RedisStore({ client: redis })`
+    : `new MemoryStore()`
+
+  let algoInit
+  if (isComposite) {
+    const { primary, secondary, mode } = algoConfig
+    algoInit = `new Composite({
+  algorithms: [
+    new ${primary.key}(${algoArgs(primary.key, primary.config)}),
+    new ${secondary.key}(${algoArgs(secondary.key, secondary.config)}),
+  ],
+  mode: COMPOSITE_MODES.${mode},
+})`
+  } else {
+    algoInit = `new ${algoKey}(${algoArgs(algoKey, algoConfig)})`
   }
 
-  console.log(divider)
-}
+  const compositeImport = isComposite ? `, COMPOSITE_MODES` : ''
+
+  let frameworkUsage
+  switch (frameworkKey) {
+    case 'express':
+      frameworkUsage = `// Express — apply globally
+app.use(limiter.express())
+
+// or per-route
+app.get('/api/resource', limiter.express(), handler)`
+      break
+    case 'fastify':
+      frameworkUsage = `// Fastify — apply globally
+fastify.addHook('onRequest', limiter.fastify())
+
+// or per-route
+fastify.get('/api/resource', { onRequest: limiter.fastify() }, handler)`
+      break
+    case 'manual':
+      frameworkUsage = `// Manual — any framework
+const result = await limiter.check({
+  ip:   req.ip,
+  path: req.path,
+  user: req.user?.id, // optional
+})
 
-// ── Summary ───────────────────────────────────────────────────────
-function renderSummary(rows) {
-  const allowed   = rows.filter((r) => r.allowed).length
-  const blocked   = rows.filter((r) => !r.allowed).length
-  const avgRemain = (rows.reduce((s, r) => s + r.remaining, 0) / rows.length).toFixed(1)
+if (!result.allowed) {
+  return res.status(429).json({
+    error:      'Too Many Requests',
+    retryAfter: result.retryAfter,
+  })
+}`
+      break
+  }
 
-  console.log(`
-  ${bold('Summary')}
-  ───────────────────────────────
-  Total requests : ${bold(String(rows.length))}
-  Allowed        : ${green(bold(String(allowed)))}
-  Blocked        : ${red(bold(String(blocked)))}
-  Avg remaining  : ${cyan(avgRemain)}
-  `)
-}
+  const onBlockedMsg = customOnBlocked
+    ? `console.warn(\`${customOnBlocked}\`)`
+    : `console.warn(\`[RATE LIMIT] \${ctx.ip} blocked — retry in \${result.retryAfter}s\`)`
+
+  return `import { ${allImports.join(', ')}${compositeImport} } from 'ratelimit-engine'${redisImport}
+${redisClient}
+const limiter = createLimiter({
+  algorithm: ${algoInit},
+  store:     ${storeInit},
+  keyBy:     ${keyStrategyKey},
+  failOpen:  ${failOpen},
+  onBlocked: (ctx, result) => {
+    ${onBlockedMsg}
+  },
+})
+
+${frameworkUsage}
 
-// ── Sleep helper ──────────────────────────────────────────────────
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms))
+export { limiter }
+`
 }
 
 // ── Main ──────────────────────────────────────────────────────────
 async function main() {
   console.clear()
   console.log(`
-  ${bold(cyan('⚡ ratelimit-engine'))} ${dim('— Algorithm Simulator')}
-  ${dim('─────────────────────────────────────────')}
+  ${bold(cyan('⚡ ratelimit-engine'))} ${dim('— Setup Wizard')}
+  ${dim('─────────────────────────────────────────────')}
+  ${dim('Generates a ready-to-use ratelimit.config.js')}
+  ${dim('for your project in the current directory.')}
   `)
 
-  console.log(`  ${bold('Select algorithm:')}\n`)
-  const algoKey  = await pickAlgorithm()
-  const algo     = await buildAlgorithm(algoKey)
-  const requests = await askNumber('\nSimulate how many requests?', 15)
-  const delayMs  = await askNumber('Delay between requests (ms)?', 100)
-
-  console.log(`\n  ${dim('Running simulation...')}\n`)
-
-  const store = new MemoryStore()
-  const rows  = []
-  const key   = 'cli:simulate'
-  const start = Date.now()
-
-  for (let i = 1; i <= requests; i++) {
-    const result = await algo.check(key, store)
-    const elapsed = Date.now() - start
-
-    rows.push({
-      req:        i,
-      time:       elapsed,
-      allowed:    result.allowed,
-      remaining:  result.remaining,
-      retryAfter: result.retryAfter !== undefined ? result.retryAfter : '—',
-      resetAt:    result.resetAt.toTimeString().slice(0, 8),
-    })
-
-    if (i < requests) {
-      await sleep(delayMs)
-    }
+  // Step 1 — Algorithm
+  console.log(`  ${bold('Step 1 — Choose an algorithm:')}\n`)
+  const algo = await askChoice(ALGORITHMS)
+  console.log()
+  const algoConfig = await collectAlgoConfig(algo.key)
+
+  // Step 2 — Store
+  console.log(`\n  ${bold('Step 2 — Choose a store:')}\n`)
+  const store = await askChoice(STORES)
+  if (store.key === 'RedisStore') {
+    console.log(`\n  ${yellow('Note:')} Make sure ${bold('ioredis')} is installed: ${dim('npm install ioredis')}`)
   }
 
-  await store.destroy()
-  renderTable(rows)
-  renderSummary(rows)
+  // Step 3 — Framework
+  console.log(`\n  ${bold('Step 3 — Choose your framework:')}\n`)
+  const framework = await askChoice(FRAMEWORKS)
+
+  // Step 4 — Key strategy
+  console.log(`\n  ${bold('Step 4 — How should requests be keyed?')}\n`)
+  const keyStrategy = await askChoice(KEY_STRATEGIES)
+
+  // Step 5 — Custom overrides
+  console.log(`\n  ${bold('Step 5 — Custom options')} ${dim('(press Enter to skip each)')}`)
+  console.log(`  ${dim('Override any value before the file is written.\n')}`)
+
+  const outputFile = await ask(`  Output filename ${dim('[ratelimit.config.js]')}: `)
+  const fileName   = outputFile || 'ratelimit.config.js'
+
+  const customOnBlocked = await ask(`  onBlocked message ${dim('[Rate limit exceeded, retry in {n}s]')}: `)
+  const failOpenRaw     = await ask(`  failOpen — allow requests when store is down? ${dim('[yes]')}: `)
+  const failOpen        = failOpenRaw.toLowerCase() === 'no' ? false : true
+
+  // Generate
+  const code = generateConfig({
+    algoKey:        algo.key,
+    algoConfig,
+    storeKey:       store.key,
+    frameworkKey:   framework.key,
+    keyStrategyKey: keyStrategy.key,
+    failOpen,
+    customOnBlocked: customOnBlocked || null,
+  })
 
-  const again = await ask('  Run another simulation? (y/n) [n]: ')
-  if (again.toLowerCase() === 'y') {
-    await main()
-  } else {
-    console.log(`\n  ${dim('Goodbye.')}\n`)
-    rl.close()
+  // Write file
+  const outPath = path.join(process.cwd(), fileName)
+  fs.writeFileSync(outPath, code, 'utf8')
+
+  // Output
+  console.log(`\n  ${dim('─────────────────────────────────────────────')}`)
+  console.log(`  ${green(bold('✅ Done!'))} Generated ${bold(fileName)}\n`)
+  console.log(`  ${dim('─────────────────────────────────────────────')}`)
+  console.log(`\n${code}`)
+  console.log(`  ${dim('─────────────────────────────────────────────')}`)
+  console.log(`\n  ${bold('Next steps:')}\n`)
+  console.log(`  ${cyan('1.')} Import the config into your app:`)
+  console.log(`     ${dim(`import { limiter } from './${fileName}'`)}`)
+  console.log(`\n  ${cyan('2.')} Wire it up — the usage snippet is inside the generated file.`)
+  if (store.key === 'RedisStore') {
+    console.log(`\n  ${cyan('3.')} Install ioredis if not already:`)
+    console.log(`     ${dim('npm install ioredis')}`)
   }
+  console.log()
+
+  rl.close()
 }
 
 main().catch((err) => {
-  console.error(red(`\nError: ${err.message}`))
+  console.error(`\nError: ${err.message}`)
   rl.close()
   process.exit(1)
 })

package/bin/dashboard.js

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Live dashboard entry point.
+ * Starts a demo server with rate limiting wired to the DashboardCollector,
+ * then renders the terminal UI at 10ms intervals.
+ *
+ * Usage: npx ratelimit-engine dashboard
+ */
+
+import { DashboardCollector } from '../src/dashboard/DashboardCollector.js'
+import { DashboardRenderer }  from '../src/dashboard/DashboardRenderer.js'
+import { createLimiter }      from '../src/engine/createLimiter.js'
+import { TokenBucket }        from '../src/algorithms/TokenBucket.js'
+import { FixedWindow }        from '../src/algorithms/FixedWindow.js'
+import { SlidingWindow }      from '../src/algorithms/SlidingWindow.js'
+import { MemoryStore }        from '../src/stores/MemoryStore.js'
+import { byIP }               from '../src/resolvers/byIP.js'
+
+const REFRESH_MS  = 10
+const DEMO_IPS    = ['192.168.1.1', '10.0.0.5', '172.16.0.3', '127.0.0.1']
+const DEMO_PATHS  = ['/api/hello', '/api/login', '/api/search', '/api/admin/data']
+const DEMO_METHOD = ['GET', 'POST', 'GET', 'DELETE']
+
+// ── Collector + Renderer ──────────────────────────────────────────
+const collector = new DashboardCollector()
+const renderer  = new DashboardRenderer()
+
+// ── Demo limiter (Token Bucket: burst 5, refill 2/sec) ───────────
+const limiter = createLimiter({
+  algorithm: new TokenBucket({ capacity: 5, refillRate: 2 }),
+  store:     new MemoryStore(),
+  keyBy:     byIP,
+  failOpen:  true,
+  onAllowed: (ctx, result) => collector.recordAllowed(ctx),
+  onBlocked: (ctx, result) => collector.recordBlocked(ctx, result),
+})
+
+// ── Simulate traffic — random bursts every 10–80ms ────────────────
+function simulateRequest() {
+  const idx    = Math.floor(Math.random() * DEMO_IPS.length)
+  const ip     = DEMO_IPS[idx]
+  const path   = DEMO_PATHS[idx]
+  const method = DEMO_METHOD[idx]
+
+  limiter.check({ ip, path, method, user: null })
+
+  // Schedule next request with variable interval to create burst patterns
+  const nextIn = Math.random() < 0.3
+    ? Math.floor(Math.random() * 5)    // burst: 0–5ms
+    : Math.floor(Math.random() * 80)   // normal: 0–80ms
+  setTimeout(simulateRequest, nextIn)
+}
+
+// ── Flush bucket every 10ms ───────────────────────────────────────
+const flushInterval = setInterval(() => collector.flush(), REFRESH_MS)
+
+// ── Render loop every 10ms ────────────────────────────────────────
+let paused = false
+const renderInterval = setInterval(() => {
+  if (!paused) renderer.render(collector.snapshot())
+}, REFRESH_MS)
+
+// ── Keyboard input ────────────────────────────────────────────────
+if (process.stdin.isTTY) {
+  process.stdin.setRawMode(true)
+}
+process.stdin.resume()
+process.stdin.setEncoding('utf8')
+
+process.stdin.on('data', (key) => {
+  if (key === 'q' || key === '\u0003') {
+    cleanup()
+  } else if (key === 'r') {
+    collector.reset()
+  } else if (key === 'p') {
+    paused = !paused
+    renderer.paused = paused
+  }
+})
+
+function cleanup() {
+  clearInterval(flushInterval)
+  clearInterval(renderInterval)
+  renderer.cleanup()
+  limiter.destroy()
+  process.exit(0)
+}
+
+process.on('SIGINT', cleanup)
+process.on('SIGTERM', cleanup)
+
+// ── Start ─────────────────────────────────────────────────────────
+simulateRequest()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ratelimit-engine",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Enterprise-grade, algorithm-pluggable rate limiting engine for Node.js",
   "main": "src/index.js",
   "type": "module",
@@ -35,7 +35,8 @@
     "LICENSE"
   ],
   "bin": {
-    "ratelimit-engine": "./bin/cli.js"
+    "ratelimit-engine": "./bin/cli.js",
+    "ratelimit-dashboard": "./bin/dashboard.js"
   },
   "author": "Abhinav710 <kumarabhinav5693@gmail.com>",
   "license": "MIT",

package/src/dashboard/DashboardCollector.js

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview In-process event collector for the live dashboard.
+ * Receives allowed/blocked events from RateLimiter hooks and
+ * maintains a rolling 10ms-bucketed time series.
+ */
+
+import { EventEmitter } from 'events'
+
+const BUCKET_MS   = 10   // resolution: one bucket per 10ms
+const HISTORY     = 200  // keep last 200 buckets (2 seconds of sparkline)
+const TOP_IPS     = 8    // max IPs shown in top-IPs panel
+const FEED_SIZE   = 12   // max rows in live feed
+
+export class DashboardCollector extends EventEmitter {
+  constructor() {
+    super()
+    this._buckets   = []   // rolling array of { ts, allowed, blocked }
+    this._ipMap     = new Map()   // ip → { allowed, blocked, lastSeen }
+    this._feed      = []          // last N events
+    this._startedAt = Date.now()
+    this._current   = this._newBucket()
+  }
+
+  /** Called by onAllowed hook */
+  recordAllowed(context) {
+    this._current.allowed++
+    this._trackIP(context, true)
+    this._pushFeed({ allowed: true, context, ts: Date.now() })
+    this.emit('tick')
+  }
+
+  /** Called by onBlocked hook */
+  recordBlocked(context, result) {
+    this._current.blocked++
+    this._trackIP(context, false)
+    this._pushFeed({ allowed: false, context, result, ts: Date.now() })
+    this.emit('tick')
+  }
+
+  /** Flush current bucket and start a new one — called every 10ms */
+  flush() {
+    this._buckets.push(this._current)
+    if (this._buckets.length > HISTORY) this._buckets.shift()
+    this._current = this._newBucket()
+  }
+
+  /** Snapshot for the renderer */
+  snapshot() {
+    const buckets  = [...this._buckets, this._current]
+    const last     = buckets.slice(-20)   // last 200ms window
+
+    const totalAllowed  = last.reduce((s, b) => s + b.allowed, 0)
+    const totalBlocked  = last.reduce((s, b) => s + b.blocked, 0)
+    const total         = totalAllowed + totalBlocked
+
+    const topIPs = [...this._ipMap.entries()]
+      .map(([ip, v]) => ({ ip, ...v }))
+      .sort((a, b) => (b.allowed + b.blocked) - (a.allowed + a.blocked))
+      .slice(0, TOP_IPS)
+
+    return {
+      uptime:    Date.now() - this._startedAt,
+      total,
+      allowed:   totalAllowed,
+      blocked:   totalBlocked,
+      sparkline: buckets.map((b) => b.allowed + b.blocked),
+      topIPs,
+      feed:      [...this._feed],
+    }
+  }
+
+  reset() {
+    this._buckets  = []
+    this._ipMap    = new Map()
+    this._feed     = []
+    this._current  = this._newBucket()
+    this._startedAt = Date.now()
+  }
+
+  _newBucket() {
+    return { ts: Date.now(), allowed: 0, blocked: 0 }
+  }
+
+  _trackIP(context, allowed) {
+    const ip = context?.ip ?? 'unknown'
+    const entry = this._ipMap.get(ip) ?? { allowed: 0, blocked: 0, lastSeen: 0 }
+    if (allowed) entry.allowed++
+    else entry.blocked++
+    entry.lastSeen = Date.now()
+    this._ipMap.set(ip, entry)
+  }
+
+  _pushFeed(event) {
+    this._feed.unshift(event)
+    if (this._feed.length > FEED_SIZE) this._feed.pop()
+  }
+}

package/src/dashboard/DashboardRenderer.js

@@ -0,0 +1,186 @@
+/**
+ * @fileoverview Terminal renderer for the live dashboard.
+ * Uses ANSI escape codes only — zero dependencies.
+ * Redraws the full screen every 10ms via process.stdout.write.
+ */
+
+// ── ANSI helpers ──────────────────────────────────────────────────
+const ESC   = '\x1b['
+const CLEAR = '\x1b[2J\x1b[H'   // clear screen + move cursor to top
+const HIDE  = '\x1b[?25l'       // hide cursor
+const SHOW  = '\x1b[?25h'       // show cursor
+
+const C = {
+  reset:   '\x1b[0m',
+  bold:    '\x1b[1m',
+  dim:     '\x1b[2m',
+  green:   '\x1b[32m',
+  red:     '\x1b[31m',
+  yellow:  '\x1b[33m',
+  cyan:    '\x1b[36m',
+  magenta: '\x1b[35m',
+  blue:    '\x1b[34m',
+  white:   '\x1b[37m',
+  bgRed:   '\x1b[41m',
+  bgGreen: '\x1b[42m',
+}
+
+const bold    = (s) => `${C.bold}${s}${C.reset}`
+const dim     = (s) => `${C.dim}${s}${C.reset}`
+const green   = (s) => `${C.green}${s}${C.reset}`
+const red     = (s) => `${C.red}${s}${C.reset}`
+const yellow  = (s) => `${C.yellow}${s}${C.reset}`
+const cyan    = (s) => `${C.cyan}${s}${C.reset}`
+const magenta = (s) => `${C.magenta}${s}${C.reset}`
+
+// ── Sparkline ─────────────────────────────────────────────────────
+const SPARK_CHARS = ' ▁▂▃▄▅▆▇█'
+
+function sparkline(values, width = 50) {
+  const slice = values.slice(-width)
+  const max   = Math.max(...slice, 1)
+  return slice
+    .map((v) => {
+      const idx = Math.round((v / max) * (SPARK_CHARS.length - 1))
+      return SPARK_CHARS[idx]
+    })
+    .join('')
+    .padStart(width)
+}
+
+// ── Bar ───────────────────────────────────────────────────────────
+function bar(value, max, width = 30, color = green) {
+  const filled = max > 0 ? Math.round((value / max) * width) : 0
+  const empty  = width - filled
+  return color('█'.repeat(filled)) + dim('░'.repeat(empty))
+}
+
+// ── Format helpers ────────────────────────────────────────────────
+function fmtUptime(ms) {
+  const s = Math.floor(ms / 1000)
+  const m = Math.floor(s / 60)
+  const h = Math.floor(m / 60)
+  return [
+    String(h).padStart(2, '0'),
+    String(m % 60).padStart(2, '0'),
+    String(s % 60).padStart(2, '0'),
+  ].join(':')
+}
+
+function fmtTime(ts) {
+  return new Date(ts).toISOString().slice(11, 23)  // HH:MM:SS.mmm
+}
+
+function pad(s, n) {
+  return String(s).slice(0, n).padEnd(n)
+}
+
+// ── Box drawing ───────────────────────────────────────────────────
+const W = 62   // inner box width
+
+function boxTop(title) {
+  const t = title ? ` ${title} ` : ''
+  const dashes = '─'.repeat(W - t.length)
+  return `  ┌─${t}${dashes}┐`
+}
+
+function boxRow(content) {
+  const raw   = content.replace(/\x1b\[[0-9;]*m/g, '')  // strip ANSI for length
+  const pad   = W - raw.length
+  return `  │ ${content}${' '.repeat(Math.max(0, pad - 1))}│`
+}
+
+function boxBot() {
+  return `  └${'─'.repeat(W + 1)}┘`
+}
+
+// ── Main renderer ─────────────────────────────────────────────────
+export class DashboardRenderer {
+  constructor({ paused = false } = {}) {
+    this.paused = paused
+  }
+
+  render(snapshot) {
+    const { uptime, total, allowed, blocked, sparkline: spark, topIPs, feed } = snapshot
+    const blockPct = total > 0 ? ((blocked / total) * 100).toFixed(1) : '0.0'
+    const maxBar   = Math.max(total, 1)
+    const lines    = []
+
+    // ── Header ────────────────────────────────────────────────────
+    lines.push('')
+    lines.push(
+      `  ${bold(cyan('⚡ ratelimit-engine'))}  ${dim('Live Dashboard')}` +
+      `${' '.repeat(18)}${dim('Refresh: 10ms')}  ${this.paused ? yellow(bold('[PAUSED]')) : ''}`
+    )
+    lines.push(`  ${dim('─'.repeat(W + 2))}`)
+    lines.push(
+      `  Uptime: ${bold(fmtUptime(uptime))}` +
+      `${' '.repeat(10)}Window: last 200ms` +
+      `${' '.repeat(8)}${blocked > allowed ? red('⚠ HIGH BLOCK RATE') : green('● healthy')}`
+    )
+    lines.push('')
+
+    // ── Traffic panel ─────────────────────────────────────────────
+    lines.push(boxTop('Traffic — per 10ms bucket'))
+    lines.push(boxRow(`${pad('Total',    9)} ${bar(total,   maxBar, 28, cyan)}   ${bold(pad(total,   5))} req`))
+    lines.push(boxRow(`${pad('Allowed',  9)} ${bar(allowed, maxBar, 28, green)}   ${bold(green(pad(allowed, 5)))} req`))
+    lines.push(boxRow(`${pad('Blocked',  9)} ${bar(blocked, maxBar, 28, red)}   ${bold(red(pad(blocked, 5)))} req  ${dim(`${blockPct}%`)}`))
+    lines.push(boxBot())
+    lines.push('')
+
+    // ── Sparkline panel ───────────────────────────────────────────
+    lines.push(boxTop('Sparkline — last 2s (200 buckets × 10ms)'))
+    lines.push(boxRow(cyan(sparkline(spark, W - 2))))
+    lines.push(boxBot())
+    lines.push('')
+
+    // ── Top IPs ───────────────────────────────────────────────────
+    lines.push(boxTop('Top IPs'))
+    if (topIPs.length === 0) {
+      lines.push(boxRow(dim('No traffic yet...')))
+    } else {
+      for (const entry of topIPs) {
+        const ipTotal  = entry.allowed + entry.blocked
+        const label    = entry.blocked > entry.allowed
+          ? red('🔴 high block')
+          : green('🟢 normal   ')
+        const ipBar    = bar(entry.blocked, Math.max(ipTotal, 1), 12, red)
+        lines.push(boxRow(
+          `${pad(entry.ip, 16)}  ` +
+          `${pad(ipTotal, 5)} req  ` +
+          `${red(pad(entry.blocked, 4))} blocked  ` +
+          `${ipBar}  ${label}`
+        ))
+      }
+    }
+    lines.push(boxBot())
+    lines.push('')
+
+    // ── Live feed ─────────────────────────────────────────────────
+    lines.push(boxTop('Live Feed'))
+    if (feed.length === 0) {
+      lines.push(boxRow(dim('Waiting for requests...')))
+    } else {
+      for (const ev of feed) {
+        const status  = ev.allowed ? green('✅ ALLOWED') : red('❌ BLOCKED')
+        const ip      = pad(ev.context?.ip ?? 'unknown', 15)
+        const method  = pad(ev.context?.method ?? 'GET', 6)
+        const path    = pad(ev.context?.path ?? '/', 20)
+        const time    = dim(fmtTime(ev.ts))
+        lines.push(boxRow(`${time}  ${status}  ${ip} ${method} ${path}`))
+      }
+    }
+    lines.push(boxBot())
+    lines.push('')
+
+    // ── Footer ────────────────────────────────────────────────────
+    lines.push(`  ${dim('[q]')} quit   ${dim('[r]')} reset counters   ${dim('[p]')} pause/resume`)
+    lines.push('')
+
+    process.stdout.write(HIDE + CLEAR + lines.join('\n'))
+  }
+
+  cleanup() {
+    process.stdout.write(SHOW + '\n')
+  }
+}