bucketflow 1.0.0 → 1.0.2

package/README.md

@@ -8,47 +8,103 @@ 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("api", "Too many requests", 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" }
 ```
 
-The constructor accepts a limiter key, optional rejection message, maximum
-requests, and window duration in milliseconds.
+Constructor:
+
+```ts
+new FixedWindow(maxNum, window, message?)
+```
+
+- `maxNum`: maximum number of requests in the window.
+- `window`: window duration in milliseconds.
+- `message`: optional message returned when a request is rejected.
+
+`checkLimit(key)` returns `{ allowed, reqRemaining, message }`.
 
-### Sliding window
+### `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 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
+
+Each limiter returns an object with an `allowed` boolean and a message. The
+additional field depends on the limiter:
+
+- `TokenBucket`: `tokens` is the number of tokens remaining.
+- `FixedWindow`: `reqRemaining` is the reported number of requests remaining.
+- `SlidingWindow`: `counter` is the current request counter.
 
 ## Framework integrations
 
@@ -77,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:
@@ -131,16 +196,17 @@ 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:
+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 are not
-intended to coordinate limits across multiple Node.js processes or servers.
+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
+process restarts.
 
 ## License
 

package/dist/fixed-window.d.ts

@@ -1,11 +1,10 @@
-import { FixedWindowProps, FixedWindowResponse } from "../types";
+import type { FixedWindowProps, FixedWindowResponse } from "../types";
 export declare class FixedWindow implements FixedWindowProps {
-    key: string;
     private store;
     message: string;
     maxNum: number;
     window: number;
-    constructor(key: string, message: string | undefined, maxNum: number, window: number);
+    constructor(maxNum: number, window: number, message?: string);
     checkLimit(key: string): FixedWindowResponse;
 }
 //# sourceMappingURL=fixed-window.d.ts.map

package/dist/fixed-window.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fixed-window.d.ts","sourceRoot":"","sources":["../src/fixed-window.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAS,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAExE,qBAAa,WAAY,YAAW,gBAAgB;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IAEf,YACE,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,YAAsB,EACrC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EAMf;IAED,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CA0C3C;CACF"}
+{"version":3,"file":"fixed-window.d.ts","sourceRoot":"","sources":["../src/fixed-window.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAS,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAE7E,qBAAa,WAAY,YAAW,gBAAgB;IAClD,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IAEf,YACE,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,MAA4B,EAKtC;IACD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CA0C3C;CACF"}

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
 });
@@ -28,9 +29,8 @@ module.exports = __toCommonJS(index_exports);
 
 // src/fixed-window.ts
 var FixedWindow = class {
-  constructor(key, message = "Too many requests", maxNum, window) {
+  constructor(maxNum, window, message = "Too many requests") {
     this.store = /* @__PURE__ */ new Map();
-    this.key = key;
     this.message = message;
     this.maxNum = maxNum;
     this.window = window;
@@ -160,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

@@ -1,8 +1,7 @@
 // src/fixed-window.ts
 var FixedWindow = class {
-  constructor(key, message = "Too many requests", maxNum, window) {
+  constructor(maxNum, window, message = "Too many requests") {
     this.store = /* @__PURE__ */ new Map();
-    this.key = key;
     this.message = message;
     this.maxNum = maxNum;
     this.window = window;
@@ -132,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.0",
+  "version": "1.0.2",
   "description": "Rate limiting for Node.js with token bucket, fixed window, and leaky bucket algorithms",
   "main": "dist/index.js",
   "keywords": [