@yaebal/throttle 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,6 @@
 # @yaebal/throttle
 
-minimum ms between outgoing calls. defaults to 34 (~30/sec, telegram's global cap).
+space out outgoing API calls. defaults to 34 ms between calls (~30/sec, telegram's global cap).
 
 ## install
 
@@ -8,6 +8,20 @@ minimum ms between outgoing calls. defaults to 34 (~30/sec, telegram's global ca
 pnpm add @yaebal/throttle
 ```
 
+## usage
+
+```ts
+import { throttle } from "@yaebal/throttle";
+
+bot.install(throttle({ minIntervalMs: 100 }));
+```
+
+the direct api-hook form is still available:
+
+```ts
+throttle(bot.api, { minIntervalMs: 100 });
+```
+
 ---
 
 part of [**yaebal**](https://github.com/neverlane/yaebal) — a type-safe, runtime-agnostic Telegram Bot API framework. MIT.

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-import type { Api } from "@yaebal/core";
+import type { Api, BotPlugin } from "@yaebal/core";
 export interface ThrottleOptions {
     /** minimum ms between outgoing calls. defaults to 34 (~30/sec, telegram's global cap). */
     minIntervalMs?: number;
@@ -11,10 +11,8 @@ 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.
- */
+/** create an installable bot plugin: `bot.install(throttle())`. */
+export declare function throttle(options?: ThrottleOptions): BotPlugin;
+/** install throttling on a bot's API directly: `throttle(bot.api)`. */
 export declare function throttle(api: Api, options?: ThrottleOptions): void;
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEnD,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;AA6BD,mEAAmE;AACnE,wBAAgB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;AAC/D,uEAAuE;AACvE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC"}

package/lib/index.js

@@ -6,12 +6,15 @@ export function reserve(now, next, interval) {
     const at = Math.max(now, next);
     return { at, next: at + interval };
 }
+function isApi(value) {
+    return typeof value?.before === "function";
+}
 /**
  * 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 = {}) {
+function installThrottle(api, options = {}) {
     const interval = options.minIntervalMs ?? 34;
     let next = 0;
     api.before(async () => {
@@ -24,4 +27,13 @@ export function throttle(api, options = {}) {
         return undefined; // keep params unchanged
     });
 }
+export function throttle(apiOrOptions, options = {}) {
+    if (isApi(apiOrOptions))
+        return installThrottle(apiOrOptions, options);
+    const pluginOptions = apiOrOptions ?? {};
+    return (bot) => {
+        installThrottle(bot.api, pluginOptions);
+        return bot;
+    };
+}
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +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"}
+{"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,SAAS,KAAK,CAAC,KAAwC;IACtD,OAAO,OAAQ,KAAyB,EAAE,MAAM,KAAK,UAAU,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,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;AAMD,MAAM,UAAU,QAAQ,CACvB,YAAoC,EACpC,UAA2B,EAAE;IAE7B,IAAI,KAAK,CAAC,YAAY,CAAC;QAAE,OAAO,eAAe,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAEvE,MAAM,aAAa,GAAG,YAAY,IAAI,EAAE,CAAC;IAEzC,OAAO,CAAC,GAAG,EAAE,EAAE;QACd,eAAe,CAAC,GAAG,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;QACxC,OAAO,GAAG,CAAC;IACZ,CAAC,CAAC;AACH,CAAC"}

package/lib/index.test.js

@@ -16,10 +16,22 @@ test("throttle registers a before hook that resolves", async () => {
     const api = {
         before: (h) => {
             hook = h;
+            return api;
         },
     };
     throttle(api, { minIntervalMs: 0 });
     assert.equal(typeof hook, "function");
     await hook?.("sendMessage", undefined); // interval 0 → no delay
 });
+test("throttle can be installed as a bot plugin", () => {
+    let hook;
+    const api = {
+        before: (h) => {
+            hook = h;
+            return api;
+        },
+    };
+    throttle({ minIntervalMs: 0 })({ api });
+    assert.equal(typeof hook, "function");
+});
 //# sourceMappingURL=index.test.js.map

package/lib/index.test.js.map

@@ -1 +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"}
+{"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;AAE7B,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,IAA4B,CAAC;IAEjC,MAAM,GAAG,GAAG;QACX,MAAM,EAAE,CAAC,CAAa,EAAE,EAAE;YACzB,IAAI,GAAG,CAAC,CAAC;YACT,OAAO,GAAU,CAAC;QACnB,CAAC;KACM,CAAC;IAET,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;AAEH,IAAI,CAAC,2CAA2C,EAAE,GAAG,EAAE;IACtD,IAAI,IAA4B,CAAC;IACjC,MAAM,GAAG,GAAG;QACX,MAAM,EAAE,CAAC,CAAa,EAAE,EAAE;YACzB,IAAI,GAAG,CAAC,CAAC;YACT,OAAO,GAAU,CAAC;QACnB,CAAC;KACM,CAAC;IAET,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,EAAW,CAAC,CAAC;IAEjD,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,UAAU,CAAC,CAAC;AACvC,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaebal/throttle",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "yaebal throttle plugin — space out outgoing API calls to avoid 429s.",
   "type": "module",
   "main": "./lib/index.js",
@@ -16,7 +16,7 @@
     "src"
   ],
   "dependencies": {
-    "@yaebal/core": "0.0.1"
+    "@yaebal/core": "0.0.5"
   },
   "devDependencies": {
     "@types/node": "latest"

package/src/index.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import type { Api, BeforeHook } from "@yaebal/core";
 import { reserve, throttle } from "./index.js";
 
 test("reserve runs the first call immediately", () => {
@@ -16,16 +17,31 @@ test("reserve respects real elapsed time (no artificial wait)", () => {
 });
 
 test("throttle registers a before hook that resolves", async () => {
-	let hook: ((method: string, params: unknown) => Promise<unknown>) | undefined;
+	let hook: BeforeHook | undefined;
 
 	const api = {
-		before: (h: typeof hook) => {
+		before: (h: BeforeHook) => {
 			hook = h;
+			return api as Api;
 		},
-	} as never;
+	} as Api;
 
 	throttle(api, { minIntervalMs: 0 });
 	assert.equal(typeof hook, "function");
-	
+
 	await hook?.("sendMessage", undefined); // interval 0 → no delay
 });
+
+test("throttle can be installed as a bot plugin", () => {
+	let hook: BeforeHook | undefined;
+	const api = {
+		before: (h: BeforeHook) => {
+			hook = h;
+			return api as Api;
+		},
+	} as Api;
+
+	throttle({ minIntervalMs: 0 })({ api } as never);
+
+	assert.equal(typeof hook, "function");
+});

package/src/index.ts

@@ -1,4 +1,4 @@
-import type { Api } from "@yaebal/core";
+import type { Api, BotPlugin } from "@yaebal/core";
 
 export interface ThrottleOptions {
 	/** minimum ms between outgoing calls. defaults to 34 (~30/sec, telegram's global cap). */
@@ -15,12 +15,16 @@ export function reserve(now: number, next: number, interval: number): { at: numb
 	return { at, next: at + interval };
 }
 
+function isApi(value: Api | ThrottleOptions | undefined): value is Api {
+	return typeof (value as Api | undefined)?.before === "function";
+}
+
 /**
  * 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 {
+function installThrottle(api: Api, options: ThrottleOptions = {}): void {
 	const interval = options.minIntervalMs ?? 34;
 
 	let next = 0;
@@ -33,7 +37,25 @@ export function throttle(api: Api, options: ThrottleOptions = {}): void {
 
 		const wait = slot.at - now;
 		if (wait > 0) await new Promise((r) => setTimeout(r, wait));
-		
+
 		return undefined; // keep params unchanged
 	});
 }
+
+/** create an installable bot plugin: `bot.install(throttle())`. */
+export function throttle(options?: ThrottleOptions): BotPlugin;
+/** install throttling on a bot's API directly: `throttle(bot.api)`. */
+export function throttle(api: Api, options?: ThrottleOptions): void;
+export function throttle(
+	apiOrOptions?: Api | ThrottleOptions,
+	options: ThrottleOptions = {},
+): BotPlugin | void {
+	if (isApi(apiOrOptions)) return installThrottle(apiOrOptions, options);
+
+	const pluginOptions = apiOrOptions ?? {};
+
+	return (bot) => {
+		installThrottle(bot.api, pluginOptions);
+		return bot;
+	};
+}