@yaebal/throttle 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/throttle
+
+minimum ms between outgoing calls. defaults to 34 (~30/sec, telegram's global cap).
+
+## install
+
+```sh
+pnpm add @yaebal/throttle
+```
+
+---
+
+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,20 @@
+import type { Api } from "@yaebal/core";
+export interface ThrottleOptions {
+    /** minimum ms between outgoing calls. defaults to 34 (~30/sec, telegram's global cap). */
+    minIntervalMs?: number;
+}
+/**
+ * reserve the next call slot: no earlier than `now`, and never closer than
+ * `interval` to the previous slot. pure — exported for testing.
+ */
+export declare function reserve(now: number, next: number, interval: number): {
+    at: number;
+    next: number;
+};
+/**
+ * space out outgoing api calls by at least `minIntervalMs` (hooks `api.before`).
+ * calls past the cap are delayed, not dropped, so nothing is lost — they just
+ * queue up behind the rate limit.
+ */
+export declare function throttle(api: Api, options?: ThrottleOptions): void;
+//# 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,GAAG,EAAE,MAAM,cAAc,CAAC;AAExC,MAAM,WAAW,eAAe;IAC/B,0FAA0F;IAC1F,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAIjG;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI,CAgBtE"}

package/lib/index.js

@@ -0,0 +1,27 @@
+/**
+ * reserve the next call slot: no earlier than `now`, and never closer than
+ * `interval` to the previous slot. pure — exported for testing.
+ */
+export function reserve(now, next, interval) {
+    const at = Math.max(now, next);
+    return { at, next: at + interval };
+}
+/**
+ * space out outgoing api calls by at least `minIntervalMs` (hooks `api.before`).
+ * calls past the cap are delayed, not dropped, so nothing is lost — they just
+ * queue up behind the rate limit.
+ */
+export function throttle(api, options = {}) {
+    const interval = options.minIntervalMs ?? 34;
+    let next = 0;
+    api.before(async () => {
+        const now = Date.now();
+        const slot = reserve(now, next, interval);
+        next = slot.next;
+        const wait = slot.at - now;
+        if (wait > 0)
+            await new Promise((r) => setTimeout(r, wait));
+        return undefined; // keep params unchanged
+    });
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,GAAW,EAAE,IAAY,EAAE,QAAgB;IAClE,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAE/B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,GAAG,QAAQ,EAAE,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAQ,EAAE,UAA2B,EAAE;IAC/D,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;IAE7C,IAAI,IAAI,GAAG,CAAC,CAAC;IAEb,GAAG,CAAC,MAAM,CAAC,KAAK,IAAwB,EAAE;QACzC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QAE1C,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QAEjB,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,GAAG,GAAG,CAAC;QAC3B,IAAI,IAAI,GAAG,CAAC;YAAE,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;QAE5D,OAAO,SAAS,CAAC,CAAC,wBAAwB;IAC3C,CAAC,CAAC,CAAC;AACJ,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,25 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { reserve, throttle } from "./index.js";
+test("reserve runs the first call immediately", () => {
+    assert.deepEqual(reserve(1000, 0, 34), { at: 1000, next: 1034 });
+});
+test("reserve spaces rapid calls by the interval", () => {
+    assert.deepEqual(reserve(1000, 1034, 34), { at: 1034, next: 1068 });
+    assert.deepEqual(reserve(1034, 1068, 34), { at: 1068, next: 1102 });
+});
+test("reserve respects real elapsed time (no artificial wait)", () => {
+    assert.deepEqual(reserve(2000, 1068, 34), { at: 2000, next: 2034 });
+});
+test("throttle registers a before hook that resolves", async () => {
+    let hook;
+    const api = {
+        before: (h) => {
+            hook = h;
+        },
+    };
+    throttle(api, { minIntervalMs: 0 });
+    assert.equal(typeof hook, "function");
+    await hook?.("sendMessage", undefined); // interval 0 → no delay
+});
+//# 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,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE/C,IAAI,CAAC,yCAAyC,EAAE,GAAG,EAAE;IACpD,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AAClE,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,4CAA4C,EAAE,GAAG,EAAE;IACvD,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACpE,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AACrE,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,yDAAyD,EAAE,GAAG,EAAE;IACpE,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AACrE,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,gDAAgD,EAAE,KAAK,IAAI,EAAE;IACjE,IAAI,IAAyE,CAAC;IAE9E,MAAM,GAAG,GAAG;QACX,MAAM,EAAE,CAAC,CAAc,EAAE,EAAE;YAC1B,IAAI,GAAG,CAAC,CAAC;QACV,CAAC;KACQ,CAAC;IAEX,QAAQ,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC,CAAC;IACpC,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,UAAU,CAAC,CAAC;IAEtC,MAAM,IAAI,EAAE,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC,CAAC,wBAAwB;AACjE,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@yaebal/throttle",
+  "version": "0.0.1",
+  "description": "yaebal throttle plugin — space out outgoing API calls to avoid 429s.",
+  "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",
+    "throttle",
+    "rate-limit"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverlane/yaebal",
+    "directory": "packages/throttle"
+  },
+  "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,31 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { reserve, throttle } from "./index.js";
+
+test("reserve runs the first call immediately", () => {
+	assert.deepEqual(reserve(1000, 0, 34), { at: 1000, next: 1034 });
+});
+
+test("reserve spaces rapid calls by the interval", () => {
+	assert.deepEqual(reserve(1000, 1034, 34), { at: 1034, next: 1068 });
+	assert.deepEqual(reserve(1034, 1068, 34), { at: 1068, next: 1102 });
+});
+
+test("reserve respects real elapsed time (no artificial wait)", () => {
+	assert.deepEqual(reserve(2000, 1068, 34), { at: 2000, next: 2034 });
+});
+
+test("throttle registers a before hook that resolves", async () => {
+	let hook: ((method: string, params: unknown) => Promise<unknown>) | undefined;
+
+	const api = {
+		before: (h: typeof hook) => {
+			hook = h;
+		},
+	} as never;
+
+	throttle(api, { minIntervalMs: 0 });
+	assert.equal(typeof hook, "function");
+	
+	await hook?.("sendMessage", undefined); // interval 0 → no delay
+});

package/src/index.ts

@@ -0,0 +1,39 @@
+import type { Api } from "@yaebal/core";
+
+export interface ThrottleOptions {
+	/** minimum ms between outgoing calls. defaults to 34 (~30/sec, telegram's global cap). */
+	minIntervalMs?: number;
+}
+
+/**
+ * reserve the next call slot: no earlier than `now`, and never closer than
+ * `interval` to the previous slot. pure — exported for testing.
+ */
+export function reserve(now: number, next: number, interval: number): { at: number; next: number } {
+	const at = Math.max(now, next);
+
+	return { at, next: at + interval };
+}
+
+/**
+ * space out outgoing api calls by at least `minIntervalMs` (hooks `api.before`).
+ * calls past the cap are delayed, not dropped, so nothing is lost — they just
+ * queue up behind the rate limit.
+ */
+export function throttle(api: Api, options: ThrottleOptions = {}): void {
+	const interval = options.minIntervalMs ?? 34;
+
+	let next = 0;
+
+	api.before(async (): Promise<undefined> => {
+		const now = Date.now();
+		const slot = reserve(now, next, interval);
+
+		next = slot.next;
+
+		const wait = slot.at - now;
+		if (wait > 0) await new Promise((r) => setTimeout(r, wait));
+		
+		return undefined; // keep params unchanged
+	});
+}