@tanstack/pacer 0.1.0

package/dist/esm/rate-limiter.js

@@ -0,0 +1,115 @@
+const defaultOptions = {
+  enabled: true,
+  limit: 1,
+  window: 0
+};
+class RateLimiter {
+  constructor(fn, initialOptions) {
+    this.fn = fn;
+    this.executionCount = 0;
+    this.rejectionCount = 0;
+    this.executionTimes = [];
+    this.options = {
+      ...defaultOptions,
+      ...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.
+   *
+   * @example
+   * ```ts
+   * const rateLimiter = new RateLimiter(fn, { limit: 5, window: 1000 });
+   *
+   * // First 5 calls will return true
+   * rateLimiter.maybeExecute('arg1', 'arg2'); // true
+   *
+   * // Additional calls within the window will return false
+   * rateLimiter.maybeExecute('arg1', 'arg2'); // false
+   * ```
+   */
+  maybeExecute(...args) {
+    this.cleanupOldExecutions();
+    if (this.executionTimes.length < this.options.limit) {
+      this.executeFunction(...args);
+      return true;
+    }
+    this.rejectFunction();
+    return false;
+  }
+  executeFunction(...args) {
+    if (!this.options.enabled) return;
+    const now = Date.now();
+    this.executionCount++;
+    this.executionTimes.push(now);
+    this.fn(...args);
+  }
+  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 rateLimit(fn, initialOptions) {
+  const rateLimiter = new RateLimiter(fn, initialOptions);
+  return rateLimiter.maybeExecute.bind(rateLimiter);
+}
+export {
+  RateLimiter,
+  rateLimit
+};
+//# sourceMappingURL=rate-limiter.js.map

package/dist/esm/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sources":["../../src/rate-limiter.ts"],"sourcesContent":["/**\n * Information about a rate limit rejection\n */\nexport interface RateLimitRejectionInfo {\n  /**\n   * Number of milliseconds until the next execution will be possible\n   */\n  msUntilNextWindow: number\n  /**\n   * Current number of executions in the window\n   */\n  currentExecutions: number\n  /**\n   * Maximum allowed executions per window\n   */\n  limit: number\n  /**\n   * Total number of rejections that have occurred\n   */\n  rejectionCount: number\n}\n\n/**\n * Options for configuring a rate-limited function\n */\nexport interface RateLimiterOptions {\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\nconst defaultOptions: Required<Omit<RateLimiterOptions, 'onReject'>> = {\n  enabled: true,\n  limit: 1,\n  window: 0,\n}\n\n/**\n * A class that creates a 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 RateLimiter(\n *   (id: string) => api.getData(id),\n *   { limit: 5, window: 1000 } // 5 calls per second\n * );\n *\n * // Will execute immediately until limit reached, then block\n * rateLimiter.maybeExecute('123');\n * ```\n */\nexport class RateLimiter<\n  TFn extends (...args: Array<any>) => any,\n  TArgs extends Parameters<TFn>,\n> {\n  private executionCount = 0\n  private rejectionCount = 0\n  private executionTimes: Array<number> = []\n  private options: RateLimiterOptions\n\n  constructor(\n    private fn: TFn,\n    initialOptions: RateLimiterOptions,\n  ) {\n    this.options = {\n      ...defaultOptions,\n      ...initialOptions,\n    }\n  }\n\n  /**\n   * Updates the rate limiter options\n   * Returns the new options state\n   */\n  setOptions(newOptions: Partial<RateLimiterOptions>): RateLimiterOptions {\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   *\n   * @example\n   * ```ts\n   * const rateLimiter = new RateLimiter(fn, { limit: 5, window: 1000 });\n   *\n   * // First 5 calls will return true\n   * rateLimiter.maybeExecute('arg1', 'arg2'); // true\n   *\n   * // Additional calls within the window will return false\n   * rateLimiter.maybeExecute('arg1', 'arg2'); // false\n   * ```\n   */\n  maybeExecute(...args: TArgs): boolean {\n    this.cleanupOldExecutions()\n\n    if (this.executionTimes.length < this.options.limit) {\n      this.executeFunction(...args)\n      return true\n    }\n\n    this.rejectFunction()\n\n    return false\n  }\n\n  private executeFunction(...args: TArgs): void {\n    if (!this.options.enabled) return\n    const now = Date.now()\n    this.executionCount++\n    this.executionTimes.push(now)\n    this.fn(...args)\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 a 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 = rateLimit(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 * 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 rateLimit<TFn extends (...args: Array<any>) => any>(\n  fn: TFn,\n  initialOptions: Omit<RateLimiterOptions, 'enabled'>,\n) {\n  const rateLimiter = new RateLimiter(fn, initialOptions)\n  return rateLimiter.maybeExecute.bind(rateLimiter)\n}\n"],"names":[],"mappings":"AA6CA,MAAM,iBAAiE;AAAA,EACrE,SAAS;AAAA,EACT,OAAO;AAAA,EACP,QAAQ;AACV;AA2BO,MAAM,YAGX;AAAA,EAMA,YACU,IACR,gBACA;AAFQ,SAAA,KAAA;AANV,SAAQ,iBAAiB;AACzB,SAAQ,iBAAiB;AACzB,SAAQ,iBAAgC,CAAC;AAOvC,SAAK,UAAU;AAAA,MACb,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOF,WAAW,YAA6D;AACtE,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,EAkBpE,gBAAgB,MAAsB;AACpC,SAAK,qBAAqB;AAE1B,QAAI,KAAK,eAAe,SAAS,KAAK,QAAQ,OAAO;AAC9C,WAAA,gBAAgB,GAAG,IAAI;AACrB,aAAA;AAAA,IAAA;AAGT,SAAK,eAAe;AAEb,WAAA;AAAA,EAAA;AAAA,EAGD,mBAAmB,MAAmB;AACxC,QAAA,CAAC,KAAK,QAAQ,QAAS;AACrB,UAAA,MAAM,KAAK,IAAI;AAChB,SAAA;AACA,SAAA,eAAe,KAAK,GAAG;AACvB,SAAA,GAAG,GAAG,IAAI;AAAA,EAAA;AAAA,EAGT,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,UACd,IACA,gBACA;AACA,QAAM,cAAc,IAAI,YAAY,IAAI,cAAc;AAC/C,SAAA,YAAY,aAAa,KAAK,WAAW;AAClD;"}

package/dist/esm/throttler.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Options for configuring a throttled function
+ */
+export interface ThrottlerOptions {
+    /**
+     * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.
+     * Defaults to true.
+     */
+    enabled?: boolean;
+    /**
+     * Whether to execute on the leading edge of the timeout.
+     * Defaults to true.
+     */
+    leading?: boolean;
+    /**
+     * Whether to execute on the trailing edge of the timeout.
+     * Defaults to true.
+     */
+    trailing?: boolean;
+    /**
+     * Time window in milliseconds during which the function can only be executed once
+     */
+    wait: number;
+}
+/**
+ * A class that creates a throttled function.
+ *
+ * Throttling ensures a function is called at most once within a specified time window.
+ * Unlike debouncing which waits for a pause in calls, throttling guarantees consistent
+ * execution timing regardless of call frequency.
+ *
+ * Supports both leading and trailing edge execution:
+ * - Leading: Execute immediately on first call (default: true)
+ * - Trailing: Execute after wait period if called during throttle (default: true)
+ *
+ * For rate limiting or hard API limits, consider using RateLimiter instead.
+ * For collapsing rapid-fire events, consider using Debouncer.
+ *
+ * @example
+ * ```ts
+ * const throttler = new Throttler(
+ *   (id: string) => api.getData(id),
+ *   { wait: 1000 } // Execute at most once per second
+ * );
+ *
+ * // First call executes immediately
+ * throttler.maybeExecute('123');
+ *
+ * // Subsequent calls within 1000ms are throttled
+ * throttler.maybeExecute('123'); // Throttled
+ * ```
+ */
+export declare class Throttler<TFn extends (...args: Array<any>) => any, TArgs extends Parameters<TFn>> {
+    private fn;
+    private executionCount;
+    private lastArgs;
+    private lastExecutionTime;
+    private options;
+    private timeoutId;
+    constructor(fn: TFn, initialOptions: ThrottlerOptions);
+    /**
+     * Updates the throttler options
+     * Returns the new options state
+     */
+    setOptions(newOptions: Partial<ThrottlerOptions>): Required<ThrottlerOptions>;
+    /**
+     * Returns the number of times the function has been executed
+     */
+    getExecutionCount(): number;
+    /**
+     * Returns the last execution time
+     */
+    getLastExecutionTime(): number;
+    /**
+     * Returns the next execution time
+     */
+    getNextExecutionTime(): number;
+    /**
+     * Attempts to execute the throttled function. The execution behavior depends on the throttler options:
+     *
+     * - If enough time has passed since the last execution (>= wait period):
+     *   - With leading=true: Executes immediately
+     *   - With leading=false: Waits for the next trailing execution
+     *
+     * - If within the wait period:
+     *   - With trailing=true: Schedules execution for end of wait period
+     *   - With trailing=false: Drops the execution
+     *
+     * @example
+     * ```ts
+     * const throttled = new Throttler(fn, { wait: 1000 });
+     *
+     * // First call executes immediately
+     * throttled.maybeExecute('a', 'b');
+     *
+     * // Call during wait period - gets throttled
+     * throttled.maybeExecute('c', 'd');
+     * ```
+     */
+    maybeExecute(...args: TArgs): void;
+    private executeFunction;
+    /**
+     * Cancels any pending trailing execution and clears internal state.
+     *
+     * If a trailing execution is scheduled (due to throttling with trailing=true),
+     * this will prevent that execution from occurring. The internal timeout and
+     * stored arguments will be cleared.
+     *
+     * Has no effect if there is no pending execution.
+     */
+    cancel(): void;
+}
+/**
+ * Creates a throttled function that limits how often the provided function can execute.
+ *
+ * Throttling ensures a function executes at most once within a specified time window,
+ * regardless of how many times it is called. This is useful for rate-limiting
+ * expensive operations or UI updates.
+ *
+ * The throttled function can be configured to execute on the leading and/or trailing
+ * edge of the throttle window via options.
+ *
+ * For handling bursts of events, consider using debounce() instead. For hard execution
+ * limits, consider using rateLimit().
+ *
+ * @example
+ * ```ts
+ * // Basic throttling - max once per second
+ * const throttled = throttle(updateUI, { wait: 1000 });
+ *
+ * // Configure leading/trailing execution
+ * const throttled = throttle(saveData, {
+ *   wait: 2000,
+ *   leading: true,  // Execute immediately on first call
+ *   trailing: true  // Execute again after delay if called during wait
+ * });
+ * ```
+ */
+export declare function throttle<TFn extends (...args: Array<any>) => any>(fn: TFn, initialOptions: Omit<ThrottlerOptions, 'enabled'>): (...args: Parameters<TFn>) => void;

package/dist/esm/throttler.js

@@ -0,0 +1,120 @@
+const defaultOptions = {
+  enabled: true,
+  leading: true,
+  trailing: true,
+  wait: 0
+};
+class Throttler {
+  constructor(fn, initialOptions) {
+    this.fn = fn;
+    this.executionCount = 0;
+    this.lastExecutionTime = 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 last execution time
+   */
+  getLastExecutionTime() {
+    return this.lastExecutionTime;
+  }
+  /**
+   * Returns the next execution time
+   */
+  getNextExecutionTime() {
+    return this.lastExecutionTime + this.options.wait;
+  }
+  /**
+   * Attempts to execute the throttled function. The execution behavior depends on the throttler options:
+   *
+   * - If enough time has passed since the last execution (>= wait period):
+   *   - With leading=true: Executes immediately
+   *   - With leading=false: Waits for the next trailing execution
+   *
+   * - If within the wait period:
+   *   - With trailing=true: Schedules execution for end of wait period
+   *   - With trailing=false: Drops the execution
+   *
+   * @example
+   * ```ts
+   * const throttled = new Throttler(fn, { wait: 1000 });
+   *
+   * // First call executes immediately
+   * throttled.maybeExecute('a', 'b');
+   *
+   * // Call during wait period - gets throttled
+   * throttled.maybeExecute('c', 'd');
+   * ```
+   */
+  maybeExecute(...args) {
+    const now = Date.now();
+    const timeSinceLastExecution = now - this.lastExecutionTime;
+    if (timeSinceLastExecution >= this.options.wait) {
+      if (this.options.leading) {
+        this.executeFunction(...args);
+      }
+      this.lastExecutionTime = now;
+    } else {
+      this.lastArgs = args;
+      if (!this.timeoutId && this.options.trailing) {
+        this.timeoutId = setTimeout(() => {
+          if (this.lastArgs) {
+            this.executeFunction(...this.lastArgs);
+            this.lastArgs = void 0;
+          }
+          this.lastExecutionTime = Date.now();
+          this.timeoutId = void 0;
+        }, this.options.wait - timeSinceLastExecution);
+      }
+    }
+  }
+  executeFunction(...args) {
+    if (!this.options.enabled) return;
+    this.executionCount++;
+    this.fn(...args);
+  }
+  /**
+   * Cancels any pending trailing execution and clears internal state.
+   *
+   * If a trailing execution is scheduled (due to throttling with trailing=true),
+   * this will prevent that execution from occurring. The internal timeout and
+   * stored arguments will be cleared.
+   *
+   * Has no effect if there is no pending execution.
+   */
+  cancel() {
+    if (this.timeoutId) {
+      clearTimeout(this.timeoutId);
+      this.timeoutId = void 0;
+      this.lastArgs = void 0;
+    }
+  }
+}
+function throttle(fn, initialOptions) {
+  const throttler = new Throttler(fn, initialOptions);
+  return throttler.maybeExecute.bind(throttler);
+}
+export {
+  Throttler,
+  throttle
+};
+//# sourceMappingURL=throttler.js.map

package/dist/esm/throttler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttler.js","sources":["../../src/throttler.ts"],"sourcesContent":["/**\n * Options for configuring a throttled function\n */\nexport interface ThrottlerOptions {\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   * Whether to execute on the leading edge of the timeout.\n   * Defaults to true.\n   */\n  leading?: boolean\n  /**\n   * Whether to execute on the trailing edge of the timeout.\n   * Defaults to true.\n   */\n  trailing?: boolean\n  /**\n   * Time window in milliseconds during which the function can only be executed once\n   */\n  wait: number\n}\n\nconst defaultOptions: Required<ThrottlerOptions> = {\n  enabled: true,\n  leading: true,\n  trailing: true,\n  wait: 0,\n}\n\n/**\n * A class that creates a throttled function.\n *\n * Throttling ensures a function is called at most once within a specified time window.\n * Unlike debouncing which waits for a pause in calls, throttling guarantees consistent\n * execution timing regardless of call frequency.\n *\n * Supports both leading and trailing edge execution:\n * - Leading: Execute immediately on first call (default: true)\n * - Trailing: Execute after wait period if called during throttle (default: true)\n *\n * For rate limiting or hard API limits, consider using RateLimiter instead.\n * For collapsing rapid-fire events, consider using Debouncer.\n *\n * @example\n * ```ts\n * const throttler = new Throttler(\n *   (id: string) => api.getData(id),\n *   { wait: 1000 } // Execute at most once per second\n * );\n *\n * // First call executes immediately\n * throttler.maybeExecute('123');\n *\n * // Subsequent calls within 1000ms are throttled\n * throttler.maybeExecute('123'); // Throttled\n * ```\n */\nexport class Throttler<\n  TFn extends (...args: Array<any>) => any,\n  TArgs extends Parameters<TFn>,\n> {\n  private executionCount = 0\n  private lastArgs: TArgs | undefined\n  private lastExecutionTime = 0\n  private options: Required<ThrottlerOptions>\n  private timeoutId: NodeJS.Timeout | undefined\n\n  constructor(\n    private fn: TFn,\n    initialOptions: ThrottlerOptions,\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<ThrottlerOptions>,\n  ): Required<ThrottlerOptions> {\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 last execution time\n   */\n  getLastExecutionTime(): number {\n    return this.lastExecutionTime\n  }\n\n  /**\n   * Returns the next execution time\n   */\n  getNextExecutionTime(): number {\n    return this.lastExecutionTime + this.options.wait\n  }\n\n  /**\n   * Attempts to execute the throttled function. The execution behavior depends on the throttler options:\n   *\n   * - If enough time has passed since the last execution (>= wait period):\n   *   - With leading=true: Executes immediately\n   *   - With leading=false: Waits for the next trailing execution\n   *\n   * - If within the wait period:\n   *   - With trailing=true: Schedules execution for end of wait period\n   *   - With trailing=false: Drops the execution\n   *\n   * @example\n   * ```ts\n   * const throttled = new Throttler(fn, { wait: 1000 });\n   *\n   * // First call executes immediately\n   * throttled.maybeExecute('a', 'b');\n   *\n   * // Call during wait period - gets throttled\n   * throttled.maybeExecute('c', 'd');\n   * ```\n   */\n  maybeExecute(...args: TArgs): void {\n    const now = Date.now()\n    const timeSinceLastExecution = now - this.lastExecutionTime\n\n    // Handle leading execution\n    if (timeSinceLastExecution >= this.options.wait) {\n      if (this.options.leading) {\n        this.executeFunction(...args)\n      }\n      this.lastExecutionTime = now\n    } else {\n      // Store the most recent arguments for potential trailing execution\n      this.lastArgs = args\n\n      // Set up trailing execution if not already scheduled\n      if (!this.timeoutId && this.options.trailing) {\n        this.timeoutId = setTimeout(() => {\n          if (this.lastArgs) {\n            this.executeFunction(...this.lastArgs)\n            this.lastArgs = undefined\n          }\n          this.lastExecutionTime = Date.now()\n          this.timeoutId = undefined\n        }, this.options.wait - timeSinceLastExecution)\n      }\n    }\n  }\n\n  private executeFunction(...args: TArgs): void {\n    if (!this.options.enabled) return\n    this.executionCount++\n    this.fn(...args)\n  }\n\n  /**\n   * Cancels any pending trailing execution and clears internal state.\n   *\n   * If a trailing execution is scheduled (due to throttling with trailing=true),\n   * this will prevent that execution from occurring. The internal timeout and\n   * stored arguments will be cleared.\n   *\n   * Has no effect if there is no pending execution.\n   */\n  cancel(): void {\n    if (this.timeoutId) {\n      clearTimeout(this.timeoutId)\n      this.timeoutId = undefined\n      this.lastArgs = undefined\n    }\n  }\n}\n\n/**\n * Creates a throttled function that limits how often the provided function can execute.\n *\n * Throttling ensures a function executes at most once within a specified time window,\n * regardless of how many times it is called. This is useful for rate-limiting\n * expensive operations or UI updates.\n *\n * The throttled function can be configured to execute on the leading and/or trailing\n * edge of the throttle window via options.\n *\n * For handling bursts of events, consider using debounce() instead. For hard execution\n * limits, consider using rateLimit().\n *\n * @example\n * ```ts\n * // Basic throttling - max once per second\n * const throttled = throttle(updateUI, { wait: 1000 });\n *\n * // Configure leading/trailing execution\n * const throttled = throttle(saveData, {\n *   wait: 2000,\n *   leading: true,  // Execute immediately on first call\n *   trailing: true  // Execute again after delay if called during wait\n * });\n * ```\n */\nexport function throttle<TFn extends (...args: Array<any>) => any>(\n  fn: TFn,\n  initialOptions: Omit<ThrottlerOptions, 'enabled'>,\n) {\n  const throttler = new Throttler(fn, initialOptions)\n  return throttler.maybeExecute.bind(throttler)\n}\n"],"names":[],"mappings":"AAyBA,MAAM,iBAA6C;AAAA,EACjD,SAAS;AAAA,EACT,SAAS;AAAA,EACT,UAAU;AAAA,EACV,MAAM;AACR;AA8BO,MAAM,UAGX;AAAA,EAOA,YACU,IACR,gBACA;AAFQ,SAAA,KAAA;AAPV,SAAQ,iBAAiB;AAEzB,SAAQ,oBAAoB;AAQ1B,SAAK,UAAU;AAAA,MACb,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOF,WACE,YAC4B;AAC5B,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,uBAA+B;AACtB,WAAA,KAAK,oBAAoB,KAAK,QAAQ;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAyB/C,gBAAgB,MAAmB;AAC3B,UAAA,MAAM,KAAK,IAAI;AACf,UAAA,yBAAyB,MAAM,KAAK;AAGtC,QAAA,0BAA0B,KAAK,QAAQ,MAAM;AAC3C,UAAA,KAAK,QAAQ,SAAS;AACnB,aAAA,gBAAgB,GAAG,IAAI;AAAA,MAAA;AAE9B,WAAK,oBAAoB;AAAA,IAAA,OACpB;AAEL,WAAK,WAAW;AAGhB,UAAI,CAAC,KAAK,aAAa,KAAK,QAAQ,UAAU;AACvC,aAAA,YAAY,WAAW,MAAM;AAChC,cAAI,KAAK,UAAU;AACZ,iBAAA,gBAAgB,GAAG,KAAK,QAAQ;AACrC,iBAAK,WAAW;AAAA,UAAA;AAEb,eAAA,oBAAoB,KAAK,IAAI;AAClC,eAAK,YAAY;AAAA,QAChB,GAAA,KAAK,QAAQ,OAAO,sBAAsB;AAAA,MAAA;AAAA,IAC/C;AAAA,EACF;AAAA,EAGM,mBAAmB,MAAmB;AACxC,QAAA,CAAC,KAAK,QAAQ,QAAS;AACtB,SAAA;AACA,SAAA,GAAG,GAAG,IAAI;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYjB,SAAe;AACb,QAAI,KAAK,WAAW;AAClB,mBAAa,KAAK,SAAS;AAC3B,WAAK,YAAY;AACjB,WAAK,WAAW;AAAA,IAAA;AAAA,EAClB;AAEJ;AA4BgB,SAAA,SACd,IACA,gBACA;AACA,QAAM,YAAY,IAAI,UAAU,IAAI,cAAc;AAC3C,SAAA,UAAU,aAAa,KAAK,SAAS;AAC9C;"}

package/package.json

@@ -0,0 +1,150 @@
+{
+  "name": "@tanstack/pacer",
+  "version": "0.1.0",
+  "description": "Utilities for debouncing, throttling, rate-limiting, queuing, and more.",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TanStack/pacer.git",
+    "directory": "packages/pacer"
+  },
+  "homepage": "https://tanstack.com/pacer",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "keywords": [
+    "debounce",
+    "throttle",
+    "rate-limit",
+    "queuer",
+    "queue",
+    "pacer"
+  ],
+  "type": "module",
+  "types": "dist/esm/index.d.ts",
+  "main": "dist/cjs/index.cjs",
+  "module": "dist/esm/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.cts",
+        "default": "./dist/cjs/index.cjs"
+      }
+    },
+    "./async-debouncer": {
+      "import": {
+        "types": "./dist/esm/async-debouncer.d.ts",
+        "default": "./dist/esm/async-debouncer.js"
+      },
+      "require": {
+        "types": "./dist/cjs/async-debouncer.d.cts",
+        "default": "./dist/cjs/async-debouncer.cjs"
+      }
+    },
+    "./async-queuer": {
+      "import": {
+        "types": "./dist/esm/async-queuer.d.ts",
+        "default": "./dist/esm/async-queuer.js"
+      },
+      "require": {
+        "types": "./dist/cjs/async-queuer.d.cts",
+        "default": "./dist/cjs/async-queuer.cjs"
+      }
+    },
+    "./async-rate-limiter": {
+      "import": {
+        "types": "./dist/esm/async-rate-limiter.d.ts",
+        "default": "./dist/esm/async-rate-limiter.js"
+      },
+      "require": {
+        "types": "./dist/cjs/async-rate-limiter.d.cts",
+        "default": "./dist/cjs/async-rate-limiter.cjs"
+      }
+    },
+    "./async-throttler": {
+      "import": {
+        "types": "./dist/esm/async-throttler.d.ts",
+        "default": "./dist/esm/async-throttler.js"
+      },
+      "require": {
+        "types": "./dist/cjs/async-throttler.d.cts",
+        "default": "./dist/cjs/async-throttler.cjs"
+      }
+    },
+    "./compare": {
+      "import": {
+        "types": "./dist/esm/compare.d.ts",
+        "default": "./dist/esm/compare.js"
+      },
+      "require": {
+        "types": "./dist/cjs/compare.d.cts",
+        "default": "./dist/cjs/compare.cjs"
+      }
+    },
+    "./debouncer": {
+      "import": {
+        "types": "./dist/esm/debouncer.d.ts",
+        "default": "./dist/esm/debouncer.js"
+      },
+      "require": {
+        "types": "./dist/cjs/debouncer.d.cts",
+        "default": "./dist/cjs/debouncer.cjs"
+      }
+    },
+    "./queuer": {
+      "import": {
+        "types": "./dist/esm/queuer.d.ts",
+        "default": "./dist/esm/queuer.js"
+      },
+      "require": {
+        "types": "./dist/cjs/queuer.d.cts",
+        "default": "./dist/cjs/queuer.cjs"
+      }
+    },
+    "./rate-limiter": {
+      "import": {
+        "types": "./dist/esm/rate-limiter.d.ts",
+        "default": "./dist/esm/rate-limiter.js"
+      },
+      "require": {
+        "types": "./dist/cjs/rate-limiter.d.cts",
+        "default": "./dist/cjs/rate-limiter.cjs"
+      }
+    },
+    "./throttler": {
+      "import": {
+        "types": "./dist/esm/throttler.d.ts",
+        "default": "./dist/esm/throttler.js"
+      },
+      "require": {
+        "types": "./dist/cjs/throttler.d.cts",
+        "default": "./dist/cjs/throttler.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist/",
+    "src"
+  ],
+  "scripts": {
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc",
+    "test:build": "publint --strict",
+    "build": "vite build"
+  }
+}