@ayepi/rate 0.1.0

package/dist/server.d.cts

@@ -0,0 +1,67 @@
+import { Algorithm, RateKeyIO, RateLimitInfo, RateLimitStore, rateLimit as rateLimit$1 } from "./index.cjs";
+import { AnyMiddleware, BoundMiddleware, Json, StackCtx } from "@ayepi/core";
+
+//#region src/server.d.ts
+
+/** The `requires` chain of a middleware def. */
+type ReqOf<M extends AnyMiddleware> = M['__req'];
+/**
+ * Server-side options for binding a {@link rateLimit} def — the limiting policy and
+ * response customization, with `key`/`skip`/`message` typed against the def's
+ * `requires` context.
+ *
+ * @typeParam M - the rate-limit def being bound.
+ */
+interface RateLimitServerOptions<M extends AnyMiddleware> {
+  /** Derive the rate-limit key from the request context (e.g. `io.ctx.user.id`). */
+  readonly key: (io: RateKeyIO<StackCtx<ReqOf<M>>>) => string;
+  /** Max requests (or token-bucket capacity) per window. */
+  readonly limit: number;
+  /** Window length in milliseconds (also the token refill period). */
+  readonly window: number;
+  /** Algorithm (default `'fixed-window'`). */
+  readonly algorithm?: Algorithm;
+  /** Backend store (default an in-process memory store). */
+  readonly store?: RateLimitStore;
+  /** Key prefix/namespace (default `'rl:'`). */
+  readonly prefix?: string;
+  /** Over-limit status code (default `429`). */
+  readonly status?: number;
+  /** Over-limit body — a string, a JSON value, or a function of the limiter info and request. */
+  readonly message?: string | Json | ((info: RateLimitInfo, io: RateKeyIO<StackCtx<ReqOf<M>>>) => string | Json);
+  /** Response headers (draft `RateLimit-*` + `Retry-After` by default; `false` for none; a function for your own). */
+  readonly headers?: boolean | ((info: RateLimitInfo) => Record<string, string>);
+  /**
+   * Also emit the `RateLimit-*` headers on **allowed** (and skipped) responses, not
+   * just the over-limit 429 — so every response advertises the caller's remaining
+   * budget. Default `false`. Uses the same {@link RateLimitServerOptions.headers}
+   * formatting (`Retry-After` is omitted when not rate-limited).
+   */
+  readonly alwaysHeaders?: boolean;
+  /** Bypass the limiter for some requests (e.g. an allow-list). */
+  readonly skip?: (io: RateKeyIO<StackCtx<ReqOf<M>>>) => boolean;
+  /**
+   * What to do when the **store itself errors** (e.g. Redis is down) — `true` serves the
+   * request through (as if allowed, full budget); `false` (default) is fail-**closed**: the
+   * error propagates, so a store outage rejects requests rather than silently lifting the limit.
+   */
+  readonly failOpen?: boolean;
+  /**
+   * Observe a store error. Fires whether or not {@link failOpen} is set (with `failOpen` the
+   * request is then allowed; without it the error still propagates). Off by default; it must
+   * not throw — if it does, the throw is ignored.
+   */
+  readonly onError?: (err: unknown) => void;
+}
+/** Bind a {@link rateLimit} def to its runtime policy. */
+declare function rateLimitServer<M extends AnyMiddleware>(def: M, opts: RateLimitServerOptions<M>): BoundMiddleware<M>;
+/**
+ * The {@link rateLimit} def factory, augmented with a `.server(def, opts)` binder.
+ * Import from `@ayepi/rate/server` in your server entry to bind a def created in a
+ * frontend-safe spec.
+ */
+declare const rateLimit: typeof rateLimit$1 & {
+  server: typeof rateLimitServer;
+};
+//#endregion
+export { RateLimitServerOptions, rateLimit };

package/dist/server.d.ts

@@ -0,0 +1,67 @@
+import { Algorithm, RateKeyIO, RateLimitInfo, RateLimitStore, rateLimit as rateLimit$1 } from "./index.js";
+import { AnyMiddleware, BoundMiddleware, Json, StackCtx } from "@ayepi/core";
+
+//#region src/server.d.ts
+
+/** The `requires` chain of a middleware def. */
+type ReqOf<M extends AnyMiddleware> = M['__req'];
+/**
+ * Server-side options for binding a {@link rateLimit} def — the limiting policy and
+ * response customization, with `key`/`skip`/`message` typed against the def's
+ * `requires` context.
+ *
+ * @typeParam M - the rate-limit def being bound.
+ */
+interface RateLimitServerOptions<M extends AnyMiddleware> {
+  /** Derive the rate-limit key from the request context (e.g. `io.ctx.user.id`). */
+  readonly key: (io: RateKeyIO<StackCtx<ReqOf<M>>>) => string;
+  /** Max requests (or token-bucket capacity) per window. */
+  readonly limit: number;
+  /** Window length in milliseconds (also the token refill period). */
+  readonly window: number;
+  /** Algorithm (default `'fixed-window'`). */
+  readonly algorithm?: Algorithm;
+  /** Backend store (default an in-process memory store). */
+  readonly store?: RateLimitStore;
+  /** Key prefix/namespace (default `'rl:'`). */
+  readonly prefix?: string;
+  /** Over-limit status code (default `429`). */
+  readonly status?: number;
+  /** Over-limit body — a string, a JSON value, or a function of the limiter info and request. */
+  readonly message?: string | Json | ((info: RateLimitInfo, io: RateKeyIO<StackCtx<ReqOf<M>>>) => string | Json);
+  /** Response headers (draft `RateLimit-*` + `Retry-After` by default; `false` for none; a function for your own). */
+  readonly headers?: boolean | ((info: RateLimitInfo) => Record<string, string>);
+  /**
+   * Also emit the `RateLimit-*` headers on **allowed** (and skipped) responses, not
+   * just the over-limit 429 — so every response advertises the caller's remaining
+   * budget. Default `false`. Uses the same {@link RateLimitServerOptions.headers}
+   * formatting (`Retry-After` is omitted when not rate-limited).
+   */
+  readonly alwaysHeaders?: boolean;
+  /** Bypass the limiter for some requests (e.g. an allow-list). */
+  readonly skip?: (io: RateKeyIO<StackCtx<ReqOf<M>>>) => boolean;
+  /**
+   * What to do when the **store itself errors** (e.g. Redis is down) — `true` serves the
+   * request through (as if allowed, full budget); `false` (default) is fail-**closed**: the
+   * error propagates, so a store outage rejects requests rather than silently lifting the limit.
+   */
+  readonly failOpen?: boolean;
+  /**
+   * Observe a store error. Fires whether or not {@link failOpen} is set (with `failOpen` the
+   * request is then allowed; without it the error still propagates). Off by default; it must
+   * not throw — if it does, the throw is ignored.
+   */
+  readonly onError?: (err: unknown) => void;
+}
+/** Bind a {@link rateLimit} def to its runtime policy. */
+declare function rateLimitServer<M extends AnyMiddleware>(def: M, opts: RateLimitServerOptions<M>): BoundMiddleware<M>;
+/**
+ * The {@link rateLimit} def factory, augmented with a `.server(def, opts)` binder.
+ * Import from `@ayepi/rate/server` in your server entry to bind a def created in a
+ * frontend-safe spec.
+ */
+declare const rateLimit: typeof rateLimit$1 & {
+  server: typeof rateLimitServer;
+};
+//#endregion
+export { RateLimitServerOptions, rateLimit };

package/dist/server.js

@@ -0,0 +1,65 @@
+import { limiter, rateLimit as rateLimit$1, rateLimitHeaders, rateLimitResponse } from "./index.js";
+//#region src/server.ts
+/** Bind a {@link rateLimit} def to its runtime policy. */
+function rateLimitServer(def, opts) {
+	const lim = limiter(opts);
+	const message = opts.message;
+	const run = async (io) => {
+		const kio = {
+			req: io.req,
+			ctx: io.ctx
+		};
+		const advertise = (info) => {
+			if (!opts.alwaysHeaders) return;
+			for (const [name, value] of Object.entries(rateLimitHeaders(info, opts.headers))) io.setHeader(name, value);
+		};
+		const fullBudget = () => ({
+			limit: lim.rule.limit,
+			remaining: lim.rule.limit,
+			reset: 0,
+			retryAfter: 0
+		});
+		if (opts.skip?.(kio)) {
+			const skipped = fullBudget();
+			advertise(skipped);
+			return io.next({ ratelimit: skipped });
+		}
+		let result;
+		try {
+			result = await lim.check(opts.key(kio));
+		} catch (err) {
+			try {
+				opts.onError?.(err);
+			} catch {}
+			if (!opts.failOpen) throw err;
+			const allowed = fullBudget();
+			advertise(allowed);
+			return io.next({ ratelimit: allowed });
+		}
+		const info = {
+			limit: result.limit,
+			remaining: result.remaining,
+			reset: result.reset,
+			retryAfter: result.retryAfter
+		};
+		if (!result.allowed) return rateLimitResponse(info, {
+			status: opts.status,
+			headers: opts.headers,
+			message: typeof message === "function" ? (i) => message(i, kio) : message
+		});
+		advertise(info);
+		return io.next({ ratelimit: info });
+	};
+	return {
+		def,
+		impl: run
+	};
+}
+/**
+* The {@link rateLimit} def factory, augmented with a `.server(def, opts)` binder.
+* Import from `@ayepi/rate/server` in your server entry to bind a def created in a
+* frontend-safe spec.
+*/
+const rateLimit = Object.assign(rateLimit$1, { server: rateLimitServer });
+//#endregion
+export { rateLimit };

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@ayepi/rate",
+  "version": "0.1.0",
+  "description": "Rate-limiting middleware for @ayepi/core — pluggable stores, multiple algorithms, customizable 429 responses",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ClickerMonkey/ayepi.git",
+    "directory": "packages/rate"
+  },
+  "homepage": "https://github.com/ClickerMonkey/ayepi/tree/main/packages/rate#readme",
+  "bugs": {
+    "url": "https://github.com/ClickerMonkey/ayepi/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      },
+      "require": {
+        "types": "./dist/server.d.cts",
+        "default": "./dist/server.cjs"
+      }
+    },
+    "./redis": {
+      "import": {
+        "types": "./dist/redis.d.ts",
+        "default": "./dist/redis.js"
+      },
+      "require": {
+        "types": "./dist/redis.d.cts",
+        "default": "./dist/redis.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "ioredis": "^5",
+    "@ayepi/core": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.8",
+    "ioredis": "^5.4.1",
+    "publint": "^0.3.0",
+    "testcontainers": "^10.13.0",
+    "tsdown": "^0.12.0",
+    "vitest": "^2.1.8",
+    "zod": "^4.4.3",
+    "@ayepi/core": "0.1.0"
+  },
+  "keywords": [
+    "ayepi",
+    "@ayepi/core",
+    "rate-limit",
+    "ratelimit",
+    "middleware",
+    "redis",
+    "throttle"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "publint": "publint"
+  }
+}