bucketflow 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# bucketflow
+
+Lightweight in-memory rate limiting utilities for Node.js and TypeScript.
+
+## Installation
+
+```bash
+npm install bucketflow
+```
+
+## Usage
+
+### Token bucket
+
+```ts
+import { TokenBucket } from "bucketflow";
+
+const limiter = new TokenBucket(10, 1000);
+const result = limiter.checkLimit("user-123");
+
+if (!result.allowed) {
+  console.log(result.message);
+}
+```
+
+The constructor accepts `capacity`, `refillRate` in milliseconds, and an
+optional rejection message.
+
+### Fixed window
+
+```ts
+import { FixedWindow } from "bucketflow";
+
+const limiter = new FixedWindow("api", "Too many requests", 100, 60_000);
+const result = limiter.checkLimit("user-123");
+```
+
+The constructor accepts a limiter key, optional rejection message, maximum
+requests, and window duration in milliseconds.
+
+### Sliding window
+
+```ts
+import { SlidingWindow } from "bucketflow";
+
+const limiter = new SlidingWindow(60_000, 1_000, 100);
+const result = limiter.checkLimit("user-123");
+```
+
+The constructor accepts the window duration, refresh rate, maximum requests,
+and an optional rejection message. Durations are in milliseconds.
+
+## Framework integrations
+
+Bucketflow does not depend on a web framework. You can call a limiter from
+middleware, hooks, guards, or any other request boundary.
+
+### Express
+
+```ts
+import express from "express";
+import { TokenBucket } from "bucketflow";
+
+const app = express();
+const limiter = new TokenBucket(100, 1_000);
+
+app.use((req, res, next) => {
+  const key = req.ip ?? "unknown";
+  const result = limiter.checkLimit(key);
+
+  if (!result.allowed) {
+    res.status(429).json(result);
+    return;
+  }
+
+  next();
+});
+```
+
+### Fastify
+
+Fastify can use a limiter in a `preHandler` hook:
+
+```ts
+import Fastify from "fastify";
+import { TokenBucket } from "bucketflow";
+
+const app = Fastify();
+const limiter = new TokenBucket(100, 1_000);
+
+app.addHook("preHandler", async (request, reply) => {
+  const key = request.ip;
+  const result = limiter.checkLimit(key);
+
+  if (!result.allowed) {
+    return reply.code(429).send(result);
+  }
+});
+```
+
+This works with Fastify because the package has no Express-specific or
+NestJS-specific dependencies; the limiter can be called from Fastify hooks.
+
+### NestJS
+
+In NestJS, the limiter can be used from middleware:
+
+```ts
+import { Injectable, NestMiddleware } from "@nestjs/common";
+import { Request, Response, NextFunction } from "express";
+import { TokenBucket } from "bucketflow";
+
+@Injectable()
+export class RateLimitMiddleware implements NestMiddleware {
+  private readonly limiter = new TokenBucket(100, 1_000);
+
+  use(req: Request, res: Response, next: NextFunction) {
+    const key = req.ip ?? "unknown";
+    const result = this.limiter.checkLimit(key);
+
+    if (!result.allowed) {
+      res.status(429).json(result);
+      return;
+    }
+
+    next();
+  }
+}
+```
+
+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:
+
+- `TokenBucket`
+- `FixedWindow`
+- `SlidingWindow`
+
+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.
+
+## License
+
+MIT

package/dist/fixed-window.d.ts

@@ -0,0 +1,11 @@
+import { 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);
+    checkLimit(key: string): FixedWindowResponse;
+}
+//# sourceMappingURL=fixed-window.d.ts.map

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

@@ -0,0 +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"}

package/dist/index.d.ts

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

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,168 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FixedWindow: () => FixedWindow,
+  SlidingWindow: () => SlidingWindow,
+  TokenBucket: () => TokenBucket
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/fixed-window.ts
+var FixedWindow = class {
+  constructor(key, message = "Too many requests", maxNum, window) {
+    this.store = /* @__PURE__ */ new Map();
+    this.key = key;
+    this.message = message;
+    this.maxNum = maxNum;
+    this.window = window;
+  }
+  checkLimit(key) {
+    if (!this.store.has(key)) {
+      this.store.set(key, {
+        count: 1,
+        windowEnd: Date.now() + this.window,
+        windowStart: Date.now()
+      });
+      return {
+        allowed: true,
+        reqRemaining: this.maxNum - 1,
+        message: this.message
+      };
+    }
+    const entry = this.store.get(key);
+    if (Date.now() > entry.windowEnd) {
+      entry.count = 0;
+      entry.windowEnd = Date.now() + this.window;
+      entry.windowStart = Date.now();
+      return {
+        allowed: true,
+        reqRemaining: this.maxNum,
+        message: this.message
+      };
+    }
+    if (entry.count >= this.maxNum) {
+      return {
+        allowed: false,
+        reqRemaining: 0,
+        message: this.message
+      };
+    }
+    entry.count += 1;
+    return {
+      allowed: true,
+      reqRemaining: this.maxNum - 1,
+      message: this.message
+    };
+  }
+};
+
+// src/token-bucket.ts
+var TokenBucket = class {
+  constructor(capacity, refillRate, message = "Too many requests") {
+    this.store = /* @__PURE__ */ new Map();
+    this.capacity = capacity;
+    this.message = message;
+    this.refillRate = refillRate;
+  }
+  checkLimit(key) {
+    if (!this.store.has(key)) {
+      this.store.set(key, {
+        tokens: this.capacity,
+        tokenWindow: Date.now()
+      });
+    }
+    const entry = this.store.get(key);
+    const timeRemaining = Date.now() - entry.tokenWindow;
+    const tokensToAdd = Math.floor(timeRemaining / this.refillRate);
+    if (timeRemaining >= this.refillRate && entry.tokens < this.capacity) {
+      entry.tokens += Math.min(tokensToAdd, this.capacity);
+      entry.tokenWindow += this.refillRate;
+    }
+    if (entry.tokens > 0) {
+      entry.tokens -= 1;
+      entry.tokenWindow = Date.now();
+      return {
+        allowed: true,
+        message: this.message,
+        tokens: entry.tokens
+      };
+    }
+    return {
+      allowed: false,
+      message: this.message,
+      tokens: entry.tokens
+    };
+  }
+};
+
+// src/sliding-window.ts
+var SlidingWindow = class {
+  constructor(window, refreshRate, maxRequests, message = "Too many requests") {
+    this.store = /* @__PURE__ */ new Map();
+    this.window = window;
+    this.message = message;
+    this.refreshRate = refreshRate;
+    this.maxRequests = maxRequests;
+  }
+  checkLimit(key) {
+    if (!this.store.has(key)) {
+      this.store.set(key, {
+        counter: 1,
+        startTime: Date.now()
+      });
+    }
+    const entry = this.store.get(key);
+    const timeElapsed = Date.now() - entry.startTime;
+    const requestOffload = Math.floor(timeElapsed / this.refreshRate);
+    if (timeElapsed >= this.refreshRate && entry.counter > 0) {
+      entry.counter = Math.max(
+        0,
+        Math.min(entry.counter - requestOffload, this.maxRequests)
+      );
+      entry.startTime = Date.now();
+      return {
+        allowed: true,
+        counter: entry.counter,
+        message: this.message
+      };
+    }
+    if (entry.counter < this.maxRequests) {
+      entry.counter += 1;
+      return {
+        allowed: true,
+        counter: entry.counter,
+        message: this.message
+      };
+    }
+    return {
+      allowed: false,
+      counter: entry.counter,
+      message: this.message
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FixedWindow,
+  SlidingWindow,
+  TokenBucket
+});

package/dist/index.mjs

@@ -0,0 +1,139 @@
+// src/fixed-window.ts
+var FixedWindow = class {
+  constructor(key, message = "Too many requests", maxNum, window) {
+    this.store = /* @__PURE__ */ new Map();
+    this.key = key;
+    this.message = message;
+    this.maxNum = maxNum;
+    this.window = window;
+  }
+  checkLimit(key) {
+    if (!this.store.has(key)) {
+      this.store.set(key, {
+        count: 1,
+        windowEnd: Date.now() + this.window,
+        windowStart: Date.now()
+      });
+      return {
+        allowed: true,
+        reqRemaining: this.maxNum - 1,
+        message: this.message
+      };
+    }
+    const entry = this.store.get(key);
+    if (Date.now() > entry.windowEnd) {
+      entry.count = 0;
+      entry.windowEnd = Date.now() + this.window;
+      entry.windowStart = Date.now();
+      return {
+        allowed: true,
+        reqRemaining: this.maxNum,
+        message: this.message
+      };
+    }
+    if (entry.count >= this.maxNum) {
+      return {
+        allowed: false,
+        reqRemaining: 0,
+        message: this.message
+      };
+    }
+    entry.count += 1;
+    return {
+      allowed: true,
+      reqRemaining: this.maxNum - 1,
+      message: this.message
+    };
+  }
+};
+
+// src/token-bucket.ts
+var TokenBucket = class {
+  constructor(capacity, refillRate, message = "Too many requests") {
+    this.store = /* @__PURE__ */ new Map();
+    this.capacity = capacity;
+    this.message = message;
+    this.refillRate = refillRate;
+  }
+  checkLimit(key) {
+    if (!this.store.has(key)) {
+      this.store.set(key, {
+        tokens: this.capacity,
+        tokenWindow: Date.now()
+      });
+    }
+    const entry = this.store.get(key);
+    const timeRemaining = Date.now() - entry.tokenWindow;
+    const tokensToAdd = Math.floor(timeRemaining / this.refillRate);
+    if (timeRemaining >= this.refillRate && entry.tokens < this.capacity) {
+      entry.tokens += Math.min(tokensToAdd, this.capacity);
+      entry.tokenWindow += this.refillRate;
+    }
+    if (entry.tokens > 0) {
+      entry.tokens -= 1;
+      entry.tokenWindow = Date.now();
+      return {
+        allowed: true,
+        message: this.message,
+        tokens: entry.tokens
+      };
+    }
+    return {
+      allowed: false,
+      message: this.message,
+      tokens: entry.tokens
+    };
+  }
+};
+
+// src/sliding-window.ts
+var SlidingWindow = class {
+  constructor(window, refreshRate, maxRequests, message = "Too many requests") {
+    this.store = /* @__PURE__ */ new Map();
+    this.window = window;
+    this.message = message;
+    this.refreshRate = refreshRate;
+    this.maxRequests = maxRequests;
+  }
+  checkLimit(key) {
+    if (!this.store.has(key)) {
+      this.store.set(key, {
+        counter: 1,
+        startTime: Date.now()
+      });
+    }
+    const entry = this.store.get(key);
+    const timeElapsed = Date.now() - entry.startTime;
+    const requestOffload = Math.floor(timeElapsed / this.refreshRate);
+    if (timeElapsed >= this.refreshRate && entry.counter > 0) {
+      entry.counter = Math.max(
+        0,
+        Math.min(entry.counter - requestOffload, this.maxRequests)
+      );
+      entry.startTime = Date.now();
+      return {
+        allowed: true,
+        counter: entry.counter,
+        message: this.message
+      };
+    }
+    if (entry.counter < this.maxRequests) {
+      entry.counter += 1;
+      return {
+        allowed: true,
+        counter: entry.counter,
+        message: this.message
+      };
+    }
+    return {
+      allowed: false,
+      counter: entry.counter,
+      message: this.message
+    };
+  }
+};
+export {
+  FixedWindow,
+  SlidingWindow,
+  TokenBucket
+};

package/dist/leaky-bucket.d.ts

@@ -0,0 +1,10 @@
+import type { LeakyBucketProps } from "../types";
+export declare class LeakyBucket implements LeakyBucketProps {
+    capacity: number;
+    queue: Array<any>;
+    leakRate: number;
+    constructor(capacity: number, leakRate: number);
+    addRequest(req: any): boolean;
+    leak(): void;
+}
+//# sourceMappingURL=leaky-bucket.d.ts.map

package/dist/leaky-bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaky-bucket.d.ts","sourceRoot":"","sources":["../src/leaky-bucket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD,qBAAa,WAAY,YAAW,gBAAgB;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IAEjB,YAAY,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAI7C;IAED,UAAU,CAAC,GAAG,EAAE,GAAG,WAMlB;IAED,IAAI,SAIH;CACF"}

package/dist/sliding-window.d.ts

@@ -0,0 +1,11 @@
+import type { SlidingWindowProps, SlidingWindowResponse } from "../types";
+export declare class SlidingWindow implements SlidingWindowProps {
+    window: number;
+    refreshRate: number;
+    maxRequests: number;
+    message: string;
+    private store;
+    constructor(window: number, refreshRate: number, maxRequests: number, message?: string);
+    checkLimit(key: string): SlidingWindowResponse;
+}
+//# sourceMappingURL=sliding-window.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sliding-window.d.ts","sourceRoot":"","sources":["../src/sliding-window.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,kBAAkB,EAClB,qBAAqB,EACtB,MAAM,UAAU,CAAC;AAElB,qBAAa,aAAc,YAAW,kBAAkB;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAEhB,OAAO,CAAC,KAAK,CAA8C;IAE3D,YACE,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,MAA4B,EAMtC;IAED,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,CAwC7C;CACF"}

package/dist/token-bucket.d.ts

@@ -0,0 +1,10 @@
+import type { TokenBucketProps, TokenEntryResponse } from "../types";
+export declare class TokenBucket implements TokenBucketProps {
+    capacity: number;
+    refillRate: number;
+    private store;
+    message: string;
+    constructor(capacity: number, refillRate: number, message?: string);
+    checkLimit(key: string): TokenEntryResponse;
+}
+//# sourceMappingURL=token-bucket.d.ts.map

package/dist/token-bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-bucket.d.ts","sourceRoot":"","sources":["../src/token-bucket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAEhB,kBAAkB,EACnB,MAAM,UAAU,CAAC;AAElB,qBAAa,WAAY,YAAW,gBAAgB;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,EAAE,MAAM,CAAC;IAEhB,YACE,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,MAA4B,EAKtC;IAED,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAiC1C;CACF"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "bucketflow",
+  "version": "1.0.0",
+  "description": "Rate limiting for Node.js with token bucket, fixed window, and leaky bucket algorithms",
+  "main": "dist/index.js",
+  "keywords": [
+    "rate-limiting",
+    "token-bucket",
+    "fixed-window",
+    "leaky-bucket"
+  ],
+  "author": "Davies",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsup && tsc --emitDeclarationOnly",
+    "prepublishOnly": "npm run build"
+  },
+  "type": "commonjs",
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "5.7.3"
+  }
+}