@tanstack/pacer 0.1.0

package/dist/cjs/async-queuer.d.cts

@@ -0,0 +1,197 @@
+import { QueuePosition } from './queuer.cjs';
+export interface AsyncQueuerOptions<TValue> {
+    /**
+     * Default position to add items to the queuer
+     * @default 'back'
+     */
+    addItemsTo?: QueuePosition;
+    /**
+     * Maximum number of concurrent tasks to process
+     */
+    concurrency?: number;
+    /**
+     * Default position to get items from during processing
+     * @default 'front'
+     */
+    getItemsFrom?: QueuePosition;
+    /**
+     * Function to determine priority of items in the queuer
+     * Higher priority items will be processed first
+     * If not provided, will use static priority values attached to tasks
+     */
+    getPriority?: (item: () => Promise<TValue>) => number;
+    /**
+     * Initial items to populate the queuer with
+     */
+    initialItems?: Array<(() => Promise<TValue>) & {
+        priority?: number;
+    }>;
+    /**
+     * Maximum number of items allowed in the queuer
+     */
+    maxSize?: number;
+    /**
+     * Callback fired whenever an item is removed from the queuer
+     */
+    onGetNextItem?: (item: () => Promise<TValue>, queuer: AsyncQueuer<TValue>) => void;
+    /**
+     * Callback fired whenever an item is added or removed from the queuer
+     */
+    onUpdate?: (queuer: AsyncQueuer<TValue>) => void;
+    /**
+     * Whether the queuer should start processing tasks immediately
+     */
+    started?: boolean;
+    /**
+     * Time in milliseconds to wait between processing items
+     */
+    wait?: number;
+}
+/**
+ * A flexible asynchronous queuer that processes tasks with configurable concurrency control.
+ *
+ * Features:
+ * - Priority queuer support via getPriority option
+ * - Configurable concurrency limit
+ * - Task success/error/completion callbacks
+ * - FIFO (First In First Out) or LIFO (Last In First Out) queuer behavior
+ * - Pause/resume task processing
+ * - Task cancellation
+ *
+ * Tasks are processed concurrently up to the configured concurrency limit. When a task completes,
+ * the next pending task is processed if below the concurrency limit.
+ *
+ * @example
+ * ```ts
+ * const queuer = new AsyncQueuer<string>({ concurrency: 2 });
+ *
+ * queuer.addItem(async () => {
+ *   return 'Hello';
+ * });
+ *
+ * queuer.start();
+ *
+ * queuer.onSuccess((result) => {
+ *   console.log(result); // 'Hello'
+ * });
+ * ```
+ */
+export declare class AsyncQueuer<TValue> {
+    protected options: Required<AsyncQueuerOptions<TValue>>;
+    private items;
+    private activeItems;
+    private onSuccessCallbacks;
+    private onErrorCallbacks;
+    private onSettledCallbacks;
+    private running;
+    private pendingTick;
+    private executionCount;
+    constructor(initialOptions?: AsyncQueuerOptions<TValue>);
+    /**
+     * Updates the queuer options
+     * Returns the new options state
+     */
+    setOptions(newOptions: Partial<AsyncQueuerOptions<TValue>>): AsyncQueuerOptions<TValue>;
+    /**
+     * Processes items in the queuer
+     */
+    protected tick(): void;
+    /**
+     * Adds a task to the queuer
+     */
+    addItem(fn: (() => Promise<TValue>) & {
+        priority?: number;
+    }, position?: QueuePosition, runOnUpdate?: boolean): Promise<TValue>;
+    /**
+     * Removes and returns an item from the queuer
+     */
+    getNextItem(position?: QueuePosition): (() => Promise<TValue>) | undefined;
+    /**
+     * Returns an item without removing it
+     */
+    peek(position?: QueuePosition): (() => Promise<TValue>) | undefined;
+    /**
+     * Returns true if the queuer is empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Returns true if the queuer is full
+     */
+    isFull(): boolean;
+    /**
+     * Returns the current size of the queuer
+     */
+    size(): number;
+    /**
+     * Removes all items from the queuer
+     */
+    clear(): void;
+    /**
+     * Resets the queuer to its initial state
+     */
+    reset(withInitialItems?: boolean): void;
+    /**
+     * Returns a copy of all items in the queuer
+     */
+    getAllItems(): Array<() => Promise<TValue>>;
+    /**
+     * Returns the number of items that have been removed from the queuer
+     */
+    getExecutionCount(): number;
+    /**
+     * Returns the active items
+     */
+    getActiveItems(): Array<() => Promise<TValue>>;
+    /**
+     * Returns the pending items
+     */
+    getPendingItems(): Array<() => Promise<TValue>>;
+    /**
+     * Adds a callback to be called when a task succeeds
+     */
+    onSuccess(cb: (result: TValue) => void): () => void;
+    /**
+     * Adds a callback to be called when a task errors
+     */
+    onError(cb: (error: Error) => void): () => void;
+    /**
+     * Adds a callback to be called when a task is settled
+     */
+    onSettled(cb: (result: TValue | Error) => void): () => void;
+    /**
+     * Starts the queuer and processes items
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the queuer from processing items
+     */
+    stop(): void;
+    /**
+     * Returns true if the queuer is running
+     */
+    isRunning(): boolean;
+    /**
+     * Returns true if the queuer is running but has no items to process
+     */
+    isIdle(): boolean;
+}
+/**
+ * Creates a new AsyncQueuer instance with the given options and returns a bound addItem function.
+ * The queuer is automatically started and ready to process items.
+ *
+ * @example
+ * ```ts
+ * const enqueue = asyncQueue<string>();
+ *
+ * // Add items to be processed
+ * enqueue(async () => {
+ *   return 'Hello';
+ * });
+ * ```
+ *
+ * @param options - Configuration options for the AsyncQueuer
+ * @returns A bound addItem function that can be used to add tasks to the queuer
+ */
+export declare function asyncQueue<TValue>(options?: AsyncQueuerOptions<TValue>): (fn: (() => Promise<TValue>) & {
+    priority?: number;
+}, position?: QueuePosition, runOnUpdate?: boolean) => Promise<TValue>;

package/dist/cjs/async-rate-limiter.cjs

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+class AsyncRateLimiter {
+  constructor(fn, initialOptions) {
+    this.fn = fn;
+    this.executionCount = 0;
+    this.rejectionCount = 0;
+    this.executionTimes = [];
+    this.options = {
+      enabled: true,
+      ...initialOptions
+    };
+  }
+  /**
+   * Updates the rate limiter options
+   * Returns the new options state
+   */
+  setOptions(newOptions) {
+    this.options = {
+      ...this.options,
+      ...newOptions
+    };
+    return this.options;
+  }
+  /**
+   * Returns the number of times the function has been executed
+   */
+  getExecutionCount() {
+    return this.executionCount;
+  }
+  /**
+   * Returns the number of times the function has been rejected
+   */
+  getRejectionCount() {
+    return this.rejectionCount;
+  }
+  /**
+   * Returns the number of remaining executions allowed in the current window
+   */
+  getRemainingInWindow() {
+    this.cleanupOldExecutions();
+    return Math.max(0, this.options.limit - this.executionTimes.length);
+  }
+  /**
+   * Attempts to execute the rate-limited function if within the configured limits.
+   * Will reject execution if the number of calls in the current window exceeds the limit.
+   * If execution is allowed, waits for any previous execution to complete before proceeding.
+   *
+   * @example
+   * ```ts
+   * const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });
+   *
+   * // First 5 calls will execute
+   * await rateLimiter.maybeExecute('arg1', 'arg2');
+   *
+   * // Additional calls within the window will be rejected
+   * await rateLimiter.maybeExecute('arg1', 'arg2'); // Rejected
+   * ```
+   */
+  async maybeExecute(...args) {
+    this.cleanupOldExecutions();
+    if (this.executionTimes.length < this.options.limit) {
+      await this.executeFunction(...args);
+      return true;
+    }
+    this.rejectFunction();
+    return false;
+  }
+  async executeFunction(...args) {
+    if (!this.options.enabled) return;
+    const now = Date.now();
+    this.executionCount++;
+    this.executionTimes.push(now);
+    try {
+      await this.fn(...args);
+    } catch (error) {
+      if (this.options.onError) {
+        try {
+          this.options.onError(error);
+        } catch {
+        }
+      }
+      throw error;
+    } finally {
+    }
+  }
+  rejectFunction() {
+    this.rejectionCount++;
+    if (this.options.onReject) {
+      const oldestExecution = Math.min(...this.executionTimes);
+      const msUntilNextWindow = oldestExecution + this.options.window - Date.now();
+      this.options.onReject({
+        msUntilNextWindow,
+        currentExecutions: this.executionTimes.length,
+        limit: this.options.limit,
+        rejectionCount: this.rejectionCount
+      });
+    }
+  }
+  cleanupOldExecutions() {
+    const now = Date.now();
+    const windowStart = now - this.options.window;
+    this.executionTimes = this.executionTimes.filter(
+      (time) => time > windowStart
+    );
+  }
+  /**
+   * Resets the rate limiter state
+   */
+  reset() {
+    this.executionTimes = [];
+    this.executionCount = 0;
+    this.rejectionCount = 0;
+  }
+}
+function asyncRateLimit(fn, initialOptions) {
+  const rateLimiter = new AsyncRateLimiter(fn, initialOptions);
+  return rateLimiter.maybeExecute.bind(rateLimiter);
+}
+exports.AsyncRateLimiter = AsyncRateLimiter;
+exports.asyncRateLimit = asyncRateLimit;
+//# sourceMappingURL=async-rate-limiter.cjs.map

package/dist/cjs/async-rate-limiter.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-rate-limiter.cjs","sources":["../../src/async-rate-limiter.ts"],"sourcesContent":["import type { RateLimitRejectionInfo } from './rate-limiter'\n\n/**\n * Options for configuring an async rate-limited function\n */\nexport interface AsyncRateLimiterOptions {\n  /**\n   * Whether the rate limiter is enabled. When disabled, maybeExecute will not trigger any executions.\n   * Defaults to true.\n   */\n  enabled?: boolean\n  /**\n   * Maximum number of executions allowed within the time window\n   */\n  limit: number\n  /**\n   * Time window in milliseconds within which the limit applies\n   */\n  window: number\n  /**\n   * Optional callback function that is called when an execution is rejected due to rate limiting\n   */\n  onReject?: (info: RateLimitRejectionInfo) => void\n  /**\n   * Optional error handler for when the rate-limited function throws\n   */\n  onError?: (error: unknown) => void\n}\n\n/**\n * A class that creates an async rate-limited function.\n *\n * Rate limiting is a simple approach that allows a function to execute up to a limit within a time window,\n * then blocks all subsequent calls until the window passes. This can lead to \"bursty\" behavior where\n * all executions happen immediately, followed by a complete block.\n *\n * For smoother execution patterns, consider using:\n * - Throttling: Ensures consistent spacing between executions (e.g. max once per 200ms)\n * - Debouncing: Waits for a pause in calls before executing (e.g. after 500ms of no calls)\n *\n * Rate limiting is best used for hard API limits or resource constraints. For UI updates or\n * smoothing out frequent events, throttling or debouncing usually provide better user experience.\n *\n * @example\n * ```ts\n * const rateLimiter = new AsyncRateLimiter(\n *   async (id: string) => await api.getData(id),\n *   { limit: 5, window: 1000 } // 5 calls per second\n * );\n *\n * // Will execute immediately until limit reached, then block\n * await rateLimiter.maybeExecute('123');\n * ```\n */\nexport class AsyncRateLimiter<\n  TFn extends (...args: Array<any>) => Promise<any>,\n  TArgs extends Parameters<TFn>,\n> {\n  private executionCount = 0\n  private rejectionCount = 0\n  private executionTimes: Array<number> = []\n  private options: AsyncRateLimiterOptions\n\n  constructor(\n    private fn: TFn,\n    initialOptions: AsyncRateLimiterOptions,\n  ) {\n    this.options = {\n      enabled: true,\n      ...initialOptions,\n    }\n  }\n\n  /**\n   * Updates the rate limiter options\n   * Returns the new options state\n   */\n  setOptions(\n    newOptions: Partial<AsyncRateLimiterOptions>,\n  ): AsyncRateLimiterOptions {\n    this.options = {\n      ...this.options,\n      ...newOptions,\n    }\n    return this.options\n  }\n\n  /**\n   * Returns the number of times the function has been executed\n   */\n  getExecutionCount(): number {\n    return this.executionCount\n  }\n\n  /**\n   * Returns the number of times the function has been rejected\n   */\n  getRejectionCount(): number {\n    return this.rejectionCount\n  }\n\n  /**\n   * Returns the number of remaining executions allowed in the current window\n   */\n  getRemainingInWindow(): number {\n    this.cleanupOldExecutions()\n    return Math.max(0, this.options.limit - this.executionTimes.length)\n  }\n\n  /**\n   * Attempts to execute the rate-limited function if within the configured limits.\n   * Will reject execution if the number of calls in the current window exceeds the limit.\n   * If execution is allowed, waits for any previous execution to complete before proceeding.\n   *\n   * @example\n   * ```ts\n   * const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });\n   *\n   * // First 5 calls will execute\n   * await rateLimiter.maybeExecute('arg1', 'arg2');\n   *\n   * // Additional calls within the window will be rejected\n   * await rateLimiter.maybeExecute('arg1', 'arg2'); // Rejected\n   * ```\n   */\n  async maybeExecute(...args: TArgs): Promise<boolean> {\n    this.cleanupOldExecutions()\n\n    if (this.executionTimes.length < this.options.limit) {\n      await this.executeFunction(...args)\n      return true\n    }\n\n    this.rejectFunction()\n    return false\n  }\n\n  private async executeFunction(...args: TArgs): Promise<void> {\n    if (!this.options.enabled) return\n    const now = Date.now()\n    this.executionCount++\n    this.executionTimes.push(now)\n\n    try {\n      await this.fn(...args)\n    } catch (error) {\n      if (this.options.onError) {\n        try {\n          this.options.onError(error)\n        } catch {\n          // Ignore errors from error handler\n        }\n      }\n      throw error\n    } finally {\n    }\n  }\n\n  private rejectFunction(): void {\n    this.rejectionCount++\n    if (this.options.onReject) {\n      const oldestExecution = Math.min(...this.executionTimes)\n      const msUntilNextWindow =\n        oldestExecution + this.options.window - Date.now()\n\n      this.options.onReject({\n        msUntilNextWindow,\n        currentExecutions: this.executionTimes.length,\n        limit: this.options.limit,\n        rejectionCount: this.rejectionCount,\n      })\n    }\n  }\n\n  private cleanupOldExecutions(): void {\n    const now = Date.now()\n    const windowStart = now - this.options.window\n    this.executionTimes = this.executionTimes.filter(\n      (time) => time > windowStart,\n    )\n  }\n\n  /**\n   * Resets the rate limiter state\n   */\n  reset(): void {\n    this.executionTimes = []\n    this.executionCount = 0\n    this.rejectionCount = 0\n  }\n}\n\n/**\n * Creates an async rate-limited function that will execute the provided function up to a maximum number of times within a time window.\n *\n * Note that rate limiting is a simpler form of execution control compared to throttling or debouncing:\n * - A rate limiter will allow all executions until the limit is reached, then block all subsequent calls until the window resets\n * - A throttler ensures even spacing between executions, which can be better for consistent performance\n * - A debouncer collapses multiple calls into one, which is better for handling bursts of events\n *\n * Consider using throttle() or debounce() if you need more intelligent execution control. Use rate limiting when you specifically\n * need to enforce a hard limit on the number of executions within a time period.\n *\n * @example\n * ```ts\n * // Rate limit to 5 calls per minute\n * const rateLimited = asyncRateLimit(makeApiCall, {\n *   limit: 5,\n *   window: 60000,\n *   onReject: ({ msUntilNextWindow }) => {\n *     console.log(`Rate limit exceeded. Try again in ${msUntilNextWindow}ms`);\n *   }\n * });\n *\n * // First 5 calls will execute immediately\n * // Additional calls will be rejected until the minute window resets\n * await rateLimited();\n *\n * // For more even execution, consider using throttle instead:\n * const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds\n * ```\n */\nexport function asyncRateLimit<\n  TFn extends (...args: Array<any>) => Promise<any>,\n>(fn: TFn, initialOptions: Omit<AsyncRateLimiterOptions, 'enabled'>) {\n  const rateLimiter = new AsyncRateLimiter(fn, initialOptions)\n  return rateLimiter.maybeExecute.bind(rateLimiter)\n}\n"],"names":[],"mappings":";;AAsDO,MAAM,iBAGX;AAAA,EAMA,YACU,IACR,gBACA;AAFQ,SAAA,KAAA;AANV,SAAQ,iBAAiB;AACzB,SAAQ,iBAAiB;AACzB,SAAQ,iBAAgC,CAAC;AAOvC,SAAK,UAAU;AAAA,MACb,SAAS;AAAA,MACT,GAAG;AAAA,IACL;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOF,WACE,YACyB;AACzB,SAAK,UAAU;AAAA,MACb,GAAG,KAAK;AAAA,MACR,GAAG;AAAA,IACL;AACA,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,oBAA4B;AAC1B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,oBAA4B;AAC1B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,uBAA+B;AAC7B,SAAK,qBAAqB;AACnB,WAAA,KAAK,IAAI,GAAG,KAAK,QAAQ,QAAQ,KAAK,eAAe,MAAM;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBpE,MAAM,gBAAgB,MAA+B;AACnD,SAAK,qBAAqB;AAE1B,QAAI,KAAK,eAAe,SAAS,KAAK,QAAQ,OAAO;AAC7C,YAAA,KAAK,gBAAgB,GAAG,IAAI;AAC3B,aAAA;AAAA,IAAA;AAGT,SAAK,eAAe;AACb,WAAA;AAAA,EAAA;AAAA,EAGT,MAAc,mBAAmB,MAA4B;AACvD,QAAA,CAAC,KAAK,QAAQ,QAAS;AACrB,UAAA,MAAM,KAAK,IAAI;AAChB,SAAA;AACA,SAAA,eAAe,KAAK,GAAG;AAExB,QAAA;AACI,YAAA,KAAK,GAAG,GAAG,IAAI;AAAA,aACd,OAAO;AACV,UAAA,KAAK,QAAQ,SAAS;AACpB,YAAA;AACG,eAAA,QAAQ,QAAQ,KAAK;AAAA,QAAA,QACpB;AAAA,QAAA;AAAA,MAER;AAEI,YAAA;AAAA,IAAA,UACN;AAAA,IAAA;AAAA,EACF;AAAA,EAGM,iBAAuB;AACxB,SAAA;AACD,QAAA,KAAK,QAAQ,UAAU;AACzB,YAAM,kBAAkB,KAAK,IAAI,GAAG,KAAK,cAAc;AACvD,YAAM,oBACJ,kBAAkB,KAAK,QAAQ,SAAS,KAAK,IAAI;AAEnD,WAAK,QAAQ,SAAS;AAAA,QACpB;AAAA,QACA,mBAAmB,KAAK,eAAe;AAAA,QACvC,OAAO,KAAK,QAAQ;AAAA,QACpB,gBAAgB,KAAK;AAAA,MAAA,CACtB;AAAA,IAAA;AAAA,EACH;AAAA,EAGM,uBAA6B;AAC7B,UAAA,MAAM,KAAK,IAAI;AACf,UAAA,cAAc,MAAM,KAAK,QAAQ;AAClC,SAAA,iBAAiB,KAAK,eAAe;AAAA,MACxC,CAAC,SAAS,OAAO;AAAA,IACnB;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMF,QAAc;AACZ,SAAK,iBAAiB,CAAC;AACvB,SAAK,iBAAiB;AACtB,SAAK,iBAAiB;AAAA,EAAA;AAE1B;AAgCgB,SAAA,eAEd,IAAS,gBAA0D;AACnE,QAAM,cAAc,IAAI,iBAAiB,IAAI,cAAc;AACpD,SAAA,YAAY,aAAa,KAAK,WAAW;AAClD;;;"}

package/dist/cjs/async-rate-limiter.d.cts

@@ -0,0 +1,132 @@
+import { RateLimitRejectionInfo } from './rate-limiter.cjs';
+/**
+ * Options for configuring an async rate-limited function
+ */
+export interface AsyncRateLimiterOptions {
+    /**
+     * Whether the rate limiter is enabled. When disabled, maybeExecute will not trigger any executions.
+     * Defaults to true.
+     */
+    enabled?: boolean;
+    /**
+     * Maximum number of executions allowed within the time window
+     */
+    limit: number;
+    /**
+     * Time window in milliseconds within which the limit applies
+     */
+    window: number;
+    /**
+     * Optional callback function that is called when an execution is rejected due to rate limiting
+     */
+    onReject?: (info: RateLimitRejectionInfo) => void;
+    /**
+     * Optional error handler for when the rate-limited function throws
+     */
+    onError?: (error: unknown) => void;
+}
+/**
+ * A class that creates an async rate-limited function.
+ *
+ * Rate limiting is a simple approach that allows a function to execute up to a limit within a time window,
+ * then blocks all subsequent calls until the window passes. This can lead to "bursty" behavior where
+ * all executions happen immediately, followed by a complete block.
+ *
+ * For smoother execution patterns, consider using:
+ * - Throttling: Ensures consistent spacing between executions (e.g. max once per 200ms)
+ * - Debouncing: Waits for a pause in calls before executing (e.g. after 500ms of no calls)
+ *
+ * Rate limiting is best used for hard API limits or resource constraints. For UI updates or
+ * smoothing out frequent events, throttling or debouncing usually provide better user experience.
+ *
+ * @example
+ * ```ts
+ * const rateLimiter = new AsyncRateLimiter(
+ *   async (id: string) => await api.getData(id),
+ *   { limit: 5, window: 1000 } // 5 calls per second
+ * );
+ *
+ * // Will execute immediately until limit reached, then block
+ * await rateLimiter.maybeExecute('123');
+ * ```
+ */
+export declare class AsyncRateLimiter<TFn extends (...args: Array<any>) => Promise<any>, TArgs extends Parameters<TFn>> {
+    private fn;
+    private executionCount;
+    private rejectionCount;
+    private executionTimes;
+    private options;
+    constructor(fn: TFn, initialOptions: AsyncRateLimiterOptions);
+    /**
+     * Updates the rate limiter options
+     * Returns the new options state
+     */
+    setOptions(newOptions: Partial<AsyncRateLimiterOptions>): AsyncRateLimiterOptions;
+    /**
+     * Returns the number of times the function has been executed
+     */
+    getExecutionCount(): number;
+    /**
+     * Returns the number of times the function has been rejected
+     */
+    getRejectionCount(): number;
+    /**
+     * Returns the number of remaining executions allowed in the current window
+     */
+    getRemainingInWindow(): number;
+    /**
+     * Attempts to execute the rate-limited function if within the configured limits.
+     * Will reject execution if the number of calls in the current window exceeds the limit.
+     * If execution is allowed, waits for any previous execution to complete before proceeding.
+     *
+     * @example
+     * ```ts
+     * const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });
+     *
+     * // First 5 calls will execute
+     * await rateLimiter.maybeExecute('arg1', 'arg2');
+     *
+     * // Additional calls within the window will be rejected
+     * await rateLimiter.maybeExecute('arg1', 'arg2'); // Rejected
+     * ```
+     */
+    maybeExecute(...args: TArgs): Promise<boolean>;
+    private executeFunction;
+    private rejectFunction;
+    private cleanupOldExecutions;
+    /**
+     * Resets the rate limiter state
+     */
+    reset(): void;
+}
+/**
+ * Creates an async rate-limited function that will execute the provided function up to a maximum number of times within a time window.
+ *
+ * Note that rate limiting is a simpler form of execution control compared to throttling or debouncing:
+ * - A rate limiter will allow all executions until the limit is reached, then block all subsequent calls until the window resets
+ * - A throttler ensures even spacing between executions, which can be better for consistent performance
+ * - A debouncer collapses multiple calls into one, which is better for handling bursts of events
+ *
+ * Consider using throttle() or debounce() if you need more intelligent execution control. Use rate limiting when you specifically
+ * need to enforce a hard limit on the number of executions within a time period.
+ *
+ * @example
+ * ```ts
+ * // Rate limit to 5 calls per minute
+ * const rateLimited = asyncRateLimit(makeApiCall, {
+ *   limit: 5,
+ *   window: 60000,
+ *   onReject: ({ msUntilNextWindow }) => {
+ *     console.log(`Rate limit exceeded. Try again in ${msUntilNextWindow}ms`);
+ *   }
+ * });
+ *
+ * // First 5 calls will execute immediately
+ * // Additional calls will be rejected until the minute window resets
+ * await rateLimited();
+ *
+ * // For more even execution, consider using throttle instead:
+ * const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds
+ * ```
+ */
+export declare function asyncRateLimit<TFn extends (...args: Array<any>) => Promise<any>>(fn: TFn, initialOptions: Omit<AsyncRateLimiterOptions, 'enabled'>): (...args: Parameters<TFn>) => Promise<boolean>;

package/dist/cjs/async-throttler.cjs

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const defaultOptions = {
+  enabled: true,
+  onError: () => {
+  },
+  wait: 0
+};
+class AsyncThrottler {
+  constructor(fn, initialOptions) {
+    this.fn = fn;
+    this.abortController = null;
+    this.executionCount = 0;
+    this.isExecuting = false;
+    this.isScheduled = false;
+    this.nextExecutionTime = 0;
+    this.options = {
+      ...defaultOptions,
+      ...initialOptions
+    };
+  }
+  /**
+   * Updates the throttler options
+   * Returns the new options state
+   */
+  setOptions(newOptions) {
+    this.options = {
+      ...this.options,
+      ...newOptions
+    };
+    return this.options;
+  }
+  /**
+   * Returns the number of times the function has been executed
+   */
+  getExecutionCount() {
+    return this.executionCount;
+  }
+  /**
+   * Returns the next execution time
+   */
+  getNextExecutionTime() {
+    return this.nextExecutionTime;
+  }
+  /**
+   * Cancels any pending execution
+   */
+  cancel() {
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+    this.isScheduled = false;
+    this.lastArgs = void 0;
+  }
+  /**
+   * Attempts to execute the throttled function
+   * If a call is already in progress, it may be blocked or queued depending on the `wait` option
+   */
+  async maybeExecute(...args) {
+    this.lastArgs = args;
+    if (this.isScheduled) return;
+    this.isScheduled = true;
+    this.abortController = new AbortController();
+    const signal = this.abortController.signal;
+    try {
+      while (this.isExecuting) {
+        await this.delay(this.options.wait, signal);
+      }
+      while (Date.now() < this.nextExecutionTime) {
+        await this.delay(this.nextExecutionTime - Date.now(), signal);
+      }
+      this.isScheduled = false;
+      this.isExecuting = true;
+      await this.executeFunction(...this.lastArgs);
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        return;
+      }
+      try {
+        this.options.onError(error);
+      } catch {
+      }
+    } finally {
+      this.nextExecutionTime = Date.now() + this.options.wait;
+      this.isExecuting = false;
+      this.abortController = null;
+    }
+  }
+  delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(resolve, ms);
+      signal.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(timeout);
+          reject(new Error("AbortError"));
+        },
+        { once: true }
+      );
+    });
+  }
+  async executeFunction(...args) {
+    if (!this.options.enabled) return;
+    this.executionCount++;
+    await this.fn(...args);
+  }
+}
+function asyncThrottle(fn, initialOptions) {
+  const asyncThrottler = new AsyncThrottler(fn, initialOptions);
+  return asyncThrottler.maybeExecute.bind(asyncThrottler);
+}
+exports.AsyncThrottler = AsyncThrottler;
+exports.asyncThrottle = asyncThrottle;
+//# sourceMappingURL=async-throttler.cjs.map

package/dist/cjs/async-throttler.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-throttler.cjs","sources":["../../src/async-throttler.ts"],"sourcesContent":["/**\n * Options for configuring an async throttled function\n */\nexport interface AsyncThrottlerOptions {\n  /**\n   * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.\n   * Defaults to true.\n   */\n  enabled?: boolean\n  /**\n   * Time window in milliseconds during which the function can only be executed once\n   * Defaults to 0ms\n   */\n  wait: number\n  /**\n   * Optional error handler for when the throttled function throws\n   */\n  onError?: (error: unknown) => void\n}\n\nconst defaultOptions: Required<AsyncThrottlerOptions> = {\n  enabled: true,\n  onError: () => {},\n  wait: 0,\n}\n\n/**\n * A class that creates an async throttled function.\n *\n * Throttling limits how often a function can be executed, allowing only one execution within a specified time window.\n * Unlike debouncing which resets the delay timer on each call, throttling ensures the function executes at a\n * regular interval regardless of how often it's called.\n *\n * This is useful for rate-limiting API calls, handling scroll/resize events, or any scenario where you want to\n * ensure a maximum execution frequency.\n *\n * @example\n * ```ts\n * const throttler = new AsyncThrottler(async (value: string) => {\n *   await saveToAPI(value);\n * }, { wait: 1000 });\n *\n * // Will only execute once per second no matter how often called\n * inputElement.addEventListener('input', () => {\n *   throttler.maybeExecute(inputElement.value);\n * });\n * ```\n */\nexport class AsyncThrottler<\n  TFn extends (...args: Array<any>) => Promise<any>,\n  TArgs extends Parameters<TFn>,\n> {\n  private abortController: AbortController | null = null\n  private executionCount = 0\n  private isExecuting = false\n  private isScheduled = false\n  private lastArgs: TArgs | undefined\n  private nextExecutionTime = 0\n  private options: Required<AsyncThrottlerOptions>\n\n  constructor(\n    private fn: TFn,\n    initialOptions: AsyncThrottlerOptions,\n  ) {\n    this.options = {\n      ...defaultOptions,\n      ...initialOptions,\n    }\n  }\n\n  /**\n   * Updates the throttler options\n   * Returns the new options state\n   */\n  setOptions(\n    newOptions: Partial<AsyncThrottlerOptions>,\n  ): Required<AsyncThrottlerOptions> {\n    this.options = {\n      ...this.options,\n      ...newOptions,\n    }\n    return this.options\n  }\n\n  /**\n   * Returns the number of times the function has been executed\n   */\n  getExecutionCount(): number {\n    return this.executionCount\n  }\n\n  /**\n   * Returns the next execution time\n   */\n  getNextExecutionTime(): number {\n    return this.nextExecutionTime\n  }\n\n  /**\n   * Cancels any pending execution\n   */\n  cancel(): void {\n    if (this.abortController) {\n      this.abortController.abort()\n      this.abortController = null\n    }\n    this.isScheduled = false\n    this.lastArgs = undefined\n  }\n\n  /**\n   * Attempts to execute the throttled function\n   * If a call is already in progress, it may be blocked or queued depending on the `wait` option\n   */\n  async maybeExecute(...args: TArgs): Promise<void> {\n    this.lastArgs = args\n    if (this.isScheduled) return\n    this.isScheduled = true\n\n    this.abortController = new AbortController()\n    const signal = this.abortController.signal\n\n    try {\n      while (this.isExecuting) {\n        await this.delay(this.options.wait, signal)\n      }\n\n      while (Date.now() < this.nextExecutionTime) {\n        await this.delay(this.nextExecutionTime - Date.now(), signal)\n      }\n\n      this.isScheduled = false\n      this.isExecuting = true\n\n      await this.executeFunction(...this.lastArgs)\n    } catch (error) {\n      if (error instanceof Error && error.name === 'AbortError') {\n        return // Silent return on cancellation\n      }\n      try {\n        this.options.onError(error)\n      } catch {\n        // Ignore errors from error handler\n      }\n    } finally {\n      this.nextExecutionTime = Date.now() + this.options.wait\n      this.isExecuting = false\n      this.abortController = null\n    }\n  }\n\n  private delay(ms: number, signal: AbortSignal): Promise<void> {\n    return new Promise((resolve, reject) => {\n      const timeout = setTimeout(resolve, ms)\n      signal.addEventListener(\n        'abort',\n        () => {\n          clearTimeout(timeout)\n          reject(new Error('AbortError'))\n        },\n        { once: true },\n      )\n    })\n  }\n\n  private async executeFunction(...args: TArgs): Promise<void> {\n    if (!this.options.enabled) return\n    this.executionCount++\n    await this.fn(...args)\n  }\n}\n\n/**\n * Creates an async throttled function that limits how often the function can execute.\n * The throttled function will execute at most once per wait period, even if called multiple times.\n * If called while executing, it will wait until execution completes before scheduling the next call.\n *\n * @example\n * ```ts\n * const throttled = asyncThrottle(async () => {\n *   await someAsyncOperation();\n * }, { wait: 1000 });\n *\n * // This will execute at most once per second\n * await throttled();\n * await throttled(); // Waits 1 second before executing\n * ```\n */\nexport function asyncThrottle<\n  TFn extends (...args: Array<any>) => Promise<any>,\n>(fn: TFn, initialOptions: Omit<AsyncThrottlerOptions, 'enabled'>) {\n  const asyncThrottler = new AsyncThrottler(fn, initialOptions)\n  return asyncThrottler.maybeExecute.bind(asyncThrottler)\n}\n"],"names":[],"mappings":";;AAoBA,MAAM,iBAAkD;AAAA,EACtD,SAAS;AAAA,EACT,SAAS,MAAM;AAAA,EAAC;AAAA,EAChB,MAAM;AACR;AAwBO,MAAM,eAGX;AAAA,EASA,YACU,IACR,gBACA;AAFQ,SAAA,KAAA;AATV,SAAQ,kBAA0C;AAClD,SAAQ,iBAAiB;AACzB,SAAQ,cAAc;AACtB,SAAQ,cAAc;AAEtB,SAAQ,oBAAoB;AAO1B,SAAK,UAAU;AAAA,MACb,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOF,WACE,YACiC;AACjC,SAAK,UAAU;AAAA,MACb,GAAG,KAAK;AAAA,MACR,GAAG;AAAA,IACL;AACA,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,oBAA4B;AAC1B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,uBAA+B;AAC7B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,SAAe;AACb,QAAI,KAAK,iBAAiB;AACxB,WAAK,gBAAgB,MAAM;AAC3B,WAAK,kBAAkB;AAAA,IAAA;AAEzB,SAAK,cAAc;AACnB,SAAK,WAAW;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOlB,MAAM,gBAAgB,MAA4B;AAChD,SAAK,WAAW;AAChB,QAAI,KAAK,YAAa;AACtB,SAAK,cAAc;AAEd,SAAA,kBAAkB,IAAI,gBAAgB;AACrC,UAAA,SAAS,KAAK,gBAAgB;AAEhC,QAAA;AACF,aAAO,KAAK,aAAa;AACvB,cAAM,KAAK,MAAM,KAAK,QAAQ,MAAM,MAAM;AAAA,MAAA;AAG5C,aAAO,KAAK,QAAQ,KAAK,mBAAmB;AAC1C,cAAM,KAAK,MAAM,KAAK,oBAAoB,KAAK,OAAO,MAAM;AAAA,MAAA;AAG9D,WAAK,cAAc;AACnB,WAAK,cAAc;AAEnB,YAAM,KAAK,gBAAgB,GAAG,KAAK,QAAQ;AAAA,aACpC,OAAO;AACd,UAAI,iBAAiB,SAAS,MAAM,SAAS,cAAc;AACzD;AAAA,MAAA;AAEE,UAAA;AACG,aAAA,QAAQ,QAAQ,KAAK;AAAA,MAAA,QACpB;AAAA,MAAA;AAAA,IAER,UACA;AACA,WAAK,oBAAoB,KAAK,IAAI,IAAI,KAAK,QAAQ;AACnD,WAAK,cAAc;AACnB,WAAK,kBAAkB;AAAA,IAAA;AAAA,EACzB;AAAA,EAGM,MAAM,IAAY,QAAoC;AAC5D,WAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AAChC,YAAA,UAAU,WAAW,SAAS,EAAE;AAC/B,aAAA;AAAA,QACL;AAAA,QACA,MAAM;AACJ,uBAAa,OAAO;AACb,iBAAA,IAAI,MAAM,YAAY,CAAC;AAAA,QAChC;AAAA,QACA,EAAE,MAAM,KAAK;AAAA,MACf;AAAA,IAAA,CACD;AAAA,EAAA;AAAA,EAGH,MAAc,mBAAmB,MAA4B;AACvD,QAAA,CAAC,KAAK,QAAQ,QAAS;AACtB,SAAA;AACC,UAAA,KAAK,GAAG,GAAG,IAAI;AAAA,EAAA;AAEzB;AAkBgB,SAAA,cAEd,IAAS,gBAAwD;AACjE,QAAM,iBAAiB,IAAI,eAAe,IAAI,cAAc;AACrD,SAAA,eAAe,aAAa,KAAK,cAAc;AACxD;;;"}