bucketflow 1.0.1 → 1.0.2

package/README.md

@@ -8,47 +8,94 @@ Lightweight in-memory rate limiting utilities for Node.js and TypeScript.
 npm install bucketflow
 ```
 
-## Usage
+## Public exports
 
-### Token bucket
+`src/index.ts` currently exports these three classes:
+
+```ts
+export { FixedWindow } from "./fixed-window";
+export { TokenBucket } from "./token-bucket";
+export { SlidingWindow } from "./sliding-window";
+```
+
+Each limiter stores its counters in memory and exposes a `checkLimit(key)`
+method. The `key` identifies the client, user, IP address, API key, or any
+other group that should have its own limit.
+
+## Using the limiters
+
+### `TokenBucket`
 
 ```ts
 import { TokenBucket } from "bucketflow";
 
-const limiter = new TokenBucket(10, 1000);
+const limiter = new TokenBucket(10, 1_000);
 const result = limiter.checkLimit("user-123");
 
-if (!result.allowed) {
-  console.log(result.message);
-}
+console.log(result);
+// { allowed: true, message: "Too many requests", tokens: 9 }
+```
+
+Constructor:
+
+```ts
+new TokenBucket(capacity, refillRate, message?)
 ```
 
-The constructor accepts `capacity`, `refillRate` in milliseconds, and an
-optional rejection message.
+- `capacity`: maximum number of tokens.
+- `refillRate`: milliseconds between token refills.
+- `message`: optional message returned when a request is rejected.
+
+`checkLimit(key)` returns `{ allowed, message, tokens }`.
 
-### Fixed window
+### `FixedWindow`
 
 ```ts
 import { FixedWindow } from "bucketflow";
 
-const limiter = new FixedWindow(100, 60_000);
+const limiter = new FixedWindow(100, 60_000, "Too many requests");
 const result = limiter.checkLimit("user-123");
+
+console.log(result);
+// { allowed: true, reqRemaining: 99, message: "Too many requests" }
+```
+
+Constructor:
+
+```ts
+new FixedWindow(maxNum, window, message?)
 ```
 
-The constructor accepts the maximum number of requests, the window duration
-in milliseconds, and an optional rejection message.
+- `maxNum`: maximum number of requests in the window.
+- `window`: window duration in milliseconds.
+- `message`: optional message returned when a request is rejected.
 
-### Sliding window
+`checkLimit(key)` returns `{ allowed, reqRemaining, message }`.
+
+### `SlidingWindow`
 
 ```ts
 import { SlidingWindow } from "bucketflow";
 
-const limiter = new SlidingWindow(60_000, 1_000, 100);
+const limiter = new SlidingWindow(60_000, 1_000, 100, "Too many requests");
 const result = limiter.checkLimit("user-123");
+
+console.log(result);
+// { allowed: true, counter: 1, message: "Too many requests" }
 ```
 
-The constructor accepts the window duration, refresh rate, maximum requests,
-and an optional rejection message. Durations and rates are in milliseconds.
+Constructor:
+
+```ts
+new SlidingWindow(window, refreshRate, maxRequests, message?)
+```
+
+- `window`: window duration in milliseconds.
+- `refreshRate`: counter refresh interval in milliseconds.
+- `maxRequests`: maximum requests tracked by the limiter.
+- `message`: optional message returned when a request is rejected.
+
+`checkLimit(key)` returns `{ allowed, counter, message }`.
 
 ## Return values
 
@@ -86,6 +133,15 @@ app.use((req, res, next) => {
 });
 ```
 
+You can use `FixedWindow` or `SlidingWindow` in the same middleware by
+replacing the limiter construction:
+
+```ts
+const limiter = new FixedWindow(100, 60_000);
+// or
+const limiter = new SlidingWindow(60_000, 1_000, 100);
+```
+
 ### Fastify
 
 Fastify can use a limiter in a `preHandler` hook:
@@ -140,13 +196,13 @@ export class RateLimitMiddleware implements NestMiddleware {
 Register the middleware in a module with `MiddlewareConsumer`, or adapt the
 same pattern into a NestJS guard when route-level control is preferred.
 
-## API
-
-The package currently exports these classes:
+The same middleware pattern works with `FixedWindow` and `SlidingWindow`:
 
-- `TokenBucket`
-- `FixedWindow`
-- `SlidingWindow`
+```ts
+private readonly limiter = new FixedWindow(100, 60_000);
+// or
+private readonly limiter = new SlidingWindow(60_000, 1_000, 100);
+```
 
 All limiters are in-memory and local to the running process. They do not share
 state across multiple Node.js processes or servers, and state is lost when the

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./fixed-window";
 export * from "./token-bucket";
 export * from "./sliding-window";
+export * from "./leaky-bucket";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   FixedWindow: () => FixedWindow,
+  LeakyBucket: () => LeakyBucket,
   SlidingWindow: () => SlidingWindow,
   TokenBucket: () => TokenBucket
 });
@@ -159,9 +160,31 @@ var SlidingWindow = class {
     };
   }
 };
+
+// src/leaky-bucket.ts
+var LeakyBucket = class {
+  constructor(capacity, leakRate) {
+    this.capacity = capacity;
+    this.queue = [];
+    this.leakRate = leakRate;
+  }
+  addRequest(req) {
+    if (this.queue.length >= this.capacity) {
+      return false;
+    }
+    this.queue.push(req);
+    return true;
+  }
+  leak() {
+    if (this.queue.length > 0) {
+      this.queue.shift();
+    }
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FixedWindow,
+  LeakyBucket,
   SlidingWindow,
   TokenBucket
 });

package/dist/index.mjs

@@ -131,8 +131,30 @@ var SlidingWindow = class {
     };
   }
 };
+
+// src/leaky-bucket.ts
+var LeakyBucket = class {
+  constructor(capacity, leakRate) {
+    this.capacity = capacity;
+    this.queue = [];
+    this.leakRate = leakRate;
+  }
+  addRequest(req) {
+    if (this.queue.length >= this.capacity) {
+      return false;
+    }
+    this.queue.push(req);
+    return true;
+  }
+  leak() {
+    if (this.queue.length > 0) {
+      this.queue.shift();
+    }
+  }
+};
 export {
   FixedWindow,
+  LeakyBucket,
   SlidingWindow,
   TokenBucket
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bucketflow",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Rate limiting for Node.js with token bucket, fixed window, and leaky bucket algorithms",
   "main": "dist/index.js",
   "keywords": [