@tanstack/pacer 0.6.0 → 0.7.0

package/dist/cjs/async-debouncer.cjs

@@ -18,6 +18,7 @@ class AsyncDebouncer {
     this._settleCount = 0;
     this._successCount = 0;
     this._timeoutId = null;
+    this._resolvePreviousPromise = null;
     this._options = {
       ...defaultOptions,
       ...initialOptions,
@@ -26,7 +27,6 @@ class AsyncDebouncer {
   }
   /**
    * Updates the debouncer options
-   * Returns the new options state
    */
   setOptions(newOptions) {
     this._options = { ...this._options, ...newOptions };
@@ -71,23 +71,25 @@ class AsyncDebouncer {
     this._lastArgs = args;
     if (this._options.leading && this._canLeadingExecute) {
       this._canLeadingExecute = false;
-      await this.executeFunction(...args);
+      await this.execute(...args);
       return this._lastResult;
     }
     if (this._options.trailing) {
       this._isPending = true;
     }
     return new Promise((resolve) => {
+      this._resolvePreviousPromise = resolve;
       this._timeoutId = setTimeout(async () => {
         if (this._options.trailing && this._lastArgs) {
-          await this.executeFunction(...this._lastArgs);
+          await this.execute(...this._lastArgs);
         }
         this._canLeadingExecute = true;
+        this._resolvePreviousPromise = null;
         resolve(this._lastResult);
       }, this.getWait());
     });
   }
-  async executeFunction(...args) {
+  async execute(...args) {
     var _a, _b, _c, _d, _e, _f;
     if (!this.getEnabled()) return void 0;
     this._abortController = new AbortController();
@@ -101,8 +103,6 @@ class AsyncDebouncer {
       (_d = (_c = this._options).onError) == null ? void 0 : _d.call(_c, error, this);
       if (this._options.throwOnError) {
         throw error;
-      } else {
-        console.error(error);
       }
     } finally {
       this._isExecuting = false;
@@ -125,6 +125,10 @@ class AsyncDebouncer {
       this._abortController.abort();
       this._abortController = null;
     }
+    if (this._resolvePreviousPromise) {
+      this._resolvePreviousPromise(this._lastResult);
+      this._resolvePreviousPromise = null;
+    }
     this._lastArgs = void 0;
     this._isPending = false;
     this._isExecuting = false;

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

@@ -1 +1 @@
-{"version":3,"file":"async-debouncer.cjs","sources":["../../src/async-debouncer.ts"],"sourcesContent":["import { parseFunctionOrValue } from './utils'\nimport type { AnyAsyncFunction, OptionalKeys } from './types'\n\n/**\n * Options for configuring an async debounced function\n */\nexport interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {\n  /**\n   * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.\n   * Can be a boolean or a function that returns a boolean.\n   * Defaults to true.\n   */\n  enabled?: boolean | ((debouncer: AsyncDebouncer<TFn>) => boolean)\n  /**\n   * Whether to execute on the leading edge of the timeout.\n   * Defaults to false.\n   */\n  leading?: boolean\n  /**\n   * Optional error handler for when the debounced function throws.\n   * If provided, the handler will be called with the error and debouncer instance.\n   * This can be used alongside throwOnError - the handler will be called before any error is thrown.\n   */\n  onError?: (error: unknown, debouncer: AsyncDebouncer<TFn>) => void\n  /**\n   * Optional callback to call when the debounced function is executed\n   */\n  onSettled?: (debouncer: AsyncDebouncer<TFn>) => void\n  /**\n   * Optional callback to call when the debounced function is executed\n   */\n  onSuccess?: (result: ReturnType<TFn>, debouncer: AsyncDebouncer<TFn>) => void\n  /**\n   * Whether to throw errors when they occur.\n   * Defaults to true if no onError handler is provided, false if an onError handler is provided.\n   * Can be explicitly set to override these defaults.\n   */\n  throwOnError?: boolean\n  /**\n   * Whether to execute on the trailing edge of the timeout.\n   * Defaults to true.\n   */\n  trailing?: boolean\n  /**\n   * Delay in milliseconds to wait after the last call before executing.\n   * Can be a number or a function that returns a number.\n   * Defaults to 0ms\n   */\n  wait: number | ((debouncer: AsyncDebouncer<TFn>) => number)\n}\n\ntype AsyncDebouncerOptionsWithOptionalCallbacks = OptionalKeys<\n  AsyncDebouncerOptions<any>,\n  'onError' | 'onSettled' | 'onSuccess'\n>\n\nconst defaultOptions: AsyncDebouncerOptionsWithOptionalCallbacks = {\n  enabled: true,\n  leading: false,\n  trailing: true,\n  wait: 0,\n}\n\n/**\n * A class that creates an async debounced function.\n *\n * Debouncing ensures that a function is only executed after a specified delay has passed since its last invocation.\n * Each new invocation resets the delay timer. This is useful for handling frequent events like window resizing\n * or input changes where you only want to execute the handler after the events have stopped occurring.\n *\n * Unlike throttling which allows execution at regular intervals, debouncing prevents any execution until\n * the function stops being called for the specified delay period.\n *\n * Unlike the non-async Debouncer, this async version supports returning values from the debounced function,\n * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call\n * instead of setting the result on a state variable from within the debounced function.\n *\n * Error Handling:\n * - If an error occurs during execution and no `onError` handler is provided, the error will be thrown and propagate up to the caller.\n * - If an `onError` handler is provided, errors will be caught and passed to the handler instead of being thrown.\n * - The error count can be tracked using `getErrorCount()`.\n * - The debouncer maintains its state and can continue to be used after an error occurs.\n *\n * @example\n * ```ts\n * const asyncDebouncer = new AsyncDebouncer(async (value: string) => {\n *   const results = await searchAPI(value);\n *   return results; // Return value is preserved\n * }, {\n *   wait: 500,\n *   onError: (error) => {\n *     console.error('Search failed:', error);\n *   }\n * });\n *\n * // Called on each keystroke but only executes after 500ms of no typing\n * // Returns the API response directly\n * const results = await asyncDebouncer.maybeExecute(inputElement.value);\n * ```\n */\nexport class AsyncDebouncer<TFn extends AnyAsyncFunction> {\n  private _options: AsyncDebouncerOptionsWithOptionalCallbacks\n  private _abortController: AbortController | null = null\n  private _canLeadingExecute = true\n  private _errorCount = 0\n  private _isExecuting = false\n  private _isPending = false\n  private _lastArgs: Parameters<TFn> | undefined\n  private _lastResult: ReturnType<TFn> | undefined\n  private _settleCount = 0\n  private _successCount = 0\n  private _timeoutId: NodeJS.Timeout | null = null\n\n  constructor(\n    private fn: TFn,\n    initialOptions: AsyncDebouncerOptions<TFn>,\n  ) {\n    this._options = {\n      ...defaultOptions,\n      ...initialOptions,\n      throwOnError: initialOptions.throwOnError ?? !initialOptions.onError,\n    }\n  }\n\n  /**\n   * Updates the debouncer options\n   * Returns the new options state\n   */\n  setOptions(newOptions: Partial<AsyncDebouncerOptions<TFn>>): void {\n    this._options = { ...this._options, ...newOptions }\n\n    // End the pending state if the debouncer is disabled\n    if (!this._options.enabled) {\n      this._isPending = false\n    }\n  }\n\n  /**\n   * Returns the current debouncer options\n   */\n  getOptions(): AsyncDebouncerOptions<TFn> {\n    return this._options\n  }\n\n  /**\n   * Returns the current debouncer enabled state\n   */\n  getEnabled(): boolean {\n    return !!parseFunctionOrValue(this._options.enabled, this)\n  }\n\n  /**\n   * Returns the current debouncer wait state\n   */\n  getWait(): number {\n    return parseFunctionOrValue(this._options.wait, this)\n  }\n\n  /**\n   * Attempts to execute the debounced function.\n   * If a call is already in progress, it will be queued.\n   *\n   * Error Handling:\n   * - If the debounced function throws and no `onError` handler is configured,\n   *   the error will be thrown from this method.\n   * - If an `onError` handler is configured, errors will be caught and passed to the handler,\n   *   and this method will return undefined.\n   * - The error state can be checked using `getErrorCount()` and `getIsExecuting()`.\n   *\n   * @returns A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError\n   * @throws The error from the debounced function if no onError handler is configured\n   */\n  async maybeExecute(\n    ...args: Parameters<TFn>\n  ): Promise<ReturnType<TFn> | undefined> {\n    this._cancel()\n    this._lastArgs = args\n\n    // Handle leading execution\n    if (this._options.leading && this._canLeadingExecute) {\n      this._canLeadingExecute = false\n      await this.executeFunction(...args)\n      return this._lastResult\n    }\n\n    // Handle trailing execution\n    if (this._options.trailing) {\n      this._isPending = true\n    }\n\n    return new Promise((resolve) => {\n      this._timeoutId = setTimeout(async () => {\n        // Execute trailing if enabled\n        if (this._options.trailing && this._lastArgs) {\n          await this.executeFunction(...this._lastArgs)\n        }\n\n        // Reset state and resolve\n        this._canLeadingExecute = true\n        resolve(this._lastResult)\n      }, this.getWait())\n    })\n  }\n\n  private async executeFunction(\n    ...args: Parameters<TFn>\n  ): Promise<ReturnType<TFn> | undefined> {\n    if (!this.getEnabled()) return undefined\n    this._abortController = new AbortController()\n    try {\n      this._isExecuting = true\n      this._lastResult = await this.fn(...args) // EXECUTE!\n      this._successCount++\n      this._options.onSuccess?.(this._lastResult!, this)\n    } catch (error) {\n      this._errorCount++\n      this._options.onError?.(error, this)\n      if (this._options.throwOnError) {\n        throw error\n      } else {\n        console.error(error)\n      }\n    } finally {\n      this._isExecuting = false\n      this._isPending = false\n      this._settleCount++\n      this._abortController = null\n      this._options.onSettled?.(this)\n    }\n    return this._lastResult\n  }\n\n  /**\n   * Cancel without resetting _canLeadingExecute\n   */\n  private _cancel(): void {\n    if (this._timeoutId) {\n      clearTimeout(this._timeoutId)\n      this._timeoutId = null\n    }\n    if (this._abortController) {\n      this._abortController.abort()\n      this._abortController = null\n    }\n    this._lastArgs = undefined\n    this._isPending = false\n    this._isExecuting = false\n  }\n\n  /**\n   * Cancels any pending execution or aborts any execution in progress\n   */\n  cancel(): void {\n    this._canLeadingExecute = true\n    this._cancel()\n  }\n\n  /**\n   * Returns the last result of the debounced function\n   */\n  getLastResult(): ReturnType<TFn> | undefined {\n    return this._lastResult\n  }\n\n  /**\n   * Returns the number of times the function has been executed successfully\n   */\n  getSuccessCount(): number {\n    return this._successCount\n  }\n\n  /**\n   * Returns the number of times the function has settled (completed or errored)\n   */\n  getSettleCount(): number {\n    return this._settleCount\n  }\n\n  /**\n   * Returns the number of times the function has errored\n   */\n  getErrorCount(): number {\n    return this._errorCount\n  }\n\n  /**\n   * Returns `true` if there is a pending execution queued up for trailing execution\n   */\n  getIsPending(): boolean {\n    return this.getEnabled() && this._isPending\n  }\n\n  /**\n   * Returns `true` if there is currently an execution in progress\n   */\n  getIsExecuting(): boolean {\n    return this._isExecuting\n  }\n}\n\n/**\n * Creates an async debounced function that delays execution until after a specified wait time.\n * The debounced function will only execute once the wait period has elapsed without any new calls.\n * If called again during the wait period, the timer resets and a new wait period begins.\n *\n * Unlike the non-async Debouncer, this async version supports returning values from the debounced function,\n * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call\n * instead of setting the result on a state variable from within the debounced function.\n *\n * Error Handling:\n * - If an `onError` handler is provided, it will be called with the error and debouncer instance\n * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown\n * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed\n * - The error state can be checked using the underlying AsyncDebouncer instance\n * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown\n *\n * @example\n * ```ts\n * const debounced = asyncDebounce(async (value: string) => {\n *   const result = await saveToAPI(value);\n *   return result; // Return value is preserved\n * }, {\n *   wait: 1000,\n *   onError: (error) => {\n *     console.error('API call failed:', error);\n *   },\n *   throwOnError: true // Will both log the error and throw it\n * });\n *\n * // Will only execute once, 1 second after the last call\n * // Returns the API response directly\n * const result = await debounced(\"third\");\n * ```\n */\nexport function asyncDebounce<TFn extends AnyAsyncFunction>(\n  fn: TFn,\n  initialOptions: AsyncDebouncerOptions<TFn>,\n) {\n  const asyncDebouncer = new AsyncDebouncer(fn, initialOptions)\n  return asyncDebouncer.maybeExecute.bind(asyncDebouncer)\n}\n"],"names":["parseFunctionOrValue"],"mappings":"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"}
+{"version":3,"file":"async-debouncer.cjs","sources":["../../src/async-debouncer.ts"],"sourcesContent":["import { parseFunctionOrValue } from './utils'\nimport type { AnyAsyncFunction, OptionalKeys } from './types'\n\n/**\n * Options for configuring an async debounced function\n */\nexport interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {\n  /**\n   * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.\n   * Can be a boolean or a function that returns a boolean.\n   * Defaults to true.\n   */\n  enabled?: boolean | ((debouncer: AsyncDebouncer<TFn>) => boolean)\n  /**\n   * Whether to execute on the leading edge of the timeout.\n   * Defaults to false.\n   */\n  leading?: boolean\n  /**\n   * Optional error handler for when the debounced function throws.\n   * If provided, the handler will be called with the error and debouncer instance.\n   * This can be used alongside throwOnError - the handler will be called before any error is thrown.\n   */\n  onError?: (error: unknown, debouncer: AsyncDebouncer<TFn>) => void\n  /**\n   * Optional callback to call when the debounced function is executed\n   */\n  onSettled?: (debouncer: AsyncDebouncer<TFn>) => void\n  /**\n   * Optional callback to call when the debounced function is executed\n   */\n  onSuccess?: (result: ReturnType<TFn>, debouncer: AsyncDebouncer<TFn>) => void\n  /**\n   * Whether to throw errors when they occur.\n   * Defaults to true if no onError handler is provided, false if an onError handler is provided.\n   * Can be explicitly set to override these defaults.\n   */\n  throwOnError?: boolean\n  /**\n   * Whether to execute on the trailing edge of the timeout.\n   * Defaults to true.\n   */\n  trailing?: boolean\n  /**\n   * Delay in milliseconds to wait after the last call before executing.\n   * Can be a number or a function that returns a number.\n   * Defaults to 0ms\n   */\n  wait: number | ((debouncer: AsyncDebouncer<TFn>) => number)\n}\n\ntype AsyncDebouncerOptionsWithOptionalCallbacks = OptionalKeys<\n  AsyncDebouncerOptions<any>,\n  'onError' | 'onSettled' | 'onSuccess'\n>\n\nconst defaultOptions: AsyncDebouncerOptionsWithOptionalCallbacks = {\n  enabled: true,\n  leading: false,\n  trailing: true,\n  wait: 0,\n}\n\n/**\n * A class that creates an async debounced function.\n *\n * Debouncing ensures that a function is only executed after a specified delay has passed since its last invocation.\n * Each new invocation resets the delay timer. This is useful for handling frequent events like window resizing\n * or input changes where you only want to execute the handler after the events have stopped occurring.\n *\n * Unlike throttling which allows execution at regular intervals, debouncing prevents any execution until\n * the function stops being called for the specified delay period.\n *\n * Unlike the non-async Debouncer, this async version supports returning values from the debounced function,\n * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call\n * instead of setting the result on a state variable from within the debounced function.\n *\n * Error Handling:\n * - If an error occurs during execution and no `onError` handler is provided, the error will be thrown and propagate up to the caller.\n * - If an `onError` handler is provided, errors will be caught and passed to the handler instead of being thrown.\n * - The error count can be tracked using `getErrorCount()`.\n * - The debouncer maintains its state and can continue to be used after an error occurs.\n *\n * @example\n * ```ts\n * const asyncDebouncer = new AsyncDebouncer(async (value: string) => {\n *   const results = await searchAPI(value);\n *   return results; // Return value is preserved\n * }, {\n *   wait: 500,\n *   onError: (error) => {\n *     console.error('Search failed:', error);\n *   }\n * });\n *\n * // Called on each keystroke but only executes after 500ms of no typing\n * // Returns the API response directly\n * const results = await asyncDebouncer.maybeExecute(inputElement.value);\n * ```\n */\nexport class AsyncDebouncer<TFn extends AnyAsyncFunction> {\n  private _options: AsyncDebouncerOptionsWithOptionalCallbacks\n  private _abortController: AbortController | null = null\n  private _canLeadingExecute = true\n  private _errorCount = 0\n  private _isExecuting = false\n  private _isPending = false\n  private _lastArgs: Parameters<TFn> | undefined\n  private _lastResult: ReturnType<TFn> | undefined\n  private _settleCount = 0\n  private _successCount = 0\n  private _timeoutId: NodeJS.Timeout | null = null\n  private _resolvePreviousPromise:\n    | ((value?: ReturnType<TFn> | undefined) => void)\n    | null = null\n\n  constructor(\n    private fn: TFn,\n    initialOptions: AsyncDebouncerOptions<TFn>,\n  ) {\n    this._options = {\n      ...defaultOptions,\n      ...initialOptions,\n      throwOnError: initialOptions.throwOnError ?? !initialOptions.onError,\n    }\n  }\n\n  /**\n   * Updates the debouncer options\n   */\n  setOptions(newOptions: Partial<AsyncDebouncerOptions<TFn>>): void {\n    this._options = { ...this._options, ...newOptions }\n\n    // End the pending state if the debouncer is disabled\n    if (!this._options.enabled) {\n      this._isPending = false\n    }\n  }\n\n  /**\n   * Returns the current debouncer options\n   */\n  getOptions(): AsyncDebouncerOptions<TFn> {\n    return this._options\n  }\n\n  /**\n   * Returns the current debouncer enabled state\n   */\n  getEnabled(): boolean {\n    return !!parseFunctionOrValue(this._options.enabled, this)\n  }\n\n  /**\n   * Returns the current debouncer wait state\n   */\n  getWait(): number {\n    return parseFunctionOrValue(this._options.wait, this)\n  }\n\n  /**\n   * Attempts to execute the debounced function.\n   * If a call is already in progress, it will be queued.\n   *\n   * Error Handling:\n   * - If the debounced function throws and no `onError` handler is configured,\n   *   the error will be thrown from this method.\n   * - If an `onError` handler is configured, errors will be caught and passed to the handler,\n   *   and this method will return undefined.\n   * - The error state can be checked using `getErrorCount()` and `getIsExecuting()`.\n   *\n   * @returns A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError\n   * @throws The error from the debounced function if no onError handler is configured\n   */\n  async maybeExecute(\n    ...args: Parameters<TFn>\n  ): Promise<ReturnType<TFn> | undefined> {\n    this._cancel()\n    this._lastArgs = args\n\n    // Handle leading execution\n    if (this._options.leading && this._canLeadingExecute) {\n      this._canLeadingExecute = false\n      await this.execute(...args)\n      return this._lastResult\n    }\n\n    // Handle trailing execution\n    if (this._options.trailing) {\n      this._isPending = true\n    }\n\n    return new Promise((resolve) => {\n      this._resolvePreviousPromise = resolve\n      this._timeoutId = setTimeout(async () => {\n        // Execute trailing if enabled\n        if (this._options.trailing && this._lastArgs) {\n          await this.execute(...this._lastArgs)\n        }\n\n        // Reset state and resolve\n        this._canLeadingExecute = true\n        this._resolvePreviousPromise = null\n        resolve(this._lastResult)\n      }, this.getWait())\n    })\n  }\n\n  private async execute(\n    ...args: Parameters<TFn>\n  ): Promise<ReturnType<TFn> | undefined> {\n    if (!this.getEnabled()) return undefined\n    this._abortController = new AbortController()\n    try {\n      this._isExecuting = true\n      this._lastResult = await this.fn(...args) // EXECUTE!\n      this._successCount++\n      this._options.onSuccess?.(this._lastResult!, this)\n    } catch (error) {\n      this._errorCount++\n      this._options.onError?.(error, this)\n      if (this._options.throwOnError) {\n        throw error\n      }\n    } finally {\n      this._isExecuting = false\n      this._isPending = false\n      this._settleCount++\n      this._abortController = null\n      this._options.onSettled?.(this)\n    }\n    return this._lastResult\n  }\n\n  /**\n   * Cancel without resetting _canLeadingExecute\n   */\n  private _cancel(): void {\n    if (this._timeoutId) {\n      clearTimeout(this._timeoutId)\n      this._timeoutId = null\n    }\n    if (this._abortController) {\n      this._abortController.abort()\n      this._abortController = null\n    }\n    if (this._resolvePreviousPromise) {\n      this._resolvePreviousPromise(this._lastResult)\n      this._resolvePreviousPromise = null\n    }\n    this._lastArgs = undefined\n    this._isPending = false\n    this._isExecuting = false\n  }\n\n  /**\n   * Cancels any pending execution or aborts any execution in progress\n   */\n  cancel(): void {\n    this._canLeadingExecute = true\n    this._cancel()\n  }\n\n  /**\n   * Returns the last result of the debounced function\n   */\n  getLastResult(): ReturnType<TFn> | undefined {\n    return this._lastResult\n  }\n\n  /**\n   * Returns the number of times the function has been executed successfully\n   */\n  getSuccessCount(): number {\n    return this._successCount\n  }\n\n  /**\n   * Returns the number of times the function has settled (completed or errored)\n   */\n  getSettleCount(): number {\n    return this._settleCount\n  }\n\n  /**\n   * Returns the number of times the function has errored\n   */\n  getErrorCount(): number {\n    return this._errorCount\n  }\n\n  /**\n   * Returns `true` if there is a pending execution queued up for trailing execution\n   */\n  getIsPending(): boolean {\n    return this.getEnabled() && this._isPending\n  }\n\n  /**\n   * Returns `true` if there is currently an execution in progress\n   */\n  getIsExecuting(): boolean {\n    return this._isExecuting\n  }\n}\n\n/**\n * Creates an async debounced function that delays execution until after a specified wait time.\n * The debounced function will only execute once the wait period has elapsed without any new calls.\n * If called again during the wait period, the timer resets and a new wait period begins.\n *\n * Unlike the non-async Debouncer, this async version supports returning values from the debounced function,\n * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call\n * instead of setting the result on a state variable from within the debounced function.\n *\n * Error Handling:\n * - If an `onError` handler is provided, it will be called with the error and debouncer instance\n * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown\n * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed\n * - The error state can be checked using the underlying AsyncDebouncer instance\n * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown\n *\n * @example\n * ```ts\n * const debounced = asyncDebounce(async (value: string) => {\n *   const result = await saveToAPI(value);\n *   return result; // Return value is preserved\n * }, {\n *   wait: 1000,\n *   onError: (error) => {\n *     console.error('API call failed:', error);\n *   },\n *   throwOnError: true // Will both log the error and throw it\n * });\n *\n * // Will only execute once, 1 second after the last call\n * // Returns the API response directly\n * const result = await debounced(\"third\");\n * ```\n */\nexport function asyncDebounce<TFn extends AnyAsyncFunction>(\n  fn: TFn,\n  initialOptions: AsyncDebouncerOptions<TFn>,\n) {\n  const asyncDebouncer = new AsyncDebouncer(fn, initialOptions)\n  return asyncDebouncer.maybeExecute.bind(asyncDebouncer)\n}\n"],"names":["parseFunctionOrValue"],"mappings":"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"}

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

@@ -96,10 +96,10 @@ export declare class AsyncDebouncer<TFn extends AnyAsyncFunction> {
     private _settleCount;
     private _successCount;
     private _timeoutId;
+    private _resolvePreviousPromise;
     constructor(fn: TFn, initialOptions: AsyncDebouncerOptions<TFn>);
     /**
      * Updates the debouncer options
-     * Returns the new options state
      */
     setOptions(newOptions: Partial<AsyncDebouncerOptions<TFn>>): void;
     /**
@@ -129,7 +129,7 @@ export declare class AsyncDebouncer<TFn extends AnyAsyncFunction> {
      * @throws The error from the debounced function if no onError handler is configured
      */
     maybeExecute(...args: Parameters<TFn>): Promise<ReturnType<TFn> | undefined>;
-    private executeFunction;
+    private execute;
     /**
      * Cancel without resetting _canLeadingExecute
      */

package/dist/cjs/async-queuer.cjs

@@ -14,7 +14,8 @@ const defaultOptions = {
   wait: 0
 };
 class AsyncQueuer {
-  constructor(initialOptions = defaultOptions) {
+  constructor(fn, initialOptions) {
+    this.fn = fn;
     this._activeItems = /* @__PURE__ */ new Set();
     this._successCount = 0;
     this._errorCount = 0;
@@ -37,32 +38,33 @@ class AsyncQueuer {
     }
   }
   /**
-   * Updates the queuer options
-   * Returns the new options state
+   * Updates the queuer options. New options are merged with existing options.
    */
   setOptions(newOptions) {
     this._options = { ...this._options, ...newOptions };
   }
   /**
-   * Returns the current queuer options
+   * Returns the current queuer options, including defaults and any overrides.
    */
   getOptions() {
     return this._options;
   }
   /**
-   * Returns the current wait time between processing items
+   * Returns the current wait time (in milliseconds) between processing items.
+   * If a function is provided, it is called with the queuer instance.
    */
   getWait() {
     return utils.parseFunctionOrValue(this._options.wait, this);
   }
   /**
-   * Returns the current concurrency limit
+   * Returns the current concurrency limit for processing items.
+   * If a function is provided, it is called with the queuer instance.
    */
   getConcurrency() {
     return utils.parseFunctionOrValue(this._options.concurrency, this);
   }
   /**
-   * Processes items in the queuer
+   * Processes items in the queue up to the concurrency limit. Internal use only.
    */
   tick() {
     var _a, _b;
@@ -72,33 +74,14 @@ class AsyncQueuer {
     }
     this.checkExpiredItems();
     while (this._activeItems.size < this.getConcurrency() && !this.getIsEmpty()) {
-      const nextFn = this.getNextItem();
-      if (!nextFn) {
+      const nextItem = this.getPeek();
+      if (!nextItem) {
         break;
       }
-      this._activeItems.add(nextFn);
+      this._activeItems.add(nextItem);
       (_b = (_a = this._options).onItemsChange) == null ? void 0 : _b.call(_a, this);
       (async () => {
-        var _a2, _b2, _c, _d, _e, _f, _g, _h;
-        let res;
-        try {
-          res = await nextFn();
-          this._successCount++;
-          (_b2 = (_a2 = this._options).onSuccess) == null ? void 0 : _b2.call(_a2, res, this);
-        } catch (error) {
-          this._errorCount++;
-          (_d = (_c = this._options).onError) == null ? void 0 : _d.call(_c, error, this);
-          if (this._options.throwOnError) {
-            throw error;
-          } else {
-            console.error(error);
-          }
-        } finally {
-          this._settledCount++;
-          this._activeItems.delete(nextFn);
-          (_f = (_e = this._options).onItemsChange) == null ? void 0 : _f.call(_e, this);
-          (_h = (_g = this._options).onSettled) == null ? void 0 : _h.call(_g, this);
-        }
+        this._lastResult = await this.execute();
         const wait = this.getWait();
         if (wait > 0) {
           setTimeout(() => this.tick(), wait);
@@ -110,40 +93,7 @@ class AsyncQueuer {
     this._pendingTick = false;
   }
   /**
-   * Checks for and removes expired items from the queuer
-   */
-  checkExpiredItems() {
-    var _a, _b, _c, _d;
-    if (this._options.expirationDuration === Infinity && this._options.getIsExpired === defaultOptions.getIsExpired)
-      return;
-    const now = Date.now();
-    const expiredIndices = [];
-    for (let i = 0; i < this._items.length; i++) {
-      const timestamp = this._itemTimestamps[i];
-      if (timestamp === void 0) continue;
-      const item = this._items[i];
-      if (item === void 0) continue;
-      const isExpired = this._options.getIsExpired !== defaultOptions.getIsExpired ? this._options.getIsExpired(item, timestamp) : now - timestamp > this._options.expirationDuration;
-      if (isExpired) {
-        expiredIndices.push(i);
-      }
-    }
-    for (let i = expiredIndices.length - 1; i >= 0; i--) {
-      const index = expiredIndices[i];
-      if (index === void 0) continue;
-      const expiredItem = this._items[index];
-      if (expiredItem === void 0) continue;
-      this._items.splice(index, 1);
-      this._itemTimestamps.splice(index, 1);
-      this._expirationCount++;
-      (_b = (_a = this._options).onExpire) == null ? void 0 : _b.call(_a, expiredItem, this);
-    }
-    if (expiredIndices.length > 0) {
-      (_d = (_c = this._options).onItemsChange) == null ? void 0 : _d.call(_c, this);
-    }
-  }
-  /**
-   * Starts the queuer and processes items
+   * Starts processing items in the queue. If already running, does nothing.
    */
   start() {
     var _a, _b;
@@ -153,19 +103,9 @@ class AsyncQueuer {
       this.tick();
     }
     (_b = (_a = this._options).onIsRunningChange) == null ? void 0 : _b.call(_a, this);
-    return new Promise((resolve) => {
-      const checkIdle = () => {
-        if (this.getIsIdle()) {
-          resolve();
-        } else {
-          setTimeout(checkIdle, 100);
-        }
-      };
-      checkIdle();
-    });
   }
   /**
-   * Stops the queuer from processing items
+   * Stops processing items in the queue. Does not clear the queue.
    */
   stop() {
     var _a, _b;
@@ -174,7 +114,7 @@ class AsyncQueuer {
     (_b = (_a = this._options).onIsRunningChange) == null ? void 0 : _b.call(_a, this);
   }
   /**
-   * Removes all items from the queuer
+   * Removes all pending items from the queue. Does not affect active tasks.
    */
   clear() {
     var _a, _b;
@@ -182,7 +122,8 @@ class AsyncQueuer {
     (_b = (_a = this._options).onItemsChange) == null ? void 0 : _b.call(_a, this);
   }
   /**
-   * Resets the queuer to its initial state
+   * Resets the queuer to its initial state. Optionally repopulates with initial items.
+   * Does not affect callbacks or options.
    */
   reset(withInitialItems) {
     this.clear();
@@ -195,34 +136,41 @@ class AsyncQueuer {
     this._running = this._options.started;
   }
   /**
-   * Adds a task to the queuer
+   * Adds an item to the queue. If the queue is full, the item is rejected and onReject is called.
+   * Items can be inserted based on priority or at the front/back depending on configuration.
+   *
+   * @example
+   * ```ts
+   * queuer.addItem({ value: 'task', priority: 10 });
+   * queuer.addItem('task2', 'front');
+   * ```
    */
-  addItem(fn, position = this._options.addItemsTo, runOnItemsChange = true) {
+  addItem(item, position = this._options.addItemsTo, runOnItemsChange = true) {
     var _a, _b, _c, _d;
     if (this.getIsFull()) {
       this._rejectionCount++;
-      (_b = (_a = this._options).onReject) == null ? void 0 : _b.call(_a, fn, this);
+      (_b = (_a = this._options).onReject) == null ? void 0 : _b.call(_a, item, this);
       return;
     }
-    const priority = this._options.getPriority !== defaultOptions.getPriority ? this._options.getPriority(fn) : fn.priority;
+    const priority = this._options.getPriority !== defaultOptions.getPriority ? this._options.getPriority(item) : item.priority;
     if (priority !== void 0) {
       const insertIndex = this._items.findIndex((existing) => {
         const existingPriority = this._options.getPriority !== defaultOptions.getPriority ? this._options.getPriority(existing) : existing.priority;
-        return existingPriority > priority;
+        return existingPriority < priority;
       });
       if (insertIndex === -1) {
-        this._items.push(fn);
+        this._items.push(item);
         this._itemTimestamps.push(Date.now());
       } else {
-        this._items.splice(insertIndex, 0, fn);
+        this._items.splice(insertIndex, 0, item);
         this._itemTimestamps.splice(insertIndex, 0, Date.now());
       }
     } else {
       if (position === "front") {
-        this._items.unshift(fn);
+        this._items.unshift(item);
         this._itemTimestamps.unshift(Date.now());
       } else {
-        this._items.push(fn);
+        this._items.push(item);
         this._itemTimestamps.push(Date.now());
       }
     }
@@ -235,10 +183,19 @@ class AsyncQueuer {
     }
   }
   /**
-   * Removes and returns an item from the queuer
+   * Removes and returns the next item from the queue without executing the task function.
+   * Use for manual queue management. Normally, use execute() to process items.
+   *
+   * @example
+   * ```ts
+   * // FIFO
+   * queuer.getNextItem();
+   * // LIFO
+   * queuer.getNextItem('back');
+   * ```
    */
   getNextItem(position = this._options.getItemsFrom) {
-    var _a, _b, _c, _d;
+    var _a, _b;
     let item;
     if (position === "front") {
       item = this._items.shift();
@@ -249,12 +206,84 @@ class AsyncQueuer {
     }
     if (item !== void 0) {
       (_b = (_a = this._options).onItemsChange) == null ? void 0 : _b.call(_a, this);
-      (_d = (_c = this._options).onGetNextItem) == null ? void 0 : _d.call(_c, item, this);
     }
     return item;
   }
   /**
-   * Returns an item without removing it
+   * Removes and returns the next item from the queue and executes the task function with it.
+   *
+   * @example
+   * ```ts
+   * queuer.execute();
+   * // LIFO
+   * queuer.execute('back');
+   * ```
+   */
+  async execute(position) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const item = this.getNextItem(position);
+    if (item !== void 0) {
+      try {
+        this._lastResult = await this.fn(item);
+        this._successCount++;
+        (_b = (_a = this._options).onSuccess) == null ? void 0 : _b.call(_a, this._lastResult, this);
+      } catch (error) {
+        this._errorCount++;
+        (_d = (_c = this._options).onError) == null ? void 0 : _d.call(_c, error, this);
+        if (this._options.throwOnError) {
+          throw error;
+        }
+      } finally {
+        this._settledCount++;
+        this._activeItems.delete(item);
+        (_f = (_e = this._options).onItemsChange) == null ? void 0 : _f.call(_e, this);
+        (_h = (_g = this._options).onSettled) == null ? void 0 : _h.call(_g, this);
+      }
+    }
+    return item;
+  }
+  /**
+   * Checks for expired items in the queue and removes them. Calls onExpire for each expired item.
+   * Internal use only.
+   */
+  checkExpiredItems() {
+    var _a, _b, _c, _d;
+    if (this._options.expirationDuration === Infinity && this._options.getIsExpired === defaultOptions.getIsExpired)
+      return;
+    const now = Date.now();
+    const expiredIndices = [];
+    for (let i = 0; i < this._items.length; i++) {
+      const timestamp = this._itemTimestamps[i];
+      if (timestamp === void 0) continue;
+      const item = this._items[i];
+      if (item === void 0) continue;
+      const isExpired = this._options.getIsExpired !== defaultOptions.getIsExpired ? this._options.getIsExpired(item, timestamp) : now - timestamp > this._options.expirationDuration;
+      if (isExpired) {
+        expiredIndices.push(i);
+      }
+    }
+    for (let i = expiredIndices.length - 1; i >= 0; i--) {
+      const index = expiredIndices[i];
+      if (index === void 0) continue;
+      const expiredItem = this._items[index];
+      if (expiredItem === void 0) continue;
+      this._items.splice(index, 1);
+      this._itemTimestamps.splice(index, 1);
+      this._expirationCount++;
+      (_b = (_a = this._options).onExpire) == null ? void 0 : _b.call(_a, expiredItem, this);
+    }
+    if (expiredIndices.length > 0) {
+      (_d = (_c = this._options).onItemsChange) == null ? void 0 : _d.call(_c, this);
+    }
+  }
+  /**
+   * Returns the next item in the queue without removing it.
+   *
+   * @example
+   * ```ts
+   * queuer.getPeek(); // front
+   * queuer.getPeek('back'); // back
+   * ```
    */
   getPeek(position = "front") {
     if (position === "front") {
@@ -263,87 +292,87 @@ class AsyncQueuer {
     return this._items[this._items.length - 1];
   }
   /**
-   * Returns true if the queuer is empty
+   * Returns true if the queue is empty (no pending items).
    */
   getIsEmpty() {
     return this._items.length === 0;
   }
   /**
-   * Returns true if the queuer is full
+   * Returns true if the queue is full (reached maxSize).
    */
   getIsFull() {
     return this._items.length >= this._options.maxSize;
   }
   /**
-   * Returns the current size of the queuer
+   * Returns the number of pending items in the queue.
    */
   getSize() {
     return this._items.length;
   }
   /**
-   * Returns a copy of all items in the queuer
+   * Returns a copy of all items in the queue, including active and pending items.
    */
   getAllItems() {
     return [...this.getActiveItems(), ...this.getPendingItems()];
   }
   /**
-   * Returns the active items
+   * Returns the items currently being processed (active tasks).
    */
   getActiveItems() {
     return Array.from(this._activeItems);
   }
   /**
-   * Returns the pending items
+   * Returns the items waiting to be processed (pending tasks).
    */
   getPendingItems() {
     return [...this._items];
   }
   /**
-   * Returns the number of items that have been successfully processed
+   * Returns the number of items that have been successfully processed.
    */
   getSuccessCount() {
     return this._successCount;
   }
   /**
-   * Returns the number of items that have failed processing
+   * Returns the number of items that have failed processing.
    */
   getErrorCount() {
     return this._errorCount;
   }
   /**
-   * Returns the number of items that have completed processing (success or error)
+   * Returns the number of items that have completed processing (success or error).
    */
   getSettledCount() {
     return this._settledCount;
   }
   /**
-   * Returns the number of items that have been rejected from the queuer
+   * Returns the number of items that have been rejected from being added to the queue.
    */
   getRejectionCount() {
     return this._rejectionCount;
   }
   /**
-   * Returns true if the queuer is running
+   * Returns true if the queuer is currently running (processing items).
    */
   getIsRunning() {
     return this._running;
   }
   /**
-   * Returns true if the queuer is running but has no items to process
+   * Returns true if the queuer is running but has no items to process and no active tasks.
    */
   getIsIdle() {
     return this._running && this.getIsEmpty() && this._activeItems.size === 0;
   }
   /**
-   * Returns the number of items that have expired from the queuer
+   * Returns the number of items that have expired and been removed from the queue.
    */
   getExpirationCount() {
     return this._expirationCount;
   }
 }
-function asyncQueue(options) {
-  const queuer = new AsyncQueuer(options);
-  return queuer.addItem.bind(queuer);
+function asyncQueue(fn, initialOptions) {
+  const asyncQueuer = new AsyncQueuer(fn, initialOptions);
+  return asyncQueuer.addItem.bind(asyncQueuer);
 }
 exports.AsyncQueuer = AsyncQueuer;
 exports.asyncQueue = asyncQueue;