@fetchmax/plugin-rate-limit 1.0.0

package/dist/index.cjs

@@ -0,0 +1,159 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  RateLimitError: () => RateLimitError,
+  default: () => index_default,
+  rateLimitPlugin: () => rateLimitPlugin
+});
+module.exports = __toCommonJS(index_exports);
+var RateLimitError = class _RateLimitError extends Error {
+  constructor(message, queueSize) {
+    super(message);
+    this.name = "RateLimitError";
+    this.queueSize = queueSize;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _RateLimitError);
+    }
+  }
+};
+function rateLimitPlugin(config) {
+  const {
+    maxRequests,
+    perMilliseconds,
+    queueOnLimit = true,
+    maxQueueSize = Infinity,
+    onRateLimit
+  } = config;
+  const timestamps = [];
+  const queue = [];
+  let queueProcessorTimeout = null;
+  function removeExpiredTimestamps() {
+    const now = Date.now();
+    const cutoff = now - perMilliseconds;
+    while (timestamps.length > 0 && timestamps[0] < cutoff) {
+      timestamps.shift();
+    }
+  }
+  function canMakeRequest() {
+    removeExpiredTimestamps();
+    return timestamps.length < maxRequests;
+  }
+  function getWaitTime() {
+    if (timestamps.length === 0) return 0;
+    const oldestTimestamp = timestamps[0];
+    const now = Date.now();
+    const elapsed = now - oldestTimestamp;
+    return Math.max(0, perMilliseconds - elapsed);
+  }
+  function processQueue() {
+    queueProcessorTimeout = null;
+    removeExpiredTimestamps();
+    while (queue.length > 0 && canMakeRequest()) {
+      const item = queue.shift();
+      if (item) {
+        timestamps.push(Date.now());
+        item.resolve();
+      }
+    }
+    scheduleQueueProcessing();
+  }
+  function scheduleQueueProcessing() {
+    if (queueProcessorTimeout) {
+      clearTimeout(queueProcessorTimeout);
+      queueProcessorTimeout = null;
+    }
+    if (queue.length === 0) {
+      return;
+    }
+    const waitTime = getWaitTime();
+    queueProcessorTimeout = setTimeout(() => {
+      processQueue();
+    }, waitTime + 10);
+  }
+  async function waitForSlot() {
+    removeExpiredTimestamps();
+    if (canMakeRequest()) {
+      timestamps.push(Date.now());
+      return;
+    }
+    if (queue.length >= maxQueueSize) {
+      throw new RateLimitError(
+        `Rate limit queue is full (${maxQueueSize} requests queued)`,
+        queue.length
+      );
+    }
+    if (!queueOnLimit) {
+      throw new RateLimitError(
+        `Rate limit exceeded: ${maxRequests} requests per ${perMilliseconds}ms`,
+        queue.length
+      );
+    }
+    const waitTime = getWaitTime();
+    if (onRateLimit) {
+      onRateLimit(queue.length, waitTime);
+    }
+    console.log(
+      `[RateLimit] Request queued. ${queue.length + 1} in queue. Wait time: ~${waitTime}ms`
+    );
+    const promise = new Promise((resolve, reject) => {
+      queue.push({ resolve, reject });
+    });
+    scheduleQueueProcessing();
+    return promise;
+  }
+  const plugin = {
+    name: "rate-limit",
+    async onRequest(request, _context) {
+      await waitForSlot();
+      return request;
+    },
+    /**
+     * Get rate limit statistics
+     */
+    getStats() {
+      removeExpiredTimestamps();
+      return {
+        requestCount: timestamps.length,
+        queueSize: queue.length,
+        timestamps: [...timestamps]
+      };
+    },
+    /**
+     * Reset rate limiter (clear timestamps and queue)
+     */
+    reset() {
+      timestamps.length = 0;
+      queue.length = 0;
+      if (queueProcessorTimeout) {
+        clearTimeout(queueProcessorTimeout);
+        queueProcessorTimeout = null;
+      }
+    }
+  };
+  return plugin;
+}
+var index_default = rateLimitPlugin;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RateLimitError,
+  rateLimitPlugin
+});

package/dist/index.d.cts

@@ -0,0 +1,51 @@
+import { Plugin } from '@fetchmax/core';
+
+interface RateLimitConfig {
+    /** Maximum number of requests allowed */
+    maxRequests: number;
+    /** Time window in milliseconds */
+    perMilliseconds: number;
+    /** Queue requests when limit is reached (default: true) */
+    queueOnLimit?: boolean;
+    /** Maximum queue size (default: Infinity) */
+    maxQueueSize?: number;
+    /** Callback when rate limit is hit */
+    onRateLimit?: (queueSize: number, waitTime: number) => void;
+}
+declare class RateLimitError extends Error {
+    name: string;
+    queueSize: number;
+    constructor(message: string, queueSize: number);
+}
+interface RateLimitPlugin extends Plugin {
+    getStats: () => {
+        requestCount: number;
+        queueSize: number;
+        timestamps: number[];
+    };
+    reset: () => void;
+}
+/**
+ * Rate Limit Plugin
+ *
+ * Controls the rate of requests to prevent overwhelming servers or hitting API limits.
+ *
+ * @example
+ * ```ts
+ * // Allow 10 requests per second
+ * const client = new HttpClient().use(rateLimitPlugin({
+ *   maxRequests: 10,
+ *   perMilliseconds: 1000
+ * }));
+ *
+ * // Allow 100 requests per minute, throw error instead of queueing
+ * const client = new HttpClient().use(rateLimitPlugin({
+ *   maxRequests: 100,
+ *   perMilliseconds: 60000,
+ *   queueOnLimit: false
+ * }));
+ * ```
+ */
+declare function rateLimitPlugin(config: RateLimitConfig): RateLimitPlugin;
+
+export { type RateLimitConfig, RateLimitError, type RateLimitPlugin, rateLimitPlugin as default, rateLimitPlugin };

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import { Plugin } from '@fetchmax/core';
+
+interface RateLimitConfig {
+    /** Maximum number of requests allowed */
+    maxRequests: number;
+    /** Time window in milliseconds */
+    perMilliseconds: number;
+    /** Queue requests when limit is reached (default: true) */
+    queueOnLimit?: boolean;
+    /** Maximum queue size (default: Infinity) */
+    maxQueueSize?: number;
+    /** Callback when rate limit is hit */
+    onRateLimit?: (queueSize: number, waitTime: number) => void;
+}
+declare class RateLimitError extends Error {
+    name: string;
+    queueSize: number;
+    constructor(message: string, queueSize: number);
+}
+interface RateLimitPlugin extends Plugin {
+    getStats: () => {
+        requestCount: number;
+        queueSize: number;
+        timestamps: number[];
+    };
+    reset: () => void;
+}
+/**
+ * Rate Limit Plugin
+ *
+ * Controls the rate of requests to prevent overwhelming servers or hitting API limits.
+ *
+ * @example
+ * ```ts
+ * // Allow 10 requests per second
+ * const client = new HttpClient().use(rateLimitPlugin({
+ *   maxRequests: 10,
+ *   perMilliseconds: 1000
+ * }));
+ *
+ * // Allow 100 requests per minute, throw error instead of queueing
+ * const client = new HttpClient().use(rateLimitPlugin({
+ *   maxRequests: 100,
+ *   perMilliseconds: 60000,
+ *   queueOnLimit: false
+ * }));
+ * ```
+ */
+declare function rateLimitPlugin(config: RateLimitConfig): RateLimitPlugin;
+
+export { type RateLimitConfig, RateLimitError, type RateLimitPlugin, rateLimitPlugin as default, rateLimitPlugin };

package/dist/index.js

@@ -0,0 +1,133 @@
+// src/index.ts
+var RateLimitError = class _RateLimitError extends Error {
+  constructor(message, queueSize) {
+    super(message);
+    this.name = "RateLimitError";
+    this.queueSize = queueSize;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _RateLimitError);
+    }
+  }
+};
+function rateLimitPlugin(config) {
+  const {
+    maxRequests,
+    perMilliseconds,
+    queueOnLimit = true,
+    maxQueueSize = Infinity,
+    onRateLimit
+  } = config;
+  const timestamps = [];
+  const queue = [];
+  let queueProcessorTimeout = null;
+  function removeExpiredTimestamps() {
+    const now = Date.now();
+    const cutoff = now - perMilliseconds;
+    while (timestamps.length > 0 && timestamps[0] < cutoff) {
+      timestamps.shift();
+    }
+  }
+  function canMakeRequest() {
+    removeExpiredTimestamps();
+    return timestamps.length < maxRequests;
+  }
+  function getWaitTime() {
+    if (timestamps.length === 0) return 0;
+    const oldestTimestamp = timestamps[0];
+    const now = Date.now();
+    const elapsed = now - oldestTimestamp;
+    return Math.max(0, perMilliseconds - elapsed);
+  }
+  function processQueue() {
+    queueProcessorTimeout = null;
+    removeExpiredTimestamps();
+    while (queue.length > 0 && canMakeRequest()) {
+      const item = queue.shift();
+      if (item) {
+        timestamps.push(Date.now());
+        item.resolve();
+      }
+    }
+    scheduleQueueProcessing();
+  }
+  function scheduleQueueProcessing() {
+    if (queueProcessorTimeout) {
+      clearTimeout(queueProcessorTimeout);
+      queueProcessorTimeout = null;
+    }
+    if (queue.length === 0) {
+      return;
+    }
+    const waitTime = getWaitTime();
+    queueProcessorTimeout = setTimeout(() => {
+      processQueue();
+    }, waitTime + 10);
+  }
+  async function waitForSlot() {
+    removeExpiredTimestamps();
+    if (canMakeRequest()) {
+      timestamps.push(Date.now());
+      return;
+    }
+    if (queue.length >= maxQueueSize) {
+      throw new RateLimitError(
+        `Rate limit queue is full (${maxQueueSize} requests queued)`,
+        queue.length
+      );
+    }
+    if (!queueOnLimit) {
+      throw new RateLimitError(
+        `Rate limit exceeded: ${maxRequests} requests per ${perMilliseconds}ms`,
+        queue.length
+      );
+    }
+    const waitTime = getWaitTime();
+    if (onRateLimit) {
+      onRateLimit(queue.length, waitTime);
+    }
+    console.log(
+      `[RateLimit] Request queued. ${queue.length + 1} in queue. Wait time: ~${waitTime}ms`
+    );
+    const promise = new Promise((resolve, reject) => {
+      queue.push({ resolve, reject });
+    });
+    scheduleQueueProcessing();
+    return promise;
+  }
+  const plugin = {
+    name: "rate-limit",
+    async onRequest(request, _context) {
+      await waitForSlot();
+      return request;
+    },
+    /**
+     * Get rate limit statistics
+     */
+    getStats() {
+      removeExpiredTimestamps();
+      return {
+        requestCount: timestamps.length,
+        queueSize: queue.length,
+        timestamps: [...timestamps]
+      };
+    },
+    /**
+     * Reset rate limiter (clear timestamps and queue)
+     */
+    reset() {
+      timestamps.length = 0;
+      queue.length = 0;
+      if (queueProcessorTimeout) {
+        clearTimeout(queueProcessorTimeout);
+        queueProcessorTimeout = null;
+      }
+    }
+  };
+  return plugin;
+}
+var index_default = rateLimitPlugin;
+export {
+  RateLimitError,
+  index_default as default,
+  rateLimitPlugin
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@fetchmax/plugin-rate-limit",
+  "version": "1.0.0",
+  "description": "Rate limiting plugin for FetchMax to control request frequency",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+  },
+  "keywords": [
+    "fetchmax",
+    "plugin",
+    "rate-limit",
+    "throttle",
+    "http",
+    "fetch"
+  ],
+  "author": "FetchMax Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fetchmax/fetchmax.git",
+    "directory": "packages/plugins/rate-limit"
+  },
+  "bugs": {
+    "url": "https://github.com/fetchmax/fetchmax/issues"
+  },
+  "homepage": "https://github.com/fetchmax/fetchmax#readme",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@fetchmax/core": "^1.0.0"
+  },
+  "devDependencies": {
+    "@fetchmax/core": "*",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3"
+  }
+}