@tanstack/pacer 0.1.0 → 0.2.0

package/dist/esm/throttler.js.map

@@ -1 +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;"}
+{"version":3,"file":"throttler.js","sources":["../../src/throttler.ts"],"sourcesContent":["import type { AnyFunction } from './types'\n\n/**\n * Options for configuring a throttled function\n */\nexport interface ThrottlerOptions<\n  TFn extends AnyFunction,\n  TArgs extends Parameters<TFn>,\n> {\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   * Callback function that is called after the function is executed\n   */\n  onExecute?: (throttler: Throttler<TFn, TArgs>) => void\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<any, any>> = {\n  enabled: true,\n  leading: true,\n  trailing: true,\n  wait: 0,\n  onExecute: () => {},\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 collapsing rapid-fire events where you only care about the last call, 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<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {\n  private _executionCount = 0\n  private _lastArgs: TArgs | undefined\n  private _lastExecutionTime = 0\n  private _options: Required<ThrottlerOptions<TFn, TArgs>>\n  private _timeoutId: NodeJS.Timeout | undefined\n  private _isPending = false\n\n  constructor(\n    private fn: TFn,\n    initialOptions: ThrottlerOptions<TFn, TArgs>,\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<TFn, TArgs>>,\n  ): Required<ThrottlerOptions<TFn, TArgs>> {\n    this._options = {\n      ...this._options,\n      ...newOptions,\n    }\n    return this._options\n  }\n\n  /**\n   * Returns the current throttler options\n   */\n  getOptions(): Required<ThrottlerOptions<TFn, TArgs>> {\n    return this._options\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      this._isPending = false\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._isPending = true\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._isPending = false\n          this._options.onExecute(this)\n        }, this._options.wait - timeSinceLastExecution)\n      }\n    }\n  }\n\n  private executeFunction(...args: TArgs): void {\n    if (!this._options.enabled) return\n    this.fn(...args) // EXECUTE!\n    this._executionCount++\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      this._isPending = false\n    }\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 `true` if there is a pending execution\n   */\n  getIsPending(): boolean {\n    return this._options.enabled && this._isPending\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/**\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<\n  TFn extends AnyFunction,\n  TArgs extends Parameters<TFn>,\n>(fn: TFn, initialOptions: Omit<ThrottlerOptions<TFn, TArgs>, 'enabled'>) {\n  const throttler = new Throttler(fn, initialOptions)\n  return throttler.maybeExecute.bind(throttler)\n}\n"],"names":[],"mappings":"AAkCA,MAAM,iBAAuD;AAAA,EAC3D,SAAS;AAAA,EACT,SAAS;AAAA,EACT,UAAU;AAAA,EACV,MAAM;AAAA,EACN,WAAW,MAAM;AAAA,EAAA;AACnB;AA6BO,MAAM,UAAkE;AAAA,EAQ7E,YACU,IACR,gBACA;AAFQ,SAAA,KAAA;AARV,SAAQ,kBAAkB;AAE1B,SAAQ,qBAAqB;AAG7B,SAAQ,aAAa;AAMnB,SAAK,WAAW;AAAA,MACd,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOF,WACE,YACwC;AACxC,SAAK,WAAW;AAAA,MACd,GAAG,KAAK;AAAA,MACR,GAAG;AAAA,IACL;AACA,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,aAAqD;AACnD,WAAO,KAAK;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,EAyBd,gBAAgB,MAAmB;AAC3B,UAAA,MAAM,KAAK,IAAI;AACf,UAAA,yBAAyB,MAAM,KAAK;AAGtC,QAAA,0BAA0B,KAAK,SAAS,MAAM;AAC5C,UAAA,KAAK,SAAS,SAAS;AACpB,aAAA,gBAAgB,GAAG,IAAI;AAAA,MAAA;AAE9B,WAAK,qBAAqB;AAC1B,WAAK,aAAa;AAAA,IAAA,OACb;AAEL,WAAK,YAAY;AAGjB,UAAI,CAAC,KAAK,cAAc,KAAK,SAAS,UAAU;AAC9C,aAAK,aAAa;AACb,aAAA,aAAa,WAAW,MAAM;AACjC,cAAI,KAAK,WAAW;AACb,iBAAA,gBAAgB,GAAG,KAAK,SAAS;AACtC,iBAAK,YAAY;AAAA,UAAA;AAEd,eAAA,qBAAqB,KAAK,IAAI;AACnC,eAAK,aAAa;AAClB,eAAK,aAAa;AACb,eAAA,SAAS,UAAU,IAAI;AAAA,QAC3B,GAAA,KAAK,SAAS,OAAO,sBAAsB;AAAA,MAAA;AAAA,IAChD;AAAA,EACF;AAAA,EAGM,mBAAmB,MAAmB;AACxC,QAAA,CAAC,KAAK,SAAS,QAAS;AACvB,SAAA,GAAG,GAAG,IAAI;AACV,SAAA;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYP,SAAe;AACb,QAAI,KAAK,YAAY;AACnB,mBAAa,KAAK,UAAU;AAC5B,WAAK,aAAa;AAClB,WAAK,YAAY;AACjB,WAAK,aAAa;AAAA,IAAA;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA,EAMF,oBAA4B;AAC1B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,eAAwB;AACf,WAAA,KAAK,SAAS,WAAW,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMvC,uBAA+B;AAC7B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,uBAA+B;AACtB,WAAA,KAAK,qBAAqB,KAAK,SAAS;AAAA,EAAA;AAEnD;AA4BgB,SAAA,SAGd,IAAS,gBAA+D;AACxE,QAAM,YAAY,IAAI,UAAU,IAAI,cAAc;AAC3C,SAAA,UAAU,aAAa,KAAK,SAAS;AAC9C;"}

package/dist/esm/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Represents a function that can be called with any arguments and returns any value.
+ * @template TArgs - The type of the arguments the function can be called with.
+ * @returns The return value of the function.
+ */
+export type AnyFunction<TArgs extends Array<any> = Array<any>> = (...args: TArgs) => any;
+/**
+ * Represents an asynchronous function that can be called with any arguments and returns a promise.
+ * @template TArgs - The type of the arguments the function can be called with.
+ * @returns A promise that resolves to the return value of the function.
+ */
+export type AnyAsyncFunction<TArgs extends Array<any> = Array<any>> = (...args: TArgs) => Promise<any>;

package/dist/esm/utils.d.ts

@@ -0,0 +1 @@
+export declare function bindInstanceMethods<T extends Record<string, any>>(instance: T): any;

package/dist/esm/utils.js

@@ -0,0 +1,13 @@
+function bindInstanceMethods(instance) {
+  return Object.getOwnPropertyNames(Object.getPrototypeOf(instance)).filter((key) => typeof instance[key] === "function").reduce((acc, key) => {
+    const method = instance[key];
+    if (typeof method === "function") {
+      acc[key] = method.bind(instance);
+    }
+    return acc;
+  }, {});
+}
+export {
+  bindInstanceMethods
+};
+//# sourceMappingURL=utils.js.map

package/dist/esm/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sources":["../../src/utils.ts"],"sourcesContent":["export function bindInstanceMethods<T extends Record<string, any>>(\n  instance: T,\n) {\n  return Object.getOwnPropertyNames(Object.getPrototypeOf(instance))\n    .filter((key) => typeof instance[key as keyof T] === 'function')\n    .reduce((acc: any, key) => {\n      const method = instance[key as keyof T]\n      if (typeof method === 'function') {\n        acc[key] = method.bind(instance)\n      }\n      return acc\n    }, {} as T)\n}\n"],"names":[],"mappings":"AAAO,SAAS,oBACd,UACA;AACA,SAAO,OAAO,oBAAoB,OAAO,eAAe,QAAQ,CAAC,EAC9D,OAAO,CAAC,QAAQ,OAAO,SAAS,GAAc,MAAM,UAAU,EAC9D,OAAO,CAAC,KAAU,QAAQ;AACnB,UAAA,SAAS,SAAS,GAAc;AAClC,QAAA,OAAO,WAAW,YAAY;AAChC,UAAI,GAAG,IAAI,OAAO,KAAK,QAAQ;AAAA,IAAA;AAE1B,WAAA;AAAA,EACT,GAAG,EAAO;AACd;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/pacer",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Utilities for debouncing, throttling, rate-limiting, queuing, and more.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -127,6 +127,13 @@
         "default": "./dist/cjs/throttler.cjs"
       }
     },
+    "./types": {
+      "types": "./dist/esm/types.d.ts"
+    },
+    "./utils": {
+      "types": "./dist/esm/utils.d.ts",
+      "default": "./dist/esm/utils.js"
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,

package/src/async-debouncer.ts

@@ -1,7 +1,12 @@
+import type { AnyAsyncFunction } from './types'
+
 /**
  * Options for configuring an async debounced function
  */
-export interface AsyncDebouncerOptions {
+export interface AsyncDebouncerOptions<
+  TFn extends AnyAsyncFunction,
+  TArgs extends Parameters<TFn>,
+> {
   /**
    * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
@@ -12,6 +17,14 @@ export interface AsyncDebouncerOptions {
    * Defaults to false.
    */
   leading?: boolean
+  /**
+   * Optional error handler for when the debounced function throws
+   */
+  onError?: (error: unknown) => void
+  /**
+   * Optional function to call when the debounced function is executed
+   */
+  onExecute?: (debouncer: AsyncDebouncer<TFn, TArgs>) => void
   /**
    * Whether to execute on the trailing edge of the timeout.
    * Defaults to true.
@@ -22,17 +35,14 @@ export interface AsyncDebouncerOptions {
    * Defaults to 0ms
    */
   wait: number
-  /**
-   * Optional error handler for when the debounced function throws
-   */
-  onError?: (error: unknown) => void
 }
 
-const defaultOptions: Required<AsyncDebouncerOptions> = {
+const defaultOptions: Required<AsyncDebouncerOptions<any, any>> = {
   enabled: true,
   leading: false,
   trailing: true,
   onError: () => {},
+  onExecute: () => {},
   wait: 0,
 }
 
@@ -48,33 +58,33 @@ const defaultOptions: Required<AsyncDebouncerOptions> = {
  *
  * @example
  * ```ts
- * const debouncer = new AsyncDebouncer(async (value: string) => {
+ * const asyncDebouncer = new AsyncDebouncer(async (value: string) => {
  *   await searchAPI(value);
  * }, { wait: 500 });
  *
  * // Called on each keystroke but only executes after 500ms of no typing
  * inputElement.addEventListener('input', () => {
- *   debouncer.maybeExecute(inputElement.value);
+ *   asyncDebouncer.maybeExecute(inputElement.value);
  * });
  * ```
  */
 export class AsyncDebouncer<
-  TFn extends (...args: Array<any>) => Promise<any>,
+  TFn extends AnyAsyncFunction,
   TArgs extends Parameters<TFn>,
 > {
-  private abortController: AbortController | null = null
-  private executionCount = 0
-  private isExecuting = false
-  private lastArgs: TArgs | undefined
-  private options: Required<AsyncDebouncerOptions>
-  private timeoutId: ReturnType<typeof setTimeout> | null = null
-  private canLeadingExecute = true
+  private _abortController: AbortController | null = null
+  private _executionCount = 0
+  private _isExecuting = false
+  private _lastArgs: TArgs | undefined
+  private _options: Required<AsyncDebouncerOptions<TFn, TArgs>>
+  private _timeoutId: ReturnType<typeof setTimeout> | null = null
+  private _canLeadingExecute = true
 
   constructor(
     private fn: TFn,
-    initialOptions: AsyncDebouncerOptions,
+    initialOptions: AsyncDebouncerOptions<TFn, TArgs>,
   ) {
-    this.options = {
+    this._options = {
       ...defaultOptions,
       ...initialOptions,
     }
@@ -85,36 +95,20 @@ export class AsyncDebouncer<
    * Returns the new options state
    */
   setOptions(
-    newOptions: Partial<AsyncDebouncerOptions>,
-  ): Required<AsyncDebouncerOptions> {
-    this.options = {
-      ...this.options,
+    newOptions: Partial<AsyncDebouncerOptions<TFn, TArgs>>,
+  ): Required<AsyncDebouncerOptions<TFn, TArgs>> {
+    this._options = {
+      ...this._options,
       ...newOptions,
     }
-    return this.options
-  }
-
-  /**
-   * Returns the number of times the function has been executed
-   */
-  getExecutionCount(): number {
-    return this.executionCount
+    return this._options
   }
 
   /**
-   * Cancels any pending execution
+   * Returns the current debouncer options
    */
-  cancel(): void {
-    if (this.timeoutId) {
-      clearTimeout(this.timeoutId)
-      this.timeoutId = null
-    }
-    if (this.abortController) {
-      this.abortController.abort()
-      this.abortController = null
-    }
-    this.lastArgs = undefined
-    this.canLeadingExecute = true
+  getOptions(): Required<AsyncDebouncerOptions<TFn, TArgs>> {
+    return this._options
   }
 
   /**
@@ -123,52 +117,85 @@ export class AsyncDebouncer<
    */
   async maybeExecute(...args: TArgs): Promise<void> {
     this.cancel()
-    this.lastArgs = args
+    this._lastArgs = args
 
     // Handle leading execution
-    if (this.options.leading && this.canLeadingExecute) {
-      this.canLeadingExecute = false
+    if (this._options.leading && this._canLeadingExecute) {
+      this._canLeadingExecute = false
       await this.executeFunction(...args)
     }
 
     return new Promise((resolve) => {
-      this.timeoutId = setTimeout(async () => {
-        if (this.isExecuting) {
+      this._timeoutId = setTimeout(async () => {
+        if (this._isExecuting) {
           resolve()
           return
         }
 
-        this.canLeadingExecute = true
+        this._canLeadingExecute = true
         // Execute trailing only if enabled
-        if (this.options.trailing) {
-          this.abortController = new AbortController()
+        if (this._options.trailing) {
+          this._abortController = new AbortController()
           try {
-            this.isExecuting = true
-            if (this.lastArgs) {
-              await this.executeFunction(...this.lastArgs)
+            this._isExecuting = true
+            if (this._lastArgs) {
+              await this.executeFunction(...this._lastArgs)
             }
           } catch (error) {
             try {
-              this.options.onError(error)
+              this._options.onError(error)
             } catch {
-              // Ignore errors from error handler
+              console.error('Error in error handler', error)
             }
           } finally {
-            this.isExecuting = false
-            this.abortController = null
+            this._isExecuting = false
+            this._abortController = null
             resolve()
           }
         } else {
           resolve()
         }
-      }, this.options.wait)
+      }, this._options.wait)
     })
   }
 
   private async executeFunction(...args: TArgs): Promise<void> {
-    if (!this.options.enabled) return
-    this.executionCount++
+    if (!this._options.enabled) return
+    this._executionCount++
     await this.fn(...args)
+    this._options.onExecute(this)
+  }
+
+  /**
+   * Cancels any pending execution
+   */
+  cancel(): void {
+    if (this._timeoutId) {
+      clearTimeout(this._timeoutId)
+      this._timeoutId = null
+    }
+    if (this._abortController) {
+      this._abortController.abort()
+      this._abortController = null
+    }
+    this._lastArgs = undefined
+    this._canLeadingExecute = true
+  }
+
+  /**
+   * Returns the number of times the function has been executed
+   */
+  getExecutionCount(): number {
+    return this._executionCount
+  }
+
+  /**
+   * Returns `true` if there is a pending execution
+   */
+  getIsPending(): boolean {
+    return (
+      this._options.enabled && (this._timeoutId !== null || this._isExecuting)
+    )
   }
 }
 
@@ -190,8 +217,9 @@ export class AsyncDebouncer<
  * ```
  */
 export function asyncDebounce<
-  TFn extends (...args: Array<any>) => Promise<any>,
->(fn: TFn, initialOptions: Omit<AsyncDebouncerOptions, 'enabled'>) {
+  TFn extends AnyAsyncFunction,
+  TArgs extends Parameters<TFn>,
+>(fn: TFn, initialOptions: Omit<AsyncDebouncerOptions<TFn, TArgs>, 'enabled'>) {
   const asyncDebouncer = new AsyncDebouncer(fn, initialOptions)
   return asyncDebouncer.maybeExecute.bind(asyncDebouncer)
 }