@joint-ops/hitlimit-bun 1.1.2 → 1.1.3

package/README.md

@@ -6,36 +6,24 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 [![Bun](https://img.shields.io/badge/Bun-Native-black.svg)](https://bun.sh)
 
-> The fastest rate limiter for Bun - 5M+ ops/sec under real-world load | Elysia, Hono & Bun.serve
+> The fastest rate limiter for Bun — 5.6M+ ops/sec | Bun.serve, Elysia & Hono
 
-**hitlimit-bun** is a blazing-fast, Bun-native rate limiting library for Bun.serve, Elysia, and Hono applications. **Memory-first by default** with 5.62M ops/sec under real-world load (~15x faster than SQLite). Optional persistence with native bun:sqlite or Redis when you need it.
+**hitlimit-bun** is a Bun-native rate limiting library. Memory-first with 5.62M ops/sec under real-world load. Atomic Redis Lua scripts for distributed systems. Native bun:sqlite for persistence. Zero runtime dependencies.
 
 **[Documentation](https://hitlimit.jointops.dev/docs/bun)** | **[GitHub](https://github.com/JointOps/hitlimit-monorepo)** | **[npm](https://www.npmjs.com/package/@joint-ops/hitlimit-bun)**
 
-## ⚡ Why hitlimit-bun?
+## Why hitlimit-bun?
 
-**Memory-first for maximum performance.** ~15x faster than SQLite.
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                                                                 │
-│  Memory (v1.1+)     ██████████████████████████████  5.62M ops/s │
-│  SQLite (v1.0)      █░░░░░░░░░░░░░░░░░░░░░░░░░░░░  383K ops/s  │
-│                                                                 │
-│  ~15x performance improvement with memory default (10K IPs)    │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-- **🚀 Memory-First** - 5.62M ops/sec under real-world load (v1.1+), ~15x faster than SQLite
-- **Bun Native** - Built specifically for Bun's runtime, not a Node.js port
-- **Zero Config** - Works out of the box with sensible defaults
-- **Framework Support** - First-class Elysia and Hono integration
-- **Optional Persistence** - SQLite (383K ops/sec) or Redis (6.6K ops/sec) when needed
-- **TypeScript First** - Full type safety and IntelliSense support
-- **Auto-Ban** - Automatically ban repeat offenders after threshold violations
-- **Shared Limits** - Group rate limits via groupId for teams/tenants
-- **Tiny Footprint** - ~18KB core bundle, zero runtime dependencies
+- **5.62M ops/sec** under real-world load (10K IPs), ~15x faster than SQLite
+- **Bun native** — built for Bun's runtime, not a Node.js port
+- **3 frameworks** — Bun.serve, Elysia, Hono from one package
+- **3 storage backends** — Memory, bun:sqlite, Redis (atomic Lua scripts)
+- **Atomic Redis** — Single-roundtrip Lua scripts with EVALSHA caching
+- **Zero runtime dependencies** — nothing extra to install
+- **Human-readable windows** — `'1m'`, `'15m'`, `'1h'` instead of milliseconds
+- **Tiered limits** — Free/Pro/Enterprise in 8 lines
+- **Auto-ban** — Ban repeat offenders after threshold violations
+- **TypeScript native** — Full type safety and IntelliSense
 
 ## Installation
 
@@ -304,7 +292,7 @@ Bun.serve({
 
 ### Redis Store
 
-For distributed systems and multi-server deployments.
+For distributed systems and multi-server deployments. Uses atomic Lua scripts — single-roundtrip with EVALSHA caching.
 
 ```typescript
 import { hitlimit } from '@joint-ops/hitlimit-bun'
@@ -352,13 +340,13 @@ Retry-After: 42
 
 hitlimit-bun is optimized for Bun's runtime with native performance:
 
-### Store Benchmarks (Bun 1.3)
+### Store Benchmarks
 
 | Store | Operations/sec | vs Node.js |
 |-------|----------------|------------|
 | **Memory** | 5,620,000+ | +68% faster |
 | **bun:sqlite** | 383,000+ | ~same |
-| **Redis** | 6,600+ | ~same |
+| **Redis** | 6,800+ | ~same |
 
 ### HTTP Throughput
 
@@ -367,7 +355,7 @@ hitlimit-bun is optimized for Bun's runtime with native performance:
 | **Bun.serve** | 105,000 req/s | 12% |
 | **Elysia** | 115,000 req/s | 11% |
 
-> **Note:** Benchmark results vary by hardware and environment. Run your own benchmarks to see results on your specific setup.
+> **Note:** These are our benchmarks and we've done our best to keep them fair and reproducible. Results vary by hardware and environment — clone the repo and run them yourself. They're not set in stone — if you find issues or have suggestions for improvement, please open an issue or PR.
 
 ### Why bun:sqlite is So Fast
 
@@ -421,7 +409,7 @@ new Elysia()
 
 ## Related Packages
 
-- [@joint-ops/hitlimit](https://www.npmjs.com/package/@joint-ops/hitlimit) - Node.js rate limiting for Express, NestJS
+- [@joint-ops/hitlimit](https://www.npmjs.com/package/@joint-ops/hitlimit) - Node.js rate limiting for Express, Fastify, Hono, NestJS
 
 ## Why Not Use Node.js Rate Limiters in Bun?
 
@@ -429,14 +417,11 @@ Node.js rate limiters like express-rate-limit use better-sqlite3 which relies on
 
 **hitlimit-bun** is built specifically for Bun:
 - Uses native `bun:sqlite` (no N-API overhead)
+- Atomic Redis Lua scripts for distributed deployments
 - No FFI overhead or Node.js polyfills
-- First-class Elysia framework support
-- Optimized for Bun.serve's request handling
+- First-class Bun.serve, Elysia, and Hono support
 
 ## License
 
 MIT - Use freely in personal and commercial projects.
 
-## Keywords
-
-bun rate limit, bun rate limiter, bun middleware, bun api, bun server, bun serve, bun framework, bun native, bun sqlite, elysia rate limit, elysia plugin, elysia middleware, elysia throttle, elysia framework, api rate limiting, throttle requests, request throttling, bun api protection, ddos protection, brute force protection, login protection, redis rate limit, high performance rate limit, fast rate limiter, sliding window, fixed window, rate-limiter-flexible bun, express-rate-limit bun, bun http, bun backend, bun rest api

package/dist/core/limiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"limiter.d.ts","sourceRoot":"","sources":["../../src/core/limiter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,cAAc,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAM7F,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;CAChB;AAsCD,wBAAsB,cAAc,CAAC,QAAQ,EAC3C,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,EAChC,GAAG,EAAE,QAAQ,GACZ,OAAO,CAAC,UAAU,CAAC,CA8CrB;AAGD,wBAAsB,UAAU,CAAC,QAAQ,EACvC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,EAChC,GAAG,EAAE,QAAQ,GACZ,OAAO,CAAC,cAAc,CAAC,CA6EzB"}
+{"version":3,"file":"limiter.d.ts","sourceRoot":"","sources":["../../src/core/limiter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,cAAc,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAM7F,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;CAChB;AAsCD,wBAAsB,cAAc,CAAC,QAAQ,EAC3C,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,EAChC,GAAG,EAAE,QAAQ,GACZ,OAAO,CAAC,UAAU,CAAC,CAgErB;AAGD,wBAAsB,UAAU,CAAC,QAAQ,EACvC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,EAChC,GAAG,EAAE,QAAQ,GACZ,OAAO,CAAC,cAAc,CAAC,CA2GzB"}

package/dist/elysia.js

@@ -202,6 +202,49 @@ async function checkLimit(config, req) {
     tierName = await config.tier(req);
   }
   const { limit, windowMs } = resolveTier(config, tierName);
+  if (limit === Infinity) {
+    return {
+      allowed: true,
+      info: { limit, remaining: Infinity, resetIn: 0, resetAt: 0, key, tier: tierName, group: groupId },
+      headers: {},
+      body: {}
+    };
+  }
+  if (config.ban && config.store.hitWithBan) {
+    const r = await config.store.hitWithBan(key, windowMs, limit, config.ban.threshold, config.ban.durationMs);
+    if (r.banned && r.count === 0) {
+      const info3 = {
+        limit,
+        remaining: 0,
+        resetIn: Math.ceil((r.banExpiresAt - Date.now()) / 1000),
+        resetAt: r.banExpiresAt,
+        key,
+        tier: tierName,
+        banned: true,
+        banExpiresAt: r.banExpiresAt,
+        group: groupId
+      };
+      return { allowed: false, info: info3, headers: buildHeaders(info3, config.headers, false), body: buildBody(config.response, info3) };
+    }
+    const now2 = Date.now();
+    const allowed2 = r.count <= limit;
+    const info2 = {
+      limit,
+      remaining: Math.max(0, limit - r.count),
+      resetIn: Math.max(0, Math.ceil((r.resetAt - now2) / 1000)),
+      resetAt: r.resetAt,
+      key,
+      tier: tierName,
+      group: groupId
+    };
+    if (r.violations > 0)
+      info2.violations = r.violations;
+    if (r.banned) {
+      info2.banned = true;
+      info2.banExpiresAt = r.banExpiresAt;
+    }
+    return { allowed: allowed2, info: info2, headers: buildHeaders(info2, config.headers, allowed2), body: allowed2 ? {} : buildBody(config.response, info2) };
+  }
   if (config.ban && config.store.isBanned) {
     const banned = await config.store.isBanned(key);
     if (banned) {
@@ -225,14 +268,6 @@ async function checkLimit(config, req) {
       };
     }
   }
-  if (limit === Infinity) {
-    return {
-      allowed: true,
-      info: { limit, remaining: Infinity, resetIn: 0, resetAt: 0, key, tier: tierName, group: groupId },
-      headers: {},
-      body: {}
-    };
-  }
   const result = await config.store.hit(key, windowMs, limit);
   const now = Date.now();
   const resetIn = Math.max(0, Math.ceil((result.resetAt - now) / 1000));

package/dist/hono.js

@@ -202,6 +202,49 @@ async function checkLimit(config, req) {
     tierName = await config.tier(req);
   }
   const { limit, windowMs } = resolveTier(config, tierName);
+  if (limit === Infinity) {
+    return {
+      allowed: true,
+      info: { limit, remaining: Infinity, resetIn: 0, resetAt: 0, key, tier: tierName, group: groupId },
+      headers: {},
+      body: {}
+    };
+  }
+  if (config.ban && config.store.hitWithBan) {
+    const r = await config.store.hitWithBan(key, windowMs, limit, config.ban.threshold, config.ban.durationMs);
+    if (r.banned && r.count === 0) {
+      const info3 = {
+        limit,
+        remaining: 0,
+        resetIn: Math.ceil((r.banExpiresAt - Date.now()) / 1000),
+        resetAt: r.banExpiresAt,
+        key,
+        tier: tierName,
+        banned: true,
+        banExpiresAt: r.banExpiresAt,
+        group: groupId
+      };
+      return { allowed: false, info: info3, headers: buildHeaders(info3, config.headers, false), body: buildBody(config.response, info3) };
+    }
+    const now2 = Date.now();
+    const allowed2 = r.count <= limit;
+    const info2 = {
+      limit,
+      remaining: Math.max(0, limit - r.count),
+      resetIn: Math.max(0, Math.ceil((r.resetAt - now2) / 1000)),
+      resetAt: r.resetAt,
+      key,
+      tier: tierName,
+      group: groupId
+    };
+    if (r.violations > 0)
+      info2.violations = r.violations;
+    if (r.banned) {
+      info2.banned = true;
+      info2.banExpiresAt = r.banExpiresAt;
+    }
+    return { allowed: allowed2, info: info2, headers: buildHeaders(info2, config.headers, allowed2), body: allowed2 ? {} : buildBody(config.response, info2) };
+  }
   if (config.ban && config.store.isBanned) {
     const banned = await config.store.isBanned(key);
     if (banned) {
@@ -225,14 +268,6 @@ async function checkLimit(config, req) {
       };
     }
   }
-  if (limit === Infinity) {
-    return {
-      allowed: true,
-      info: { limit, remaining: Infinity, resetIn: 0, resetAt: 0, key, tier: tierName, group: groupId },
-      headers: {},
-      body: {}
-    };
-  }
   const result = await config.store.hit(key, windowMs, limit);
   const now = Date.now();
   const resetIn = Math.max(0, Math.ceil((result.resetAt - now) / 1000));

package/dist/index.js

@@ -199,6 +199,49 @@ async function checkLimit(config, req) {
     tierName = await config.tier(req);
   }
   const { limit, windowMs } = resolveTier(config, tierName);
+  if (limit === Infinity) {
+    return {
+      allowed: true,
+      info: { limit, remaining: Infinity, resetIn: 0, resetAt: 0, key, tier: tierName, group: groupId },
+      headers: {},
+      body: {}
+    };
+  }
+  if (config.ban && config.store.hitWithBan) {
+    const r = await config.store.hitWithBan(key, windowMs, limit, config.ban.threshold, config.ban.durationMs);
+    if (r.banned && r.count === 0) {
+      const info3 = {
+        limit,
+        remaining: 0,
+        resetIn: Math.ceil((r.banExpiresAt - Date.now()) / 1000),
+        resetAt: r.banExpiresAt,
+        key,
+        tier: tierName,
+        banned: true,
+        banExpiresAt: r.banExpiresAt,
+        group: groupId
+      };
+      return { allowed: false, info: info3, headers: buildHeaders(info3, config.headers, false), body: buildBody(config.response, info3) };
+    }
+    const now2 = Date.now();
+    const allowed2 = r.count <= limit;
+    const info2 = {
+      limit,
+      remaining: Math.max(0, limit - r.count),
+      resetIn: Math.max(0, Math.ceil((r.resetAt - now2) / 1000)),
+      resetAt: r.resetAt,
+      key,
+      tier: tierName,
+      group: groupId
+    };
+    if (r.violations > 0)
+      info2.violations = r.violations;
+    if (r.banned) {
+      info2.banned = true;
+      info2.banExpiresAt = r.banExpiresAt;
+    }
+    return { allowed: allowed2, info: info2, headers: buildHeaders(info2, config.headers, allowed2), body: allowed2 ? {} : buildBody(config.response, info2) };
+  }
   if (config.ban && config.store.isBanned) {
     const banned = await config.store.isBanned(key);
     if (banned) {
@@ -222,14 +265,6 @@ async function checkLimit(config, req) {
       };
     }
   }
-  if (limit === Infinity) {
-    return {
-      allowed: true,
-      info: { limit, remaining: Infinity, resetIn: 0, resetAt: 0, key, tier: tierName, group: groupId },
-      headers: {},
-      body: {}
-    };
-  }
   const result = await config.store.hit(key, windowMs, limit);
   const now = Date.now();
   const resetIn = Math.max(0, Math.ceil((result.resetAt - now) / 1000));

package/dist/stores/redis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../src/stores/redis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,2BAA2B,CAAA;AAG3E,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAqED,wBAAgB,UAAU,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,aAAa,CAErE"}
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../src/stores/redis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,2BAA2B,CAAA;AAG7F,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA6KD,wBAAgB,UAAU,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,aAAa,CAErE"}

package/dist/stores/redis.js

@@ -1,30 +1,121 @@
 // @bun
 // src/stores/redis.ts
 import Redis from "ioredis";
+var HIT_SCRIPT = `
+local key = KEYS[1]
+local windowMs = tonumber(ARGV[1])
+local count = redis.call('INCR', key)
+local ttl = redis.call('PTTL', key)
+if ttl < 0 then
+  redis.call('PEXPIRE', key, windowMs)
+  ttl = windowMs
+end
+return {count, ttl}
+`;
+var HIT_WITH_BAN_SCRIPT = `
+local hitKey = KEYS[1]
+local banKey = KEYS[2]
+local violationKey = KEYS[3]
+local windowMs = tonumber(ARGV[1])
+local limit = tonumber(ARGV[2])
+local banThreshold = tonumber(ARGV[3])
+local banDurationMs = tonumber(ARGV[4])
+
+-- Check ban first
+local banTTL = redis.call('PTTL', banKey)
+if banTTL > 0 then
+  return {-1, banTTL, 1, 0}
+end
+
+-- Hit counter
+local count = redis.call('INCR', hitKey)
+local ttl = redis.call('PTTL', hitKey)
+if ttl < 0 then
+  redis.call('PEXPIRE', hitKey, windowMs)
+  ttl = windowMs
+end
+
+-- Track violations if over limit
+local banned = 0
+local violations = 0
+if count > limit then
+  violations = redis.call('INCR', violationKey)
+  local vTTL = redis.call('PTTL', violationKey)
+  if vTTL < 0 then
+    redis.call('PEXPIRE', violationKey, banDurationMs)
+  end
+  if violations >= banThreshold then
+    redis.call('SET', banKey, '1', 'PX', banDurationMs)
+    banned = 1
+  end
+end
+return {count, ttl, banned, violations}
+`;
 
 class RedisStore {
   redis;
   prefix;
   banPrefix;
   violationPrefix;
+  hitSHA = null;
+  hitWithBanSHA = null;
   constructor(options = {}) {
     this.redis = new Redis(options.url ?? "redis://localhost:6379");
     this.prefix = options.keyPrefix ?? "hitlimit:";
     this.banPrefix = (options.keyPrefix ?? "hitlimit:") + "ban:";
     this.violationPrefix = (options.keyPrefix ?? "hitlimit:") + "violations:";
   }
+  async loadScripts() {
+    if (!this.hitSHA) {
+      this.hitSHA = await this.redis.script("LOAD", HIT_SCRIPT);
+    }
+    if (!this.hitWithBanSHA) {
+      this.hitWithBanSHA = await this.redis.script("LOAD", HIT_WITH_BAN_SCRIPT);
+    }
+  }
+  async evalScript(sha, script, keys, args) {
+    try {
+      return await this.redis.evalsha(sha, keys.length, ...keys, ...args);
+    } catch (err) {
+      if (err.message && err.message.includes("NOSCRIPT")) {
+        const newSHA = await this.redis.script("LOAD", script);
+        if (script === HIT_SCRIPT)
+          this.hitSHA = newSHA;
+        else if (script === HIT_WITH_BAN_SCRIPT)
+          this.hitWithBanSHA = newSHA;
+        return await this.redis.evalsha(newSHA, keys.length, ...keys, ...args);
+      }
+      throw err;
+    }
+  }
   async hit(key, windowMs, _limit) {
+    await this.loadScripts();
     const redisKey = this.prefix + key;
-    const now = Date.now();
-    const results = await this.redis.multi().incr(redisKey).pttl(redisKey).exec();
-    const count = results[0][1];
-    let ttl = results[1][1];
-    if (ttl < 0) {
-      await this.redis.pexpire(redisKey, windowMs);
-      ttl = windowMs;
+    const result = await this.evalScript(this.hitSHA, HIT_SCRIPT, [redisKey], [windowMs]);
+    const count = result[0];
+    const ttl = result[1];
+    return { count, resetAt: Date.now() + ttl };
+  }
+  async hitWithBan(key, windowMs, limit, banThreshold, banDurationMs) {
+    await this.loadScripts();
+    const hitKey = this.prefix + key;
+    const banKey = this.banPrefix + key;
+    const violationKey = this.violationPrefix + key;
+    const result = await this.evalScript(this.hitWithBanSHA, HIT_WITH_BAN_SCRIPT, [hitKey, banKey, violationKey], [windowMs, limit, banThreshold, banDurationMs]);
+    const count = result[0];
+    const ttl = result[1];
+    const banned = result[2] === 1;
+    const violations = result[3];
+    if (count === -1) {
+      return { count: 0, resetAt: Date.now() + ttl, banned: true, violations: 0, banExpiresAt: Date.now() + ttl };
     }
-    const resetAt = now + ttl;
-    return { count, resetAt };
+    return {
+      count,
+      resetAt: Date.now() + ttl,
+      banned,
+      violations,
+      banExpiresAt: banned ? Date.now() + banDurationMs : 0
+    };
   }
   async isBanned(key) {
     const result = await this.redis.exists(this.banPrefix + key);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joint-ops/hitlimit-bun",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Ultra-fast Bun-native rate limiting - Memory-first with 6M+ ops/sec for Bun.serve, Elysia & Hono",
   "author": {
     "name": "Shayan M Hussain",
@@ -117,7 +117,7 @@
     "test:watch": "bun test --watch"
   },
   "dependencies": {
-    "@joint-ops/hitlimit-types": "1.1.2"
+    "@joint-ops/hitlimit-types": "1.1.3"
   },
   "peerDependencies": {
     "elysia": ">=1.0.0",