@h1s97x/request-queue 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 h1s97x
+
+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/dist/index.cjs

@@ -0,0 +1,223 @@
+'use strict';
+
+const tokenBucket = require('@h1s97x/token-bucket');
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+const DEFAULT_OPTIONS = {
+  maxSize: 100,
+  maxWaitTime: 6e4,
+  bucketCapacity: 20,
+  requestsPerSecond: 10
+};
+class RequestQueueManager {
+  constructor(options = {}) {
+    __publicField(this, "queue", []);
+    __publicField(this, "options");
+    __publicField(this, "rateLimiter");
+    __publicField(this, "stats");
+    __publicField(this, "cleanupInterval", null);
+    __publicField(this, "idCounter", 0);
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.rateLimiter = new tokenBucket.TokenBucketRateLimiter({
+      capacity: this.options.bucketCapacity,
+      refillRate: this.options.requestsPerSecond
+    });
+    this.stats = {
+      waiting: 0,
+      processing: 0,
+      completed: 0,
+      failed: 0,
+      timeout: 0,
+      maxQueueLength: 0,
+      totalProcessed: 0
+    };
+    this.cleanupInterval = setInterval(() => {
+      this.cleanup();
+    }, 1e4);
+  }
+  generateId() {
+    return `job_${Date.now()}_${++this.idCounter}`;
+  }
+  /**
+   * Enqueue a task for rate-limited execution.
+   * Returns a promise that resolves with the task's result
+   * once a rate-limit token is acquired and the task completes.
+   */
+  async enqueue(task, timeout) {
+    const jobId = this.generateId();
+    const waitTimeout = timeout ?? this.options.maxWaitTime;
+    if (this.queue.length >= this.options.maxSize) {
+      throw new Error(`QUEUE_FULL: Queue is full (${this.options.maxSize})`);
+    }
+    this.stats.maxQueueLength = Math.max(
+      this.stats.maxQueueLength,
+      this.queue.length + 1
+    );
+    return new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        const index = this.queue.findIndex((j) => j.id === jobId);
+        if (index !== -1) {
+          this.queue.splice(index, 1);
+          this.stats.waiting--;
+        }
+        this.stats.timeout++;
+        reject(new Error(`TIMEOUT: Task waited too long (${waitTimeout}ms)`));
+      }, waitTimeout);
+      const job = {
+        id: jobId,
+        task,
+        resolve,
+        reject,
+        createdAt: Date.now(),
+        timeout: timeoutId,
+        status: "waiting"
+      };
+      this.queue.push(job);
+      this.stats.waiting++;
+      this.processQueue();
+    });
+  }
+  /**
+   * Process the queue: acquire tokens and execute tasks
+   */
+  async processQueue() {
+    while (this.queue.length > 0) {
+      if (!this.rateLimiter.tryAcquire()) {
+        await new Promise((r) => setTimeout(r, 50));
+        continue;
+      }
+      const job = this.queue.shift();
+      if (!job)
+        break;
+      clearTimeout(job.timeout);
+      this.stats.waiting--;
+      this.stats.processing++;
+      this.stats.totalProcessed++;
+      job.status = "processing";
+      try {
+        const result = await job.task();
+        job.status = "completed";
+        this.stats.processing--;
+        this.stats.completed++;
+        job.resolve(result);
+      } catch (error) {
+        job.status = "failed";
+        this.stats.processing--;
+        this.stats.failed++;
+        job.reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+  }
+  /**
+   * Get queue statistics
+   */
+  getStats() {
+    const now = Date.now();
+    const totalWaitTime = this.queue.reduce(
+      (sum, job) => sum + (now - job.createdAt),
+      0
+    );
+    const avgWaitTime = this.queue.length > 0 ? totalWaitTime / this.queue.length : 0;
+    return {
+      ...this.stats,
+      avgWaitTime,
+      currentTokenBucket: this.rateLimiter.getStatus()
+    };
+  }
+  /**
+   * Estimate wait time for a new task
+   */
+  getEstimatedWaitTime() {
+    if (this.queue.length === 0)
+      return 0;
+    const avgWaitPerRequest = 1e3 / this.options.requestsPerSecond;
+    return Math.ceil(this.queue.length * avgWaitPerRequest);
+  }
+  /**
+   * Check if a new task can be enqueued
+   */
+  canEnqueue() {
+    if (this.queue.length >= this.options.maxSize) {
+      return {
+        allowed: false,
+        reason: `Queue is full (${this.queue.length}/${this.options.maxSize})`
+      };
+    }
+    const estimatedWait = this.getEstimatedWaitTime();
+    if (estimatedWait > this.options.maxWaitTime) {
+      return {
+        allowed: false,
+        reason: `Estimated wait too long (${Math.round(estimatedWait / 1e3)}s)`,
+        estimatedWait
+      };
+    }
+    return { allowed: true, estimatedWait };
+  }
+  /**
+   * Periodic cleanup: evict stale tasks that exceeded maxWaitTime
+   */
+  cleanup() {
+    const now = Date.now();
+    const expired = [];
+    for (let i = this.queue.length - 1; i >= 0; i--) {
+      const job = this.queue[i];
+      if (now - job.createdAt > this.options.maxWaitTime) {
+        expired.push(job);
+        this.queue.splice(i, 1);
+        this.stats.waiting--;
+      }
+    }
+    for (const job of expired) {
+      clearTimeout(job.timeout);
+      job.status = "timeout";
+      this.stats.timeout++;
+      job.reject(new Error(`CLEANUP: Task evicted after ${this.options.maxWaitTime}ms`));
+    }
+  }
+  /**
+   * Update rate limiting config
+   */
+  updateRateLimit(refillRate, capacity) {
+    this.options.requestsPerSecond = refillRate;
+    if (capacity !== void 0) {
+      this.options.bucketCapacity = capacity;
+    }
+    this.rateLimiter.updateConfig(refillRate, capacity);
+  }
+  /**
+   * Clear all queued tasks
+   */
+  clear() {
+    for (const job of this.queue) {
+      clearTimeout(job.timeout);
+      job.reject(new Error("CLEARED: Queue has been cleared"));
+    }
+    this.queue = [];
+    this.stats.waiting = 0;
+  }
+  /**
+   * Destroy the queue manager and release resources
+   */
+  destroy() {
+    if (this.cleanupInterval !== null) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    this.clear();
+  }
+}
+let queueInstance = null;
+function getRequestQueue() {
+  if (!queueInstance) {
+    queueInstance = new RequestQueueManager();
+  }
+  return queueInstance;
+}
+
+exports.RequestQueueManager = RequestQueueManager;
+exports.getRequestQueue = getRequestQueue;

package/dist/index.d.cts

@@ -0,0 +1,91 @@
+import { TokenBucketRateLimiter } from '@h1s97x/token-bucket';
+
+/**
+ * FIFO request queue manager with rate limiting
+ *
+ * Features:
+ * - FIFO order for fairness
+ * - Configurable max queue length
+ * - Rate-limited task execution via token bucket
+ * - Timeout-based task eviction
+ * - Wait time estimation
+ * - Periodic stale cleanup
+ */
+
+interface QueueOptions {
+    /** Maximum queue length */
+    maxSize: number;
+    /** Max task wait time in ms */
+    maxWaitTime: number;
+    /** Token bucket capacity (burst) */
+    bucketCapacity: number;
+    /** Requests allowed per second */
+    requestsPerSecond: number;
+}
+interface QueueStats {
+    waiting: number;
+    processing: number;
+    completed: number;
+    failed: number;
+    timeout: number;
+    avgWaitTime: number;
+    maxQueueLength: number;
+    totalProcessed: number;
+    currentTokenBucket: ReturnType<TokenBucketRateLimiter['getStatus']>;
+}
+declare class RequestQueueManager {
+    private queue;
+    private options;
+    private rateLimiter;
+    private stats;
+    private cleanupInterval;
+    private idCounter;
+    constructor(options?: Partial<QueueOptions>);
+    private generateId;
+    /**
+     * Enqueue a task for rate-limited execution.
+     * Returns a promise that resolves with the task's result
+     * once a rate-limit token is acquired and the task completes.
+     */
+    enqueue<T>(task: () => Promise<T>, timeout?: number): Promise<T>;
+    /**
+     * Process the queue: acquire tokens and execute tasks
+     */
+    private processQueue;
+    /**
+     * Get queue statistics
+     */
+    getStats(): QueueStats;
+    /**
+     * Estimate wait time for a new task
+     */
+    getEstimatedWaitTime(): number;
+    /**
+     * Check if a new task can be enqueued
+     */
+    canEnqueue(): {
+        allowed: boolean;
+        reason?: string;
+        estimatedWait?: number;
+    };
+    /**
+     * Periodic cleanup: evict stale tasks that exceeded maxWaitTime
+     */
+    private cleanup;
+    /**
+     * Update rate limiting config
+     */
+    updateRateLimit(refillRate: number, capacity?: number): void;
+    /**
+     * Clear all queued tasks
+     */
+    clear(): void;
+    /**
+     * Destroy the queue manager and release resources
+     */
+    destroy(): void;
+}
+declare function getRequestQueue(): RequestQueueManager;
+
+export { RequestQueueManager, getRequestQueue };
+export type { QueueOptions, QueueStats };

package/dist/index.d.mts

@@ -0,0 +1,91 @@
+import { TokenBucketRateLimiter } from '@h1s97x/token-bucket';
+
+/**
+ * FIFO request queue manager with rate limiting
+ *
+ * Features:
+ * - FIFO order for fairness
+ * - Configurable max queue length
+ * - Rate-limited task execution via token bucket
+ * - Timeout-based task eviction
+ * - Wait time estimation
+ * - Periodic stale cleanup
+ */
+
+interface QueueOptions {
+    /** Maximum queue length */
+    maxSize: number;
+    /** Max task wait time in ms */
+    maxWaitTime: number;
+    /** Token bucket capacity (burst) */
+    bucketCapacity: number;
+    /** Requests allowed per second */
+    requestsPerSecond: number;
+}
+interface QueueStats {
+    waiting: number;
+    processing: number;
+    completed: number;
+    failed: number;
+    timeout: number;
+    avgWaitTime: number;
+    maxQueueLength: number;
+    totalProcessed: number;
+    currentTokenBucket: ReturnType<TokenBucketRateLimiter['getStatus']>;
+}
+declare class RequestQueueManager {
+    private queue;
+    private options;
+    private rateLimiter;
+    private stats;
+    private cleanupInterval;
+    private idCounter;
+    constructor(options?: Partial<QueueOptions>);
+    private generateId;
+    /**
+     * Enqueue a task for rate-limited execution.
+     * Returns a promise that resolves with the task's result
+     * once a rate-limit token is acquired and the task completes.
+     */
+    enqueue<T>(task: () => Promise<T>, timeout?: number): Promise<T>;
+    /**
+     * Process the queue: acquire tokens and execute tasks
+     */
+    private processQueue;
+    /**
+     * Get queue statistics
+     */
+    getStats(): QueueStats;
+    /**
+     * Estimate wait time for a new task
+     */
+    getEstimatedWaitTime(): number;
+    /**
+     * Check if a new task can be enqueued
+     */
+    canEnqueue(): {
+        allowed: boolean;
+        reason?: string;
+        estimatedWait?: number;
+    };
+    /**
+     * Periodic cleanup: evict stale tasks that exceeded maxWaitTime
+     */
+    private cleanup;
+    /**
+     * Update rate limiting config
+     */
+    updateRateLimit(refillRate: number, capacity?: number): void;
+    /**
+     * Clear all queued tasks
+     */
+    clear(): void;
+    /**
+     * Destroy the queue manager and release resources
+     */
+    destroy(): void;
+}
+declare function getRequestQueue(): RequestQueueManager;
+
+export { RequestQueueManager, getRequestQueue };
+export type { QueueOptions, QueueStats };

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+import { TokenBucketRateLimiter } from '@h1s97x/token-bucket';
+
+/**
+ * FIFO request queue manager with rate limiting
+ *
+ * Features:
+ * - FIFO order for fairness
+ * - Configurable max queue length
+ * - Rate-limited task execution via token bucket
+ * - Timeout-based task eviction
+ * - Wait time estimation
+ * - Periodic stale cleanup
+ */
+
+interface QueueOptions {
+    /** Maximum queue length */
+    maxSize: number;
+    /** Max task wait time in ms */
+    maxWaitTime: number;
+    /** Token bucket capacity (burst) */
+    bucketCapacity: number;
+    /** Requests allowed per second */
+    requestsPerSecond: number;
+}
+interface QueueStats {
+    waiting: number;
+    processing: number;
+    completed: number;
+    failed: number;
+    timeout: number;
+    avgWaitTime: number;
+    maxQueueLength: number;
+    totalProcessed: number;
+    currentTokenBucket: ReturnType<TokenBucketRateLimiter['getStatus']>;
+}
+declare class RequestQueueManager {
+    private queue;
+    private options;
+    private rateLimiter;
+    private stats;
+    private cleanupInterval;
+    private idCounter;
+    constructor(options?: Partial<QueueOptions>);
+    private generateId;
+    /**
+     * Enqueue a task for rate-limited execution.
+     * Returns a promise that resolves with the task's result
+     * once a rate-limit token is acquired and the task completes.
+     */
+    enqueue<T>(task: () => Promise<T>, timeout?: number): Promise<T>;
+    /**
+     * Process the queue: acquire tokens and execute tasks
+     */
+    private processQueue;
+    /**
+     * Get queue statistics
+     */
+    getStats(): QueueStats;
+    /**
+     * Estimate wait time for a new task
+     */
+    getEstimatedWaitTime(): number;
+    /**
+     * Check if a new task can be enqueued
+     */
+    canEnqueue(): {
+        allowed: boolean;
+        reason?: string;
+        estimatedWait?: number;
+    };
+    /**
+     * Periodic cleanup: evict stale tasks that exceeded maxWaitTime
+     */
+    private cleanup;
+    /**
+     * Update rate limiting config
+     */
+    updateRateLimit(refillRate: number, capacity?: number): void;
+    /**
+     * Clear all queued tasks
+     */
+    clear(): void;
+    /**
+     * Destroy the queue manager and release resources
+     */
+    destroy(): void;
+}
+declare function getRequestQueue(): RequestQueueManager;
+
+export { RequestQueueManager, getRequestQueue };
+export type { QueueOptions, QueueStats };

package/dist/index.mjs

@@ -0,0 +1,220 @@
+import { TokenBucketRateLimiter } from '@h1s97x/token-bucket';
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+const DEFAULT_OPTIONS = {
+  maxSize: 100,
+  maxWaitTime: 6e4,
+  bucketCapacity: 20,
+  requestsPerSecond: 10
+};
+class RequestQueueManager {
+  constructor(options = {}) {
+    __publicField(this, "queue", []);
+    __publicField(this, "options");
+    __publicField(this, "rateLimiter");
+    __publicField(this, "stats");
+    __publicField(this, "cleanupInterval", null);
+    __publicField(this, "idCounter", 0);
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.rateLimiter = new TokenBucketRateLimiter({
+      capacity: this.options.bucketCapacity,
+      refillRate: this.options.requestsPerSecond
+    });
+    this.stats = {
+      waiting: 0,
+      processing: 0,
+      completed: 0,
+      failed: 0,
+      timeout: 0,
+      maxQueueLength: 0,
+      totalProcessed: 0
+    };
+    this.cleanupInterval = setInterval(() => {
+      this.cleanup();
+    }, 1e4);
+  }
+  generateId() {
+    return `job_${Date.now()}_${++this.idCounter}`;
+  }
+  /**
+   * Enqueue a task for rate-limited execution.
+   * Returns a promise that resolves with the task's result
+   * once a rate-limit token is acquired and the task completes.
+   */
+  async enqueue(task, timeout) {
+    const jobId = this.generateId();
+    const waitTimeout = timeout ?? this.options.maxWaitTime;
+    if (this.queue.length >= this.options.maxSize) {
+      throw new Error(`QUEUE_FULL: Queue is full (${this.options.maxSize})`);
+    }
+    this.stats.maxQueueLength = Math.max(
+      this.stats.maxQueueLength,
+      this.queue.length + 1
+    );
+    return new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        const index = this.queue.findIndex((j) => j.id === jobId);
+        if (index !== -1) {
+          this.queue.splice(index, 1);
+          this.stats.waiting--;
+        }
+        this.stats.timeout++;
+        reject(new Error(`TIMEOUT: Task waited too long (${waitTimeout}ms)`));
+      }, waitTimeout);
+      const job = {
+        id: jobId,
+        task,
+        resolve,
+        reject,
+        createdAt: Date.now(),
+        timeout: timeoutId,
+        status: "waiting"
+      };
+      this.queue.push(job);
+      this.stats.waiting++;
+      this.processQueue();
+    });
+  }
+  /**
+   * Process the queue: acquire tokens and execute tasks
+   */
+  async processQueue() {
+    while (this.queue.length > 0) {
+      if (!this.rateLimiter.tryAcquire()) {
+        await new Promise((r) => setTimeout(r, 50));
+        continue;
+      }
+      const job = this.queue.shift();
+      if (!job)
+        break;
+      clearTimeout(job.timeout);
+      this.stats.waiting--;
+      this.stats.processing++;
+      this.stats.totalProcessed++;
+      job.status = "processing";
+      try {
+        const result = await job.task();
+        job.status = "completed";
+        this.stats.processing--;
+        this.stats.completed++;
+        job.resolve(result);
+      } catch (error) {
+        job.status = "failed";
+        this.stats.processing--;
+        this.stats.failed++;
+        job.reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+  }
+  /**
+   * Get queue statistics
+   */
+  getStats() {
+    const now = Date.now();
+    const totalWaitTime = this.queue.reduce(
+      (sum, job) => sum + (now - job.createdAt),
+      0
+    );
+    const avgWaitTime = this.queue.length > 0 ? totalWaitTime / this.queue.length : 0;
+    return {
+      ...this.stats,
+      avgWaitTime,
+      currentTokenBucket: this.rateLimiter.getStatus()
+    };
+  }
+  /**
+   * Estimate wait time for a new task
+   */
+  getEstimatedWaitTime() {
+    if (this.queue.length === 0)
+      return 0;
+    const avgWaitPerRequest = 1e3 / this.options.requestsPerSecond;
+    return Math.ceil(this.queue.length * avgWaitPerRequest);
+  }
+  /**
+   * Check if a new task can be enqueued
+   */
+  canEnqueue() {
+    if (this.queue.length >= this.options.maxSize) {
+      return {
+        allowed: false,
+        reason: `Queue is full (${this.queue.length}/${this.options.maxSize})`
+      };
+    }
+    const estimatedWait = this.getEstimatedWaitTime();
+    if (estimatedWait > this.options.maxWaitTime) {
+      return {
+        allowed: false,
+        reason: `Estimated wait too long (${Math.round(estimatedWait / 1e3)}s)`,
+        estimatedWait
+      };
+    }
+    return { allowed: true, estimatedWait };
+  }
+  /**
+   * Periodic cleanup: evict stale tasks that exceeded maxWaitTime
+   */
+  cleanup() {
+    const now = Date.now();
+    const expired = [];
+    for (let i = this.queue.length - 1; i >= 0; i--) {
+      const job = this.queue[i];
+      if (now - job.createdAt > this.options.maxWaitTime) {
+        expired.push(job);
+        this.queue.splice(i, 1);
+        this.stats.waiting--;
+      }
+    }
+    for (const job of expired) {
+      clearTimeout(job.timeout);
+      job.status = "timeout";
+      this.stats.timeout++;
+      job.reject(new Error(`CLEANUP: Task evicted after ${this.options.maxWaitTime}ms`));
+    }
+  }
+  /**
+   * Update rate limiting config
+   */
+  updateRateLimit(refillRate, capacity) {
+    this.options.requestsPerSecond = refillRate;
+    if (capacity !== void 0) {
+      this.options.bucketCapacity = capacity;
+    }
+    this.rateLimiter.updateConfig(refillRate, capacity);
+  }
+  /**
+   * Clear all queued tasks
+   */
+  clear() {
+    for (const job of this.queue) {
+      clearTimeout(job.timeout);
+      job.reject(new Error("CLEARED: Queue has been cleared"));
+    }
+    this.queue = [];
+    this.stats.waiting = 0;
+  }
+  /**
+   * Destroy the queue manager and release resources
+   */
+  destroy() {
+    if (this.cleanupInterval !== null) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    this.clear();
+  }
+}
+let queueInstance = null;
+function getRequestQueue() {
+  if (!queueInstance) {
+    queueInstance = new RequestQueueManager();
+  }
+  return queueInstance;
+}
+
+export { RequestQueueManager, getRequestQueue };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@h1s97x/request-queue",
+  "version": "0.1.1",
+  "description": "FIFO request queue manager with rate limiting for Node.js and browser",
+  "author": "h1s97x",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@h1s97x/token-bucket": "0.1.1"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.9"
+  },
+  "keywords": [
+    "request-queue",
+    "rate-limiter",
+    "fifo",
+    "throttle",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/h1s97x/toolkit.git",
+    "directory": "packages/request-queue"
+  },
+  "bugs": {
+    "url": "https://github.com/h1s97x/toolkit/issues"
+  },
+  "homepage": "https://github.com/h1s97x/toolkit/tree/main/packages/request-queue",
+  "scripts": {
+    "build": "unbuild",
+    "dev": "unbuild --stub",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}