throttleai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+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,308 @@
+<p align="center">
+  <img src="logo.png" alt="ThrottleAI" width="400">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/throttleai"><img src="https://img.shields.io/npm/v/throttleai" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">
+  <em>A token-based lease governor for AI calls — small enough to embed anywhere, strict enough to prevent stampedes.</em>
+</p>
+
+---
+
+## 60-second quickstart
+
+```bash
+pnpm add throttleai
+```
+
+```ts
+import { createGovernor, withLease, presets } from "throttleai";
+
+const gov = createGovernor(presets.balanced());
+
+const result = await withLease(
+  gov,
+  { actorId: "user-1", action: "chat" },
+  async () => await callMyModel(),
+);
+
+if (result.granted) {
+  console.log(result.result);
+} else {
+  console.log("Throttled:", result.decision.recommendation);
+}
+```
+
+That's it. The governor enforces concurrency, rate limits, and fairness. Leases auto-expire if you forget to release.
+
+## Why
+
+AI applications hit rate limits, blow budgets, and create stampedes. ThrottleAI sits between your code and the model call, enforcing:
+
+- **Concurrency** — cap in-flight calls with weighted slots and interactive reserve
+- **Rate** — requests/min and tokens/min with rolling windows
+- **Fairness** — no single actor monopolizes capacity
+- **Leases** — acquire before, release after, auto-expire on timeout
+- **Observability** — `snapshot()`, `onEvent`, and `formatEvent()` for debugging
+
+Zero dependencies. Node.js 18+. Tree-shakeable.
+
+## Presets
+
+```ts
+import { presets } from "throttleai";
+
+// Single user, CLI tools — 1 call at a time, 10 req/min
+createGovernor(presets.quiet());
+
+// SaaS backend — 5 concurrent (2 interactive reserve), 60 req/min, fairness
+createGovernor(presets.balanced());
+
+// Batch processing — 20 concurrent, 300 req/min, fairness + adaptive tuning
+createGovernor(presets.aggressive());
+
+// Override any field
+createGovernor({ ...presets.balanced(), leaseTtlMs: 30_000 });
+```
+
+## Common patterns
+
+### Server endpoint: 429 vs queue
+
+```ts
+// Option A: immediate deny with 429
+const result = await withLease(gov, request, fn);
+// result.granted === false → respond with 429
+
+// Option B: wait with bounded retries
+const result = await withLease(gov, request, fn, {
+  strategy: "wait-then-deny",
+  maxAttempts: 3,
+  maxWaitMs: 5_000,
+});
+```
+
+### UI interactive vs background
+
+```ts
+// User-facing chat gets priority
+gov.acquire({ actorId: "user", action: "chat", priority: "interactive" });
+
+// Background embedding can wait
+gov.acquire({ actorId: "pipeline", action: "embed", priority: "background" });
+```
+
+With `interactiveReserve: 2`, background tasks are blocked when only 2 slots remain, keeping those for interactive requests.
+
+### Streaming calls
+
+```ts
+const decision = gov.acquire({ actorId: "user", action: "stream" });
+if (!decision.granted) return;
+
+try {
+  const stream = await openai.chat.completions.create({ stream: true, ... });
+  for await (const chunk of stream) {
+    // process chunk
+  }
+  gov.release(decision.leaseId, { outcome: "success" });
+} catch (err) {
+  gov.release(decision.leaseId, { outcome: "error" });
+  throw err;
+}
+```
+
+Acquire once, release once — the lease holds for the entire stream duration.
+
+### Observability: see why it throttles
+
+```ts
+import { createGovernor, formatEvent, formatSnapshot } from "throttleai";
+
+const gov = createGovernor({
+  ...presets.balanced(),
+  onEvent: (e) => console.log(formatEvent(e)),
+  // [deny] actor=user-1 action=chat reason=concurrency retryAfterMs=500 — All 5 slots in use...
+});
+
+// Point-in-time view
+console.log(formatSnapshot(gov.snapshot()));
+// concurrency=3/5 rate=12/60 leases=3
+```
+
+## Configuration
+
+```ts
+createGovernor({
+  // Concurrency (optional)
+  concurrency: {
+    maxInFlight: 5,          // max simultaneous weight
+    interactiveReserve: 1,   // slots reserved for interactive priority
+  },
+
+  // Rate limiting (optional)
+  rate: {
+    requestsPerMinute: 60,   // request-rate cap
+    tokensPerMinute: 100_000, // token-rate cap
+    windowMs: 60_000,         // rolling window (default 60s)
+  },
+
+  // Advanced (optional)
+  fairness: true,             // prevent actor monopolization
+  adaptive: true,             // auto-tune concurrency from deny rate + latency
+  strict: true,               // throw on double release / unknown ID (dev mode)
+
+  // Lease settings
+  leaseTtlMs: 60_000,         // auto-expire (default 60s)
+  reaperIntervalMs: 5_000,    // sweep interval (default 5s)
+
+  // Observability
+  onEvent: (e) => { /* acquire, deny, release, expire, warn */ },
+});
+```
+
+## API
+
+### `createGovernor(config): Governor`
+
+Factory function. Returns a `Governor` instance.
+
+### `governor.acquire(request): AcquireDecision`
+
+Request a lease. Returns:
+
+```ts
+// Granted
+{ granted: true, leaseId: string, expiresAt: number }
+
+// Denied
+{ granted: false, reason, retryAfterMs, recommendation, limitsHint? }
+```
+
+Deny reasons: `"concurrency"` | `"rate"` | `"budget"` | `"policy"`
+
+### `governor.release(leaseId, report?): void`
+
+Release a lease. Always call this — even on errors.
+
+### `withLease(governor, request, fn, options?)`
+
+Execute `fn` under a lease with automatic release.
+
+```ts
+withLease(gov, request, fn, {
+  strategy: "deny",           // default — fail immediately
+  strategy: "wait",           // retry with backoff until maxWaitMs
+  strategy: "wait-then-deny", // retry up to maxAttempts
+  maxWaitMs: 10_000,          // max total wait (default 10s)
+  maxAttempts: 3,             // for "wait-then-deny" (default 3)
+  initialBackoffMs: 250,      // starting backoff (default 250ms)
+});
+```
+
+### `governor.snapshot(): GovernorSnapshot`
+
+Point-in-time state: concurrency, rate, tokens, last deny.
+
+### `formatEvent(event): string` / `formatSnapshot(snap): string`
+
+One-line human-readable formatters.
+
+### Status getters
+
+```ts
+gov.activeLeases         // active lease count
+gov.concurrencyActive    // in-flight weight
+gov.concurrencyAvailable // remaining capacity
+gov.rateCount            // requests in current window
+gov.tokenRateCount       // tokens in current window
+```
+
+### `governor.dispose(): void`
+
+Stop the TTL reaper. Call on shutdown.
+
+## Adapters
+
+Tree-shakeable wrappers — import only what you use. No runtime deps.
+
+### fetch
+
+```ts
+import { wrapFetch } from "throttleai/adapters/fetch";
+const throttledFetch = wrapFetch(fetch, { governor: gov });
+const r = await throttledFetch("https://api.example.com/v1/chat");
+if (r.ok) console.log(r.response.status);
+```
+
+### OpenAI-compatible
+
+```ts
+import { wrapChatCompletions } from "throttleai/adapters/openai";
+const chat = wrapChatCompletions(openai.chat.completions.create, { governor: gov });
+const r = await chat({ model: "gpt-4", messages });
+if (r.ok) console.log(r.result.choices[0].message.content);
+```
+
+### Tool call
+
+```ts
+import { wrapTool } from "throttleai/adapters/tools";
+const embed = wrapTool(myEmbedFn, { governor: gov, toolId: "embed", costWeight: 2 });
+const r = await embed("hello");
+if (r.ok) console.log(r.result);
+```
+
+### Express
+
+```ts
+import { throttleMiddleware } from "throttleai/adapters/express";
+app.use("/ai", throttleMiddleware({ governor: gov }));
+// 429 + Retry-After header + JSON body on deny
+```
+
+### Hono
+
+```ts
+import { throttle } from "throttleai/adapters/hono";
+app.use("/ai/*", throttle({ governor: gov }));
+// 429 JSON on deny, leaseId stored on context
+```
+
+All adapters return `{ ok: true, result, latencyMs }` on grant, `{ ok: false, decision }` on deny.
+
+## Tuning guide
+
+| You see this | Adjust this |
+|---|---|
+| `reason: "concurrency"` | Increase `maxInFlight` or decrease call duration |
+| `reason: "rate"` | Increase `requestsPerMinute` / `tokensPerMinute` |
+| `reason: "policy"` (fairness) | Lower `softCapRatio` or increase `maxInFlight` |
+| High `retryAfterMs` | Reduce `leaseTtlMs` so expired leases free faster |
+| Background tasks starved | Increase `maxInFlight` or reduce `interactiveReserve` |
+| Interactive latency high | Increase `interactiveReserve` |
+| Adaptive shrinks too fast | Lower `alpha` or raise `targetDenyRate` |
+
+Use `snapshot()` and `formatSnapshot()` to observe state in production.
+
+## Examples
+
+See [`examples/`](examples/) for runnable demos:
+
+- **[node-basic.ts](examples/node-basic.ts)** — burst simulation with snapshot printing
+- **[express-middleware.ts](examples/express-middleware.ts)** — 429 + retry-after endpoint
+- **[cookbook-adapters.ts](examples/cookbook-adapters.ts)** — all five adapters in action
+- **[cookbook-burst-snapshot.ts](examples/cookbook-burst-snapshot.ts)** — burst load with governor snapshots
+- **[cookbook-interactive-reserve.ts](examples/cookbook-interactive-reserve.ts)** — interactive vs background priority
+
+```bash
+npx tsx examples/node-basic.ts
+```
+
+## License
+
+MIT

package/dist/adapters/express.cjs

@@ -0,0 +1,75 @@
+"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/adapters/express.ts
+var express_exports = {};
+__export(express_exports, {
+  throttleMiddleware: () => throttleMiddleware
+});
+module.exports = __toCommonJS(express_exports);
+function throttleMiddleware(options) {
+  const {
+    governor,
+    getActorId,
+    getAction,
+    getPriority,
+    getEstimate,
+    onDeny
+  } = options;
+  return (req, res, next) => {
+    const actorId = getActorId ? getActorId(req) : asString(req.headers["x-actor-id"]) ?? req.ip ?? "anonymous";
+    const request = {
+      actorId,
+      action: getAction ? getAction(req) : req.path,
+      priority: getPriority ? getPriority(req) : "interactive",
+      estimate: getEstimate ? getEstimate(req) : void 0
+    };
+    const decision = governor.acquire(request);
+    if (!decision.granted) {
+      if (onDeny) {
+        onDeny(req, res, decision);
+        return;
+      }
+      res.setHeader("Retry-After", String(Math.ceil(decision.retryAfterMs / 1e3)));
+      res.status(429).json({
+        error: "Too many requests",
+        reason: decision.reason,
+        retryAfterMs: decision.retryAfterMs,
+        recommendation: decision.recommendation
+      });
+      return;
+    }
+    const leaseId = decision.leaseId;
+    res.on("finish", () => {
+      governor.release(leaseId, {
+        outcome: (res.statusCode ?? 200) < 400 ? "success" : "error"
+      });
+    });
+    next();
+  };
+}
+function asString(value) {
+  if (Array.isArray(value)) return value[0];
+  return value;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  throttleMiddleware
+});
+//# sourceMappingURL=express.cjs.map

package/dist/adapters/express.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/express.ts"],"sourcesContent":["/**\n * ThrottleAI Express adapter — drop-in middleware.\n *\n * No dependency on Express — this exports a plain function that\n * returns `(req, res, next)`. You already have Express installed.\n *\n * @module throttleai/adapters/express\n */\n\nexport type {\n  AdapterGovernor,\n  AdapterOptions,\n} from \"./types.js\";\n\nimport type { AcquireRequest, AcquireDecision, Priority, TokenEstimate } from \"../types.js\";\nimport type { AdapterGovernor } from \"./types.js\";\n\n// ---------------------------------------------------------------------------\n// Types — use minimal shapes so we don't need @types/express\n// ---------------------------------------------------------------------------\n\n/** Minimal Express-compatible request shape. */\nexport interface ExpressLikeRequest {\n  path: string;\n  method: string;\n  ip?: string;\n  headers: Record<string, string | string[] | undefined>;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  [key: string]: any;\n}\n\n/** Minimal Express-compatible response shape. */\nexport interface ExpressLikeResponse {\n  status(code: number): this;\n  json(body: unknown): void;\n  setHeader(name: string, value: string | number): void;\n  on(event: string, listener: () => void): void;\n  statusCode?: number;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  [key: string]: any;\n}\n\n/** Options for the Express throttle middleware. */\nexport interface ThrottleMiddlewareOptions {\n  /** Governor instance. */\n  governor: AdapterGovernor;\n  /**\n   * Derive the actor ID from the request (default: x-actor-id header or req.ip).\n   */\n  getActorId?: (req: ExpressLikeRequest) => string;\n  /**\n   * Derive the action from the request (default: req.path).\n   */\n  getAction?: (req: ExpressLikeRequest) => string;\n  /**\n   * Derive the priority from the request (default: interactive).\n   */\n  getPriority?: (req: ExpressLikeRequest) => Priority;\n  /**\n   * Derive a token estimate from the request (optional).\n   */\n  getEstimate?: (req: ExpressLikeRequest) => TokenEstimate | undefined;\n  /**\n   * Custom handler for denied requests (default: 429 JSON response).\n   */\n  onDeny?: (\n    req: ExpressLikeRequest,\n    res: ExpressLikeResponse,\n    decision: AcquireDecision & { granted: false },\n  ) => void;\n}\n\n// ---------------------------------------------------------------------------\n// throttleMiddleware\n// ---------------------------------------------------------------------------\n\n/**\n * Create an Express middleware that throttles requests via the governor.\n *\n * ```ts\n * import express from \"express\";\n * import { createGovernor, presets } from \"throttleai\";\n * import { throttleMiddleware } from \"throttleai/adapters/express\";\n *\n * const gov = createGovernor(presets.balanced());\n * const app = express();\n *\n * app.use(\"/ai\", throttleMiddleware({ governor: gov }));\n *\n * app.post(\"/ai/chat\", (req, res) => {\n *   // This only runs if the governor granted a lease\n *   res.json({ message: \"ok\" });\n * });\n * ```\n */\nexport function throttleMiddleware(\n  options: ThrottleMiddlewareOptions,\n): (req: ExpressLikeRequest, res: ExpressLikeResponse, next: () => void) => void {\n  const {\n    governor,\n    getActorId,\n    getAction,\n    getPriority,\n    getEstimate,\n    onDeny,\n  } = options;\n\n  return (req, res, next) => {\n    const actorId = getActorId\n      ? getActorId(req)\n      : (asString(req.headers[\"x-actor-id\"]) ?? req.ip ?? \"anonymous\");\n\n    const request: AcquireRequest = {\n      actorId,\n      action: getAction ? getAction(req) : req.path,\n      priority: getPriority ? getPriority(req) : \"interactive\",\n      estimate: getEstimate ? getEstimate(req) : undefined,\n    };\n\n    const decision = governor.acquire(request);\n\n    if (!decision.granted) {\n      if (onDeny) {\n        onDeny(req, res, decision as AcquireDecision & { granted: false });\n        return;\n      }\n\n      // Default: 429 JSON response\n      res.setHeader(\"Retry-After\", String(Math.ceil(decision.retryAfterMs / 1000)));\n      res.status(429).json({\n        error: \"Too many requests\",\n        reason: decision.reason,\n        retryAfterMs: decision.retryAfterMs,\n        recommendation: decision.recommendation,\n      });\n      return;\n    }\n\n    // Release lease when response finishes\n    const leaseId = decision.leaseId;\n    res.on(\"finish\", () => {\n      governor.release(leaseId, {\n        outcome: (res.statusCode ?? 200) < 400 ? \"success\" : \"error\",\n      });\n    });\n\n    next();\n  };\n}\n\n/** Safely convert a header value to string. */\nfunction asString(value: string | string[] | undefined): string | undefined {\n  if (Array.isArray(value)) return value[0];\n  return value;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA+FO,SAAS,mBACd,SAC+E;AAC/E,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,IAAI;AAEJ,SAAO,CAAC,KAAK,KAAK,SAAS;AACzB,UAAM,UAAU,aACZ,WAAW,GAAG,IACb,SAAS,IAAI,QAAQ,YAAY,CAAC,KAAK,IAAI,MAAM;AAEtD,UAAM,UAA0B;AAAA,MAC9B;AAAA,MACA,QAAQ,YAAY,UAAU,GAAG,IAAI,IAAI;AAAA,MACzC,UAAU,cAAc,YAAY,GAAG,IAAI;AAAA,MAC3C,UAAU,cAAc,YAAY,GAAG,IAAI;AAAA,IAC7C;AAEA,UAAM,WAAW,SAAS,QAAQ,OAAO;AAEzC,QAAI,CAAC,SAAS,SAAS;AACrB,UAAI,QAAQ;AACV,eAAO,KAAK,KAAK,QAAgD;AACjE;AAAA,MACF;AAGA,UAAI,UAAU,eAAe,OAAO,KAAK,KAAK,SAAS,eAAe,GAAI,CAAC,CAAC;AAC5E,UAAI,OAAO,GAAG,EAAE,KAAK;AAAA,QACnB,OAAO;AAAA,QACP,QAAQ,SAAS;AAAA,QACjB,cAAc,SAAS;AAAA,QACvB,gBAAgB,SAAS;AAAA,MAC3B,CAAC;AACD;AAAA,IACF;AAGA,UAAM,UAAU,SAAS;AACzB,QAAI,GAAG,UAAU,MAAM;AACrB,eAAS,QAAQ,SAAS;AAAA,QACxB,UAAU,IAAI,cAAc,OAAO,MAAM,YAAY;AAAA,MACvD,CAAC;AAAA,IACH,CAAC;AAED,SAAK;AAAA,EACP;AACF;AAGA,SAAS,SAAS,OAA0D;AAC1E,MAAI,MAAM,QAAQ,KAAK,EAAG,QAAO,MAAM,CAAC;AACxC,SAAO;AACT;","names":[]}

package/dist/adapters/express.d.cts

@@ -0,0 +1,79 @@
+import { A as AdapterGovernor } from '../types-DOUI5hr7.cjs';
+export { a as AdapterOptions } from '../types-DOUI5hr7.cjs';
+import { P as Priority, T as TokenEstimate, A as AcquireDecision } from '../governor-MVaCesqM.cjs';
+
+/**
+ * ThrottleAI Express adapter — drop-in middleware.
+ *
+ * No dependency on Express — this exports a plain function that
+ * returns `(req, res, next)`. You already have Express installed.
+ *
+ * @module throttleai/adapters/express
+ */
+
+/** Minimal Express-compatible request shape. */
+interface ExpressLikeRequest {
+    path: string;
+    method: string;
+    ip?: string;
+    headers: Record<string, string | string[] | undefined>;
+    [key: string]: any;
+}
+/** Minimal Express-compatible response shape. */
+interface ExpressLikeResponse {
+    status(code: number): this;
+    json(body: unknown): void;
+    setHeader(name: string, value: string | number): void;
+    on(event: string, listener: () => void): void;
+    statusCode?: number;
+    [key: string]: any;
+}
+/** Options for the Express throttle middleware. */
+interface ThrottleMiddlewareOptions {
+    /** Governor instance. */
+    governor: AdapterGovernor;
+    /**
+     * Derive the actor ID from the request (default: x-actor-id header or req.ip).
+     */
+    getActorId?: (req: ExpressLikeRequest) => string;
+    /**
+     * Derive the action from the request (default: req.path).
+     */
+    getAction?: (req: ExpressLikeRequest) => string;
+    /**
+     * Derive the priority from the request (default: interactive).
+     */
+    getPriority?: (req: ExpressLikeRequest) => Priority;
+    /**
+     * Derive a token estimate from the request (optional).
+     */
+    getEstimate?: (req: ExpressLikeRequest) => TokenEstimate | undefined;
+    /**
+     * Custom handler for denied requests (default: 429 JSON response).
+     */
+    onDeny?: (req: ExpressLikeRequest, res: ExpressLikeResponse, decision: AcquireDecision & {
+        granted: false;
+    }) => void;
+}
+/**
+ * Create an Express middleware that throttles requests via the governor.
+ *
+ * ```ts
+ * import express from "express";
+ * import { createGovernor, presets } from "throttleai";
+ * import { throttleMiddleware } from "throttleai/adapters/express";
+ *
+ * const gov = createGovernor(presets.balanced());
+ * const app = express();
+ *
+ * app.use("/ai", throttleMiddleware({ governor: gov }));
+ *
+ * app.post("/ai/chat", (req, res) => {
+ *   // This only runs if the governor granted a lease
+ *   res.json({ message: "ok" });
+ * });
+ * ```
+ */
+declare function throttleMiddleware(options: ThrottleMiddlewareOptions): (req: ExpressLikeRequest, res: ExpressLikeResponse, next: () => void) => void;
+
+export { AdapterGovernor, type ExpressLikeRequest, type ExpressLikeResponse, type ThrottleMiddlewareOptions, throttleMiddleware };

package/dist/adapters/express.d.ts

@@ -0,0 +1,79 @@
+import { A as AdapterGovernor } from '../types-BkfBESR2.js';
+export { a as AdapterOptions } from '../types-BkfBESR2.js';
+import { P as Priority, T as TokenEstimate, A as AcquireDecision } from '../governor-MVaCesqM.js';
+
+/**
+ * ThrottleAI Express adapter — drop-in middleware.
+ *
+ * No dependency on Express — this exports a plain function that
+ * returns `(req, res, next)`. You already have Express installed.
+ *
+ * @module throttleai/adapters/express
+ */
+
+/** Minimal Express-compatible request shape. */
+interface ExpressLikeRequest {
+    path: string;
+    method: string;
+    ip?: string;
+    headers: Record<string, string | string[] | undefined>;
+    [key: string]: any;
+}
+/** Minimal Express-compatible response shape. */
+interface ExpressLikeResponse {
+    status(code: number): this;
+    json(body: unknown): void;
+    setHeader(name: string, value: string | number): void;
+    on(event: string, listener: () => void): void;
+    statusCode?: number;
+    [key: string]: any;
+}
+/** Options for the Express throttle middleware. */
+interface ThrottleMiddlewareOptions {
+    /** Governor instance. */
+    governor: AdapterGovernor;
+    /**
+     * Derive the actor ID from the request (default: x-actor-id header or req.ip).
+     */
+    getActorId?: (req: ExpressLikeRequest) => string;
+    /**
+     * Derive the action from the request (default: req.path).
+     */
+    getAction?: (req: ExpressLikeRequest) => string;
+    /**
+     * Derive the priority from the request (default: interactive).
+     */
+    getPriority?: (req: ExpressLikeRequest) => Priority;
+    /**
+     * Derive a token estimate from the request (optional).
+     */
+    getEstimate?: (req: ExpressLikeRequest) => TokenEstimate | undefined;
+    /**
+     * Custom handler for denied requests (default: 429 JSON response).
+     */
+    onDeny?: (req: ExpressLikeRequest, res: ExpressLikeResponse, decision: AcquireDecision & {
+        granted: false;
+    }) => void;
+}
+/**
+ * Create an Express middleware that throttles requests via the governor.
+ *
+ * ```ts
+ * import express from "express";
+ * import { createGovernor, presets } from "throttleai";
+ * import { throttleMiddleware } from "throttleai/adapters/express";
+ *
+ * const gov = createGovernor(presets.balanced());
+ * const app = express();
+ *
+ * app.use("/ai", throttleMiddleware({ governor: gov }));
+ *
+ * app.post("/ai/chat", (req, res) => {
+ *   // This only runs if the governor granted a lease
+ *   res.json({ message: "ok" });
+ * });
+ * ```
+ */
+declare function throttleMiddleware(options: ThrottleMiddlewareOptions): (req: ExpressLikeRequest, res: ExpressLikeResponse, next: () => void) => void;
+
+export { AdapterGovernor, type ExpressLikeRequest, type ExpressLikeResponse, type ThrottleMiddlewareOptions, throttleMiddleware };

package/dist/adapters/express.js

@@ -0,0 +1,50 @@
+// src/adapters/express.ts
+function throttleMiddleware(options) {
+  const {
+    governor,
+    getActorId,
+    getAction,
+    getPriority,
+    getEstimate,
+    onDeny
+  } = options;
+  return (req, res, next) => {
+    const actorId = getActorId ? getActorId(req) : asString(req.headers["x-actor-id"]) ?? req.ip ?? "anonymous";
+    const request = {
+      actorId,
+      action: getAction ? getAction(req) : req.path,
+      priority: getPriority ? getPriority(req) : "interactive",
+      estimate: getEstimate ? getEstimate(req) : void 0
+    };
+    const decision = governor.acquire(request);
+    if (!decision.granted) {
+      if (onDeny) {
+        onDeny(req, res, decision);
+        return;
+      }
+      res.setHeader("Retry-After", String(Math.ceil(decision.retryAfterMs / 1e3)));
+      res.status(429).json({
+        error: "Too many requests",
+        reason: decision.reason,
+        retryAfterMs: decision.retryAfterMs,
+        recommendation: decision.recommendation
+      });
+      return;
+    }
+    const leaseId = decision.leaseId;
+    res.on("finish", () => {
+      governor.release(leaseId, {
+        outcome: (res.statusCode ?? 200) < 400 ? "success" : "error"
+      });
+    });
+    next();
+  };
+}
+function asString(value) {
+  if (Array.isArray(value)) return value[0];
+  return value;
+}
+export {
+  throttleMiddleware
+};
+//# sourceMappingURL=express.js.map

package/dist/adapters/express.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/express.ts"],"sourcesContent":["/**\n * ThrottleAI Express adapter — drop-in middleware.\n *\n * No dependency on Express — this exports a plain function that\n * returns `(req, res, next)`. You already have Express installed.\n *\n * @module throttleai/adapters/express\n */\n\nexport type {\n  AdapterGovernor,\n  AdapterOptions,\n} from \"./types.js\";\n\nimport type { AcquireRequest, AcquireDecision, Priority, TokenEstimate } from \"../types.js\";\nimport type { AdapterGovernor } from \"./types.js\";\n\n// ---------------------------------------------------------------------------\n// Types — use minimal shapes so we don't need @types/express\n// ---------------------------------------------------------------------------\n\n/** Minimal Express-compatible request shape. */\nexport interface ExpressLikeRequest {\n  path: string;\n  method: string;\n  ip?: string;\n  headers: Record<string, string | string[] | undefined>;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  [key: string]: any;\n}\n\n/** Minimal Express-compatible response shape. */\nexport interface ExpressLikeResponse {\n  status(code: number): this;\n  json(body: unknown): void;\n  setHeader(name: string, value: string | number): void;\n  on(event: string, listener: () => void): void;\n  statusCode?: number;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  [key: string]: any;\n}\n\n/** Options for the Express throttle middleware. */\nexport interface ThrottleMiddlewareOptions {\n  /** Governor instance. */\n  governor: AdapterGovernor;\n  /**\n   * Derive the actor ID from the request (default: x-actor-id header or req.ip).\n   */\n  getActorId?: (req: ExpressLikeRequest) => string;\n  /**\n   * Derive the action from the request (default: req.path).\n   */\n  getAction?: (req: ExpressLikeRequest) => string;\n  /**\n   * Derive the priority from the request (default: interactive).\n   */\n  getPriority?: (req: ExpressLikeRequest) => Priority;\n  /**\n   * Derive a token estimate from the request (optional).\n   */\n  getEstimate?: (req: ExpressLikeRequest) => TokenEstimate | undefined;\n  /**\n   * Custom handler for denied requests (default: 429 JSON response).\n   */\n  onDeny?: (\n    req: ExpressLikeRequest,\n    res: ExpressLikeResponse,\n    decision: AcquireDecision & { granted: false },\n  ) => void;\n}\n\n// ---------------------------------------------------------------------------\n// throttleMiddleware\n// ---------------------------------------------------------------------------\n\n/**\n * Create an Express middleware that throttles requests via the governor.\n *\n * ```ts\n * import express from \"express\";\n * import { createGovernor, presets } from \"throttleai\";\n * import { throttleMiddleware } from \"throttleai/adapters/express\";\n *\n * const gov = createGovernor(presets.balanced());\n * const app = express();\n *\n * app.use(\"/ai\", throttleMiddleware({ governor: gov }));\n *\n * app.post(\"/ai/chat\", (req, res) => {\n *   // This only runs if the governor granted a lease\n *   res.json({ message: \"ok\" });\n * });\n * ```\n */\nexport function throttleMiddleware(\n  options: ThrottleMiddlewareOptions,\n): (req: ExpressLikeRequest, res: ExpressLikeResponse, next: () => void) => void {\n  const {\n    governor,\n    getActorId,\n    getAction,\n    getPriority,\n    getEstimate,\n    onDeny,\n  } = options;\n\n  return (req, res, next) => {\n    const actorId = getActorId\n      ? getActorId(req)\n      : (asString(req.headers[\"x-actor-id\"]) ?? req.ip ?? \"anonymous\");\n\n    const request: AcquireRequest = {\n      actorId,\n      action: getAction ? getAction(req) : req.path,\n      priority: getPriority ? getPriority(req) : \"interactive\",\n      estimate: getEstimate ? getEstimate(req) : undefined,\n    };\n\n    const decision = governor.acquire(request);\n\n    if (!decision.granted) {\n      if (onDeny) {\n        onDeny(req, res, decision as AcquireDecision & { granted: false });\n        return;\n      }\n\n      // Default: 429 JSON response\n      res.setHeader(\"Retry-After\", String(Math.ceil(decision.retryAfterMs / 1000)));\n      res.status(429).json({\n        error: \"Too many requests\",\n        reason: decision.reason,\n        retryAfterMs: decision.retryAfterMs,\n        recommendation: decision.recommendation,\n      });\n      return;\n    }\n\n    // Release lease when response finishes\n    const leaseId = decision.leaseId;\n    res.on(\"finish\", () => {\n      governor.release(leaseId, {\n        outcome: (res.statusCode ?? 200) < 400 ? \"success\" : \"error\",\n      });\n    });\n\n    next();\n  };\n}\n\n/** Safely convert a header value to string. */\nfunction asString(value: string | string[] | undefined): string | undefined {\n  if (Array.isArray(value)) return value[0];\n  return value;\n}\n"],"mappings":";AA+FO,SAAS,mBACd,SAC+E;AAC/E,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,IAAI;AAEJ,SAAO,CAAC,KAAK,KAAK,SAAS;AACzB,UAAM,UAAU,aACZ,WAAW,GAAG,IACb,SAAS,IAAI,QAAQ,YAAY,CAAC,KAAK,IAAI,MAAM;AAEtD,UAAM,UAA0B;AAAA,MAC9B;AAAA,MACA,QAAQ,YAAY,UAAU,GAAG,IAAI,IAAI;AAAA,MACzC,UAAU,cAAc,YAAY,GAAG,IAAI;AAAA,MAC3C,UAAU,cAAc,YAAY,GAAG,IAAI;AAAA,IAC7C;AAEA,UAAM,WAAW,SAAS,QAAQ,OAAO;AAEzC,QAAI,CAAC,SAAS,SAAS;AACrB,UAAI,QAAQ;AACV,eAAO,KAAK,KAAK,QAAgD;AACjE;AAAA,MACF;AAGA,UAAI,UAAU,eAAe,OAAO,KAAK,KAAK,SAAS,eAAe,GAAI,CAAC,CAAC;AAC5E,UAAI,OAAO,GAAG,EAAE,KAAK;AAAA,QACnB,OAAO;AAAA,QACP,QAAQ,SAAS;AAAA,QACjB,cAAc,SAAS;AAAA,QACvB,gBAAgB,SAAS;AAAA,MAC3B,CAAC;AACD;AAAA,IACF;AAGA,UAAM,UAAU,SAAS;AACzB,QAAI,GAAG,UAAU,MAAM;AACrB,eAAS,QAAQ,SAAS;AAAA,QACxB,UAAU,IAAI,cAAc,OAAO,MAAM,YAAY;AAAA,MACvD,CAAC;AAAA,IACH,CAAC;AAED,SAAK;AAAA,EACP;AACF;AAGA,SAAS,SAAS,OAA0D;AAC1E,MAAI,MAAM,QAAQ,KAAK,EAAG,QAAO,MAAM,CAAC;AACxC,SAAO;AACT;","names":[]}