@talak-web3/rate-limit 1.0.1

package/README.md

@@ -0,0 +1,98 @@
+# @talak-web3/rate-limit
+
+Rate limiting utilities for talak-web3 with both in-memory and Redis-backed implementations.
+
+## Installation
+
+```bash
+npm install @talak-web3/rate-limit
+# or
+yarn add @talak-web3/rate-limit
+# or
+pnpm add @talak-web3/rate-limit
+```
+
+## Usage
+
+### In-Memory (Development/Testing)
+
+```typescript
+import { createRateLimiter } from '@talak-web3/rate-limit';
+
+const limiter = createRateLimiter({
+  type: 'memory',
+  capacity: 10,           // Max 10 requests
+  refillPerSecond: 1,     // Refill 1 token per second
+});
+
+const result = await limiter.check('user:123');
+if (result.allowed) {
+  console.log(`Allowed! ${result.remaining} requests remaining`);
+} else {
+  console.log(`Rate limited. Try again at ${new Date(result.resetAt!).toISOString()}`);
+}
+```
+
+### Redis (Production)
+
+```typescript
+import Redis from 'ioredis';
+import { createRateLimiter } from '@talak-web3/rate-limit';
+
+const redis = new Redis(process.env.REDIS_URL);
+
+const limiter = createRateLimiter({
+  type: 'redis',
+  redis,
+  capacity: 100,          // Max 100 requests
+  refillPerSecond: 10,    // Refill 10 tokens per second
+});
+
+const result = await limiter.check('ip:192.168.1.1');
+```
+
+## API
+
+### `createRateLimiter(opts)`
+
+Factory function that returns a rate limiter instance.
+
+#### Options
+
+- `type`: `'memory'` or `'redis'`
+- `capacity`: Maximum number of requests allowed
+- `refillPerSecond`: Rate at which tokens are refilled
+- `redis`: Redis client instance (required for `type: 'redis'`)
+
+### `RateLimiter` Interface
+
+```typescript
+interface RateLimiter {
+  check(key: string, cost?: number): Promise<RateLimitResult>;
+  reset(key: string): Promise<void>;
+}
+
+interface RateLimitResult {
+  allowed: boolean;
+  remaining: number;
+  resetAt?: number;  // Timestamp when limit resets
+}
+```
+
+## Algorithms
+
+### Token Bucket (In-Memory)
+
+- Simple token bucket algorithm
+- Tokens refill at a constant rate
+- Good for single-process applications
+
+### Sliding Window (Redis)
+
+- Uses Redis sorted sets for precise rate limiting
+- Works across multiple processes/servers
+- Atomic operations via Lua scripts
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@talak-web3/rate-limit",
+  "version": "1.0.1",
+  "description": "Rate limiting utilities for talak-web3",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node build-simple.cjs",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "ioredis": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "rate-limit",
+    "token-bucket",
+    "sliding-window",
+    "web3"
+  ],
+  "author": "Dagim Abebe",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dagimabebe/talak-web3.git",
+    "directory": "packages/talak-web3-rate-limit"
+  }
+}