@yaebal/ratelimiter 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 neverlane
+
+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,13 @@
+# @yaebal/ratelimiter
+
+max updates allowed per window. defaults to 5.
+
+## install
+
+```sh
+pnpm add @yaebal/ratelimiter
+```
+
+---
+
+part of [**yaebal**](https://github.com/neverlane/yaebal) — a type-safe, runtime-agnostic Telegram Bot API framework. MIT.

package/lib/index.d.ts

@@ -0,0 +1,28 @@
+import type { Context, Plugin } from "@yaebal/core";
+interface Window {
+    count: number;
+    resetAt: number;
+}
+export interface RateLimiterOptions {
+    /** max updates allowed per window. defaults to 5. */
+    limit?: number;
+    /** window length in ms. defaults to 1000. */
+    windowMs?: number;
+    /** called when an update is dropped for exceeding the limit. */
+    onLimit?: (ctx: Context) => unknown;
+    /** limit key for an update. defaults to per-user (`ctx.from.id`). */
+    getKey?: (ctx: Context) => string | undefined;
+}
+/**
+ * decide whether an update is within the limit, returning the updated window.
+ * mutates `rec` in place when reusing the window, or allocates a fresh one on
+ * reset. exported for testing.
+ */
+export declare function decide(rec: Window | undefined, now: number, limit: number, windowMs: number): {
+    allowed: boolean;
+    window: Window;
+};
+/** drop updates from a key (defaults to per-user) that exceed `limit` per `windowMs`. */
+export declare function ratelimiter(options?: RateLimiterOptions): Plugin<Context, Record<never, never>>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEpD,UAAU,MAAM;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IAClC,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;IACpC,qEAAqE;IACrE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;CAC9C;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CACrB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACd;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAKtC;AAED,yFAAyF;AACzF,wBAAgB,WAAW,CAC1B,OAAO,GAAE,kBAAuB,GAC9B,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CA0BvC"}

package/lib/index.js

@@ -0,0 +1,33 @@
+/**
+ * decide whether an update is within the limit, returning the updated window.
+ * mutates `rec` in place when reusing the window, or allocates a fresh one on
+ * reset. exported for testing.
+ */
+export function decide(rec, now, limit, windowMs) {
+    const window = !rec || now >= rec.resetAt ? { count: 0, resetAt: now + windowMs } : rec;
+    window.count += 1;
+    return { allowed: window.count <= limit, window };
+}
+/** drop updates from a key (defaults to per-user) that exceed `limit` per `windowMs`. */
+export function ratelimiter(options = {}) {
+    const limit = options.limit ?? 5;
+    const windowMs = options.windowMs ?? 1000;
+    const getKey = options.getKey ?? ((ctx) => ctx.from?.id?.toString());
+    // ponytail: one entry per distinct key, never evicted — bounded by the number
+    // of users the bot ever sees. fine for anti-spam scale; add a sweep if it grows.
+    const windows = new Map();
+    const plugin = (composer) => composer.use(async (ctx, next) => {
+        const key = getKey(ctx);
+        if (key === undefined)
+            return next();
+        const { allowed, window } = decide(windows.get(key), Date.now(), limit, windowMs);
+        windows.set(key, window);
+        if (!allowed) {
+            await options.onLimit?.(ctx);
+            return; // dropped
+        }
+        await next();
+    });
+    return plugin;
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkBA;;;;GAIG;AACH,MAAM,UAAU,MAAM,CACrB,GAAuB,EACvB,GAAW,EACX,KAAa,EACb,QAAgB;IAEhB,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,GAAG,QAAQ,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IACxF,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC;IAElB,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,IAAI,KAAK,EAAE,MAAM,EAAE,CAAC;AACnD,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,WAAW,CAC1B,UAA8B,EAAE;IAEhC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;IACjC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC;IAC1C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;IAE9E,8EAA8E;IAC9E,iFAAiF;IACjF,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE1C,MAAM,MAAM,GAA0C,CAAC,QAAQ,EAAE,EAAE,CAClE,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAChC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,IAAI,EAAE,CAAC;QAErC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;QAClF,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAEzB,IAAI,CAAC,OAAO,EAAE,CAAC;YACd,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC;YAC7B,OAAO,CAAC,UAAU;QACnB,CAAC;QAED,MAAM,IAAI,EAAE,CAAC;IACd,CAAC,CAAC,CAAC;IAEJ,OAAO,MAAM,CAAC;AACf,CAAC"}

package/lib/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/lib/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/lib/index.test.js

@@ -0,0 +1,52 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context } from "@yaebal/core";
+import { decide, ratelimiter } from "./index.js";
+const noop = async () => { };
+const entry = (c) => c.toMiddleware();
+const api = {};
+const ctxFrom = (userId) => new Context({
+    api,
+    update: {
+        update_id: 1,
+        message: {
+            message_id: 1,
+            date: 0,
+            chat: { id: userId, type: "private" },
+            from: { id: userId, is_bot: false, first_name: "u" },
+            text: "spam",
+        },
+    },
+    updateType: "message",
+});
+test("decide allows up to the limit, then blocks within the window", () => {
+    const a = decide(undefined, 1000, 2, 1000);
+    assert.deepEqual(a, { allowed: true, window: { count: 1, resetAt: 2000 } });
+    const b = decide(a.window, 1000, 2, 1000);
+    assert.equal(b.allowed, true); // count 2
+    const c = decide(b.window, 1000, 2, 1000);
+    assert.equal(c.allowed, false); // count 3 > 2
+});
+test("decide resets after the window elapses", () => {
+    const over = { count: 9, resetAt: 1500 };
+    const r = decide(over, 2000, 2, 1000); // now >= resetAt
+    assert.deepEqual(r, { allowed: true, window: { count: 1, resetAt: 3000 } });
+});
+test("ratelimiter drops updates over the limit and fires onLimit", async () => {
+    let handled = 0;
+    let limited = 0;
+    const mw = entry(new Composer()
+        .install(ratelimiter({ limit: 2, windowMs: 10_000, onLimit: () => limited++ }))
+        .use((_ctx, next) => {
+        handled++;
+        return next();
+    }));
+    await mw(ctxFrom(1), noop);
+    await mw(ctxFrom(1), noop);
+    await mw(ctxFrom(1), noop); // third → dropped
+    assert.equal(handled, 2);
+    assert.equal(limited, 1);
+    await mw(ctxFrom(2), noop); // different user → allowed
+    assert.equal(handled, 3);
+});
+//# sourceMappingURL=index.test.js.map

package/lib/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAmB,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,IAAI,GAAG,KAAK,IAAI,EAAE,GAAE,CAAC,CAAC;AAC5B,MAAM,KAAK,GAAG,CAAoB,CAAc,EAAE,EAAE,CACnD,CAAC,CAAC,YAAY,EAAoC,CAAC;AAEpD,MAAM,GAAG,GAAG,EAAW,CAAC;AACxB,MAAM,OAAO,GAAG,CAAC,MAAc,EAAE,EAAE,CAClC,IAAI,OAAO,CAAC;IACX,GAAG;IACH,MAAM,EAAE;QACP,SAAS,EAAE,CAAC;QACZ,OAAO,EAAE;YACR,UAAU,EAAE,CAAC;YACb,IAAI,EAAE,CAAC;YACP,IAAI,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE;YACrC,IAAI,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE;YACpD,IAAI,EAAE,MAAM;SACZ;KACQ;IACV,UAAU,EAAE,SAAS;CACrB,CAAC,CAAC;AAEJ,IAAI,CAAC,8DAA8D,EAAE,GAAG,EAAE;IACzE,MAAM,CAAC,GAAG,MAAM,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IAC3C,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;IAE5E,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IAC1C,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,UAAU;IAEzC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IAC1C,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,cAAc;AAC/C,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,wCAAwC,EAAE,GAAG,EAAE;IACnD,MAAM,IAAI,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACzC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,iBAAiB;IAExD,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;AAC7E,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,4DAA4D,EAAE,KAAK,IAAI,EAAE;IAC7E,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,MAAM,EAAE,GAAG,KAAK,CACf,IAAI,QAAQ,EAAW;SACrB,OAAO,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;SAC9E,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE;QACnB,OAAO,EAAE,CAAC;QACV,OAAO,IAAI,EAAE,CAAC;IACf,CAAC,CAAC,CACH,CAAC;IAEF,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC3B,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC3B,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,kBAAkB;IAE9C,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACzB,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAEzB,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,2BAA2B;IACvD,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;AAC1B,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@yaebal/ratelimiter",
+  "version": "0.0.1",
+  "description": "yaebal ratelimiter plugin — drop updates from users who spam the bot.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@yaebal/core": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "latest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "telegram",
+    "telegram-bot",
+    "yaebal",
+    "rate-limit",
+    "anti-spam"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverlane/yaebal",
+    "directory": "packages/ratelimiter"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test lib"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,67 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context, type Middleware } from "@yaebal/core";
+import { decide, ratelimiter } from "./index.js";
+
+const noop = async () => {};
+const entry = <C extends Context>(c: Composer<C>) =>
+	c.toMiddleware() as unknown as Middleware<Context>;
+
+const api = {} as never;
+const ctxFrom = (userId: number) =>
+	new Context({
+		api,
+		update: {
+			update_id: 1,
+			message: {
+				message_id: 1,
+				date: 0,
+				chat: { id: userId, type: "private" },
+				from: { id: userId, is_bot: false, first_name: "u" },
+				text: "spam",
+			},
+		} as never,
+		updateType: "message",
+	});
+
+test("decide allows up to the limit, then blocks within the window", () => {
+	const a = decide(undefined, 1000, 2, 1000);
+	assert.deepEqual(a, { allowed: true, window: { count: 1, resetAt: 2000 } });
+
+	const b = decide(a.window, 1000, 2, 1000);
+	assert.equal(b.allowed, true); // count 2
+
+	const c = decide(b.window, 1000, 2, 1000);
+	assert.equal(c.allowed, false); // count 3 > 2
+});
+
+test("decide resets after the window elapses", () => {
+	const over = { count: 9, resetAt: 1500 };
+	const r = decide(over, 2000, 2, 1000); // now >= resetAt
+
+	assert.deepEqual(r, { allowed: true, window: { count: 1, resetAt: 3000 } });
+});
+
+test("ratelimiter drops updates over the limit and fires onLimit", async () => {
+	let handled = 0;
+	let limited = 0;
+
+	const mw = entry(
+		new Composer<Context>()
+			.install(ratelimiter({ limit: 2, windowMs: 10_000, onLimit: () => limited++ }))
+			.use((_ctx, next) => {
+				handled++;
+				return next();
+			}),
+	);
+
+	await mw(ctxFrom(1), noop);
+	await mw(ctxFrom(1), noop);
+	await mw(ctxFrom(1), noop); // third → dropped
+	
+	assert.equal(handled, 2);
+	assert.equal(limited, 1);
+
+	await mw(ctxFrom(2), noop); // different user → allowed
+	assert.equal(handled, 3);
+});

package/src/index.ts

@@ -0,0 +1,65 @@
+import type { Context, Plugin } from "@yaebal/core";
+
+interface Window {
+	count: number;
+	resetAt: number;
+}
+
+export interface RateLimiterOptions {
+	/** max updates allowed per window. defaults to 5. */
+	limit?: number;
+	/** window length in ms. defaults to 1000. */
+	windowMs?: number;
+	/** called when an update is dropped for exceeding the limit. */
+	onLimit?: (ctx: Context) => unknown;
+	/** limit key for an update. defaults to per-user (`ctx.from.id`). */
+	getKey?: (ctx: Context) => string | undefined;
+}
+
+/**
+ * decide whether an update is within the limit, returning the updated window.
+ * mutates `rec` in place when reusing the window, or allocates a fresh one on
+ * reset. exported for testing.
+ */
+export function decide(
+	rec: Window | undefined,
+	now: number,
+	limit: number,
+	windowMs: number,
+): { allowed: boolean; window: Window } {
+	const window = !rec || now >= rec.resetAt ? { count: 0, resetAt: now + windowMs } : rec;
+	window.count += 1;
+
+	return { allowed: window.count <= limit, window };
+}
+
+/** drop updates from a key (defaults to per-user) that exceed `limit` per `windowMs`. */
+export function ratelimiter(
+	options: RateLimiterOptions = {},
+): Plugin<Context, Record<never, never>> {
+	const limit = options.limit ?? 5;
+	const windowMs = options.windowMs ?? 1000;
+	const getKey = options.getKey ?? ((ctx: Context) => ctx.from?.id?.toString());
+
+	// ponytail: one entry per distinct key, never evicted — bounded by the number
+	// of users the bot ever sees. fine for anti-spam scale; add a sweep if it grows.
+	const windows = new Map<string, Window>();
+
+	const plugin: Plugin<Context, Record<never, never>> = (composer) =>
+		composer.use(async (ctx, next) => {
+			const key = getKey(ctx);
+			if (key === undefined) return next();
+
+			const { allowed, window } = decide(windows.get(key), Date.now(), limit, windowMs);
+			windows.set(key, window);
+
+			if (!allowed) {
+				await options.onLimit?.(ctx);
+				return; // dropped
+			}
+
+			await next();
+		});
+		
+	return plugin;
+}