@joint-ops/hitlimit-bun 1.2.0 → 1.3.0

package/README.md

@@ -94,10 +94,19 @@ new Elysia()
 
 ---
 
-## 4 Storage Backends
+## 6 Storage Backends
 
 All built in. No extra packages to install.
 
+| Store | Best For | Peer Dependency |
+|---|---|---|
+| Memory | Development, single server | None |
+| bun:sqlite | Single server + persistence | None (built-in) |
+| Redis | Distributed, production | `ioredis` |
+| **Valkey** | **Distributed, open-source Redis alternative** | `ioredis` |
+| **DragonflyDB** | **High-throughput distributed** | `ioredis` |
+| PostgreSQL | Shared database infrastructure | `pg` |
+
 ```typescript
 import { hitlimit } from '@joint-ops/hitlimit-bun'
 
@@ -112,6 +121,14 @@ Bun.serve({ fetch: hitlimit({ store: sqliteStore({ path: './ratelimit.db' }) },
 import { redisStore } from '@joint-ops/hitlimit-bun/stores/redis'
 Bun.serve({ fetch: hitlimit({ store: redisStore({ url: 'redis://localhost:6379' }) }, handler) })
 
+// Valkey — open-source Redis alternative
+import { valkeyStore } from '@joint-ops/hitlimit-bun/stores/valkey'
+Bun.serve({ fetch: hitlimit({ store: valkeyStore({ url: 'redis://localhost:6379' }) }, handler) })
+
+// DragonflyDB — high-throughput Redis alternative
+import { dragonflyStore } from '@joint-ops/hitlimit-bun/stores/dragonfly'
+Bun.serve({ fetch: hitlimit({ store: dragonflyStore({ url: 'redis://localhost:6379' }) }, handler) })
+
 // Postgres — distributed, atomic upserts
 import { postgresStore } from '@joint-ops/hitlimit-bun/stores/postgres'
 Bun.serve({ fetch: hitlimit({ store: postgresStore({ url: 'postgres://localhost:5432/mydb' }) }, handler) })
@@ -124,6 +141,34 @@ Bun.serve({ fetch: hitlimit({ store: postgresStore({ url: 'postgres://localhost:
 | Redis | 6,700 | 148μs | Multi-server / distributed |
 | Postgres | 3,700 | 273μs | Multi-server / already using Postgres |
 
+### Valkey (Redis Alternative)
+```typescript
+import { hitlimit } from '@joint-ops/hitlimit-bun'
+import { valkeyStore } from '@joint-ops/hitlimit-bun/stores/valkey'
+
+Bun.serve({
+  fetch: hitlimit({
+    store: valkeyStore({ url: 'redis://localhost:6379' }),
+    limit: 100,
+    window: '1m'
+  }, handler)
+})
+```
+
+### DragonflyDB
+```typescript
+import { hitlimit } from '@joint-ops/hitlimit-bun'
+import { dragonflyStore } from '@joint-ops/hitlimit-bun/stores/dragonfly'
+
+Bun.serve({
+  fetch: hitlimit({
+    store: dragonflyStore({ url: 'redis://localhost:6379' }),
+    limit: 100,
+    window: '1m'
+  }, handler)
+})
+```
+
 ---
 
 ## Performance

package/dist/stores/dragonfly.d.ts

@@ -0,0 +1,9 @@
+import type { HitLimitStore } from '@joint-ops/hitlimit-types';
+export interface DragonflyStoreOptions {
+    /** DragonflyDB connection URL. Default: 'redis://localhost:6379' */
+    url?: string;
+    /** Key prefix for all rate limit keys. Default: 'hitlimit:' */
+    keyPrefix?: string;
+}
+export declare function dragonflyStore(options?: DragonflyStoreOptions): HitLimitStore;
+//# sourceMappingURL=dragonfly.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dragonfly.d.ts","sourceRoot":"","sources":["../../src/stores/dragonfly.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAG9D,MAAM,WAAW,qBAAqB;IACpC,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,aAAa,CAE7E"}

package/dist/stores/dragonfly.js

@@ -0,0 +1,133 @@
+// @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;
+  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:";
+    this.redis.defineCommand("hitlimitHit", {
+      numberOfKeys: 1,
+      lua: HIT_SCRIPT
+    });
+    this.redis.defineCommand("hitlimitHitWithBan", {
+      numberOfKeys: 3,
+      lua: HIT_WITH_BAN_SCRIPT
+    });
+  }
+  async hit(key, windowMs, _limit) {
+    const redisKey = this.prefix + key;
+    const result = await this.redis.hitlimitHit(redisKey, windowMs);
+    const count = result[0];
+    const ttl = result[1];
+    return { count, resetAt: Date.now() + ttl };
+  }
+  async hitWithBan(key, windowMs, limit, banThreshold, banDurationMs) {
+    const hitKey = this.prefix + key;
+    const banKey = this.banPrefix + key;
+    const violationKey = this.violationPrefix + key;
+    const result = await this.redis.hitlimitHitWithBan(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 };
+    }
+    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);
+    return result === 1;
+  }
+  async ban(key, durationMs) {
+    await this.redis.set(this.banPrefix + key, "1", "PX", durationMs);
+  }
+  async recordViolation(key, windowMs) {
+    const redisKey = this.violationPrefix + key;
+    const count = await this.redis.incr(redisKey);
+    if (count === 1) {
+      await this.redis.pexpire(redisKey, windowMs);
+    }
+    return count;
+  }
+  async reset(key) {
+    await this.redis.del(this.prefix + key, this.banPrefix + key, this.violationPrefix + key);
+  }
+  async shutdown() {
+    await this.redis.quit();
+  }
+}
+function redisStore(options) {
+  return new RedisStore(options);
+}
+
+// src/stores/dragonfly.ts
+function dragonflyStore(options) {
+  return new RedisStore(options);
+}
+export {
+  dragonflyStore
+};

package/dist/stores/redis.d.ts

@@ -1,7 +1,23 @@
-import type { HitLimitStore } from '@joint-ops/hitlimit-types';
+import type { HitLimitStore, HitWithBanResult, StoreResult } from '@joint-ops/hitlimit-types';
 export interface RedisStoreOptions {
     url?: string;
     keyPrefix?: string;
 }
+export declare const HIT_SCRIPT = "\nlocal key = KEYS[1]\nlocal windowMs = tonumber(ARGV[1])\nlocal count = redis.call('INCR', key)\nlocal ttl = redis.call('PTTL', key)\nif ttl < 0 then\n  redis.call('PEXPIRE', key, windowMs)\n  ttl = windowMs\nend\nreturn {count, ttl}\n";
+export declare const HIT_WITH_BAN_SCRIPT = "\nlocal hitKey = KEYS[1]\nlocal banKey = KEYS[2]\nlocal violationKey = KEYS[3]\nlocal windowMs = tonumber(ARGV[1])\nlocal limit = tonumber(ARGV[2])\nlocal banThreshold = tonumber(ARGV[3])\nlocal banDurationMs = tonumber(ARGV[4])\n\n-- Check ban first\nlocal banTTL = redis.call('PTTL', banKey)\nif banTTL > 0 then\n  return {-1, banTTL, 1, 0}\nend\n\n-- Hit counter\nlocal count = redis.call('INCR', hitKey)\nlocal ttl = redis.call('PTTL', hitKey)\nif ttl < 0 then\n  redis.call('PEXPIRE', hitKey, windowMs)\n  ttl = windowMs\nend\n\n-- Track violations if over limit\nlocal banned = 0\nlocal violations = 0\nif count > limit then\n  violations = redis.call('INCR', violationKey)\n  local vTTL = redis.call('PTTL', violationKey)\n  if vTTL < 0 then\n    redis.call('PEXPIRE', violationKey, banDurationMs)\n  end\n  if violations >= banThreshold then\n    redis.call('SET', banKey, '1', 'PX', banDurationMs)\n    banned = 1\n  end\nend\nreturn {count, ttl, banned, violations}\n";
+export declare class RedisStore implements HitLimitStore {
+    private redis;
+    private prefix;
+    private banPrefix;
+    private violationPrefix;
+    constructor(options?: RedisStoreOptions);
+    hit(key: string, windowMs: number, _limit: number): Promise<StoreResult>;
+    hitWithBan(key: string, windowMs: number, limit: number, banThreshold: number, banDurationMs: number): Promise<HitWithBanResult>;
+    isBanned(key: string): Promise<boolean>;
+    ban(key: string, durationMs: number): Promise<void>;
+    recordViolation(key: string, windowMs: number): Promise<number>;
+    reset(key: string): Promise<void>;
+    shutdown(): Promise<void>;
+}
 export declare function redisStore(options?: RedisStoreOptions): HitLimitStore;
 //# sourceMappingURL=redis.d.ts.map

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,EAAiC,MAAM,2BAA2B,CAAA;AAG7F,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAmJD,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,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAG7F,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAGD,eAAO,MAAM,UAAU,iPAUtB,CAAA;AAGD,eAAO,MAAM,mBAAmB,s9BAsC/B,CAAA;AAED,qBAAa,UAAW,YAAW,aAAa;IAC9C,OAAO,CAAC,KAAK,CAAO;IACpB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,eAAe,CAAQ;gBAEnB,OAAO,GAAE,iBAAsB;IAiBrC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IASxE,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA4BhI,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKvC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAS/D,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQjC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGhC;AAED,wBAAgB,UAAU,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,aAAa,CAErE"}

package/dist/stores/redis.js

@@ -124,5 +124,8 @@ function redisStore(options) {
   return new RedisStore(options);
 }
 export {
-  redisStore
+  redisStore,
+  RedisStore,
+  HIT_WITH_BAN_SCRIPT,
+  HIT_SCRIPT
 };

package/dist/stores/valkey.d.ts

@@ -0,0 +1,9 @@
+import type { HitLimitStore } from '@joint-ops/hitlimit-types';
+export interface ValkeyStoreOptions {
+    /** Valkey connection URL. Default: 'redis://localhost:6379' */
+    url?: string;
+    /** Key prefix for all rate limit keys. Default: 'hitlimit:' */
+    keyPrefix?: string;
+}
+export declare function valkeyStore(options?: ValkeyStoreOptions): HitLimitStore;
+//# sourceMappingURL=valkey.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"valkey.d.ts","sourceRoot":"","sources":["../../src/stores/valkey.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAG9D,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,aAAa,CAEvE"}

package/dist/stores/valkey.js

@@ -0,0 +1,133 @@
+// @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;
+  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:";
+    this.redis.defineCommand("hitlimitHit", {
+      numberOfKeys: 1,
+      lua: HIT_SCRIPT
+    });
+    this.redis.defineCommand("hitlimitHitWithBan", {
+      numberOfKeys: 3,
+      lua: HIT_WITH_BAN_SCRIPT
+    });
+  }
+  async hit(key, windowMs, _limit) {
+    const redisKey = this.prefix + key;
+    const result = await this.redis.hitlimitHit(redisKey, windowMs);
+    const count = result[0];
+    const ttl = result[1];
+    return { count, resetAt: Date.now() + ttl };
+  }
+  async hitWithBan(key, windowMs, limit, banThreshold, banDurationMs) {
+    const hitKey = this.prefix + key;
+    const banKey = this.banPrefix + key;
+    const violationKey = this.violationPrefix + key;
+    const result = await this.redis.hitlimitHitWithBan(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 };
+    }
+    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);
+    return result === 1;
+  }
+  async ban(key, durationMs) {
+    await this.redis.set(this.banPrefix + key, "1", "PX", durationMs);
+  }
+  async recordViolation(key, windowMs) {
+    const redisKey = this.violationPrefix + key;
+    const count = await this.redis.incr(redisKey);
+    if (count === 1) {
+      await this.redis.pexpire(redisKey, windowMs);
+    }
+    return count;
+  }
+  async reset(key) {
+    await this.redis.del(this.prefix + key, this.banPrefix + key, this.violationPrefix + key);
+  }
+  async shutdown() {
+    await this.redis.quit();
+  }
+}
+function redisStore(options) {
+  return new RedisStore(options);
+}
+
+// src/stores/valkey.ts
+function valkeyStore(options) {
+  return new RedisStore(options);
+}
+export {
+  valkeyStore
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joint-ops/hitlimit-bun",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Ultra-fast Bun-native rate limiting - Memory-first with 6M+ ops/sec for Bun.serve, Elysia & Hono",
   "author": {
     "name": "Shayan M Hussain",
@@ -86,7 +86,13 @@
     "bun-framework",
     "lightweight",
     "zero-dependency",
-    "esm"
+    "esm",
+    "valkey",
+    "valkey-rate-limit",
+    "dragonfly",
+    "dragonflydb",
+    "dragonfly-rate-limit",
+    "redis-alternative"
   ],
   "type": "module",
   "main": "./dist/index.js",
@@ -127,6 +133,16 @@
       "types": "./dist/stores/postgres.d.ts",
       "bun": "./dist/stores/postgres.js",
       "import": "./dist/stores/postgres.js"
+    },
+    "./stores/valkey": {
+      "types": "./dist/stores/valkey.d.ts",
+      "bun": "./dist/stores/valkey.js",
+      "import": "./dist/stores/valkey.js"
+    },
+    "./stores/dragonfly": {
+      "types": "./dist/stores/dragonfly.d.ts",
+      "bun": "./dist/stores/dragonfly.js",
+      "import": "./dist/stores/dragonfly.js"
     }
   },
   "files": [
@@ -134,13 +150,13 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "build": "bun build ./src/index.ts ./src/elysia.ts ./src/hono.ts ./src/stores/memory.ts ./src/stores/redis.ts ./src/stores/sqlite.ts ./src/stores/postgres.ts --outdir=./dist --target=bun --external=elysia --external=hono --external=ioredis --external=pg --external=@sinclair/typebox && tsc --emitDeclarationOnly",
+    "build": "bun build ./src/index.ts ./src/elysia.ts ./src/hono.ts ./src/stores/memory.ts ./src/stores/redis.ts ./src/stores/sqlite.ts ./src/stores/postgres.ts ./src/stores/valkey.ts ./src/stores/dragonfly.ts --outdir=./dist --root=./src --target=bun --external=elysia --external=hono --external=ioredis --external=pg --external=@sinclair/typebox && tsc --emitDeclarationOnly",
     "clean": "rm -rf dist",
     "test": "bun test",
     "test:watch": "bun test --watch"
   },
   "dependencies": {
-    "@joint-ops/hitlimit-types": "1.2.0"
+    "@joint-ops/hitlimit-types": "1.3.0"
   },
   "peerDependencies": {
     "elysia": ">=1.0.0",