@tanstack/pacer 0.6.0 → 0.7.0

package/dist/esm/async-debouncer.js.map

@@ -1 +1 @@
-{"version":3,"file":"async-debouncer.js","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":[],"mappings":"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"}
+{"version":3,"file":"async-debouncer.js","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":[],"mappings":"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"}

package/dist/esm/async-queuer.d.ts

@@ -1,9 +1,5 @@
-import { AnyAsyncFunction } from './types.js';
 import { QueuePosition } from './queuer.js';
-export type AsyncQueuerFn = AnyAsyncFunction & {
-    priority?: number;
-};
-export interface AsyncQueuerOptions<TFn extends AsyncQueuerFn> {
+export interface AsyncQueuerOptions<TValue> {
     /**
      * Default position to add items to the queuer
      * @default 'back'
@@ -14,7 +10,7 @@ export interface AsyncQueuerOptions<TFn extends AsyncQueuerFn> {
      * Can be a number or a function that returns a number.
      * @default 1
      */
-    concurrency?: number | ((queuer: AsyncQueuer<TFn>) => number);
+    concurrency?: number | ((queuer: AsyncQueuer<TValue>) => number);
     /**
      * Maximum time in milliseconds that an item can stay in the queue
      * If not provided, items will never expire
@@ -24,7 +20,7 @@ export interface AsyncQueuerOptions<TFn extends AsyncQueuerFn> {
      * Function to determine if an item has expired
      * If provided, this overrides the expirationDuration behavior
      */
-    getIsExpired?: (item: TFn, addedAt: number) => boolean;
+    getIsExpired?: (item: TValue, addedAt: number) => boolean;
     /**
      * Default position to get items from during processing
      * @default 'front'
@@ -35,13 +31,11 @@ export interface AsyncQueuerOptions<TFn extends AsyncQueuerFn> {
      * Higher priority items will be processed first
      * If not provided, will use static priority values attached to tasks
      */
-    getPriority?: (item: TFn) => number;
+    getPriority?: (item: TValue) => number;
     /**
      * Initial items to populate the queuer with
      */
-    initialItems?: Array<TFn & {
-        priority?: number;
-    }>;
+    initialItems?: Array<TValue>;
     /**
      * Maximum number of items allowed in the queuer
      */
@@ -51,35 +45,31 @@ export interface AsyncQueuerOptions<TFn extends AsyncQueuerFn> {
      * If provided, the handler will be called with the error and queuer instance.
      * This can be used alongside throwOnError - the handler will be called before any error is thrown.
      */
-    onError?: (error: unknown, queuer: AsyncQueuer<TFn>) => void;
+    onError?: (error: unknown, queuer: AsyncQueuer<TValue>) => void;
     /**
      * Callback fired whenever an item expires in the queuer
      */
-    onExpire?: (item: TFn, queuer: AsyncQueuer<TFn>) => void;
-    /**
-     * Callback fired whenever an item is removed from the queuer
-     */
-    onGetNextItem?: (item: TFn, queuer: AsyncQueuer<TFn>) => void;
+    onExpire?: (item: TValue, queuer: AsyncQueuer<TValue>) => void;
     /**
      * Callback fired whenever the queuer's running state changes
      */
-    onIsRunningChange?: (queuer: AsyncQueuer<TFn>) => void;
+    onIsRunningChange?: (queuer: AsyncQueuer<TValue>) => void;
     /**
      * Callback fired whenever an item is added or removed from the queuer
      */
-    onItemsChange?: (queuer: AsyncQueuer<TFn>) => void;
+    onItemsChange?: (queuer: AsyncQueuer<TValue>) => void;
     /**
      * Callback fired whenever an item is rejected from being added to the queuer
      */
-    onReject?: (item: TFn, queuer: AsyncQueuer<TFn>) => void;
+    onReject?: (item: TValue, queuer: AsyncQueuer<TValue>) => void;
     /**
      * Optional callback to call when a task is settled
      */
-    onSettled?: (queuer: AsyncQueuer<TFn>) => void;
+    onSettled?: (queuer: AsyncQueuer<TValue>) => void;
     /**
      * Optional callback to call when a task succeeds
      */
-    onSuccess?: (result: TFn, queuer: AsyncQueuer<TFn>) => void;
+    onSuccess?: (result: TValue, queuer: AsyncQueuer<TValue>) => void;
     /**
      * Whether the queuer should start processing tasks immediately or not.
      */
@@ -95,47 +85,48 @@ export interface AsyncQueuerOptions<TFn extends AsyncQueuerFn> {
      * Can be a number or a function that returns a number.
      * @default 0
      */
-    wait?: number | ((queuer: AsyncQueuer<TFn>) => number);
+    wait?: number | ((queuer: AsyncQueuer<TValue>) => number);
 }
 /**
- * A flexible asynchronous queue that processes tasks with configurable concurrency control.
+ * A flexible asynchronous queue for processing tasks with configurable concurrency, priority, and expiration.
  *
  * Features:
- * - Priority queue support via getPriority option
+ * - Priority queue support via the getPriority option
  * - Configurable concurrency limit
- * - Task success/error/completion callbacks
+ * - Callbacks for task success, error, completion, and queue state changes
  * - FIFO (First In First Out) or LIFO (Last In First Out) queue behavior
- * - Pause/resume task processing
+ * - Pause and resume processing
  * - Task cancellation
- * - Item expiration to clear stale items from the queue
+ * - Item expiration to remove stale items from the queue
  *
  * Tasks are processed concurrently up to the configured concurrency limit. When a task completes,
- * the next pending task is processed if below the concurrency limit.
+ * the next pending task is processed if the concurrency limit allows.
  *
  * Error Handling:
  * - If an `onError` handler is provided, it will be called with the error and queuer instance
  * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
  * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
- * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
- * - The error state can be checked using the underlying AsyncQueuer instance
+ * - Both onError and throwOnError can be used together; the handler will be called before any error is thrown
+ * - The error state can be checked using the AsyncQueuer instance
  *
- * @example
+ * Example usage:
  * ```ts
- * const asyncQueuer = new AsyncQueuer<string>({
+ * const asyncQueuer = new AsyncQueuer<string>(async (item) => {
+ *   // process item
+ *   return item.toUpperCase();
+ * }, {
  *   concurrency: 2,
  *   onSuccess: (result) => {
- *     console.log(result); // 'Hello'
+ *     console.log(result);
  *   }
  * });
  *
- * asyncQueuer.addItem(async () => {
- *   return 'Hello';
- * });
- *
+ * asyncQueuer.addItem('hello');
  * asyncQueuer.start();
  * ```
  */
-export declare class AsyncQueuer<TFn extends AsyncQueuerFn> {
+export declare class AsyncQueuer<TValue> {
+    private fn;
     private _options;
     private _activeItems;
     private _successCount;
@@ -147,135 +138,172 @@ export declare class AsyncQueuer<TFn extends AsyncQueuerFn> {
     private _itemTimestamps;
     private _pendingTick;
     private _running;
-    constructor(initialOptions?: AsyncQueuerOptions<TFn>);
+    private _lastResult;
+    constructor(fn: (value: TValue) => Promise<any>, initialOptions: AsyncQueuerOptions<TValue>);
     /**
-     * Updates the queuer options
-     * Returns the new options state
+     * Updates the queuer options. New options are merged with existing options.
      */
-    setOptions(newOptions: Partial<AsyncQueuerOptions<TFn>>): void;
+    setOptions(newOptions: Partial<AsyncQueuerOptions<TValue>>): void;
     /**
-     * Returns the current queuer options
+     * Returns the current queuer options, including defaults and any overrides.
      */
-    getOptions(): AsyncQueuerOptions<TFn>;
+    getOptions(): AsyncQueuerOptions<TValue>;
     /**
-     * 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(): number;
     /**
-     * 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(): number;
     /**
-     * Processes items in the queuer
+     * Processes items in the queue up to the concurrency limit. Internal use only.
      */
     private tick;
     /**
-     * Checks for and removes expired items from the queuer
-     */
-    private checkExpiredItems;
-    /**
-     * Starts the queuer and processes items
+     * Starts processing items in the queue. If already running, does nothing.
      */
-    start(): Promise<void>;
+    start(): void;
     /**
-     * Stops the queuer from processing items
+     * Stops processing items in the queue. Does not clear the queue.
      */
     stop(): void;
     /**
-     * Removes all items from the queuer
+     * Removes all pending items from the queue. Does not affect active tasks.
      */
     clear(): void;
     /**
-     * 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?: boolean): void;
     /**
-     * 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: TFn, position?: QueuePosition, runOnItemsChange?: boolean): void;
-    /**
-     * Removes and returns an item from the queuer
+    addItem(item: TValue & {
+        priority?: number;
+    }, position?: QueuePosition, runOnItemsChange?: boolean): void;
+    /**
+     * 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?: QueuePosition): TValue | undefined;
+    /**
+     * Removes and returns the next item from the queue and executes the task function with it.
+     *
+     * @example
+     * ```ts
+     * queuer.execute();
+     * // LIFO
+     * queuer.execute('back');
+     * ```
+     */
+    execute(position?: QueuePosition): Promise<any>;
+    /**
+     * Checks for expired items in the queue and removes them. Calls onExpire for each expired item.
+     * Internal use only.
      */
-    getNextItem(position?: QueuePosition): TFn | undefined;
+    private checkExpiredItems;
     /**
-     * Returns an item without removing it
+     * Returns the next item in the queue without removing it.
+     *
+     * @example
+     * ```ts
+     * queuer.getPeek(); // front
+     * queuer.getPeek('back'); // back
+     * ```
      */
-    getPeek(position?: QueuePosition): TFn | undefined;
+    getPeek(position?: QueuePosition): TValue | undefined;
     /**
-     * Returns true if the queuer is empty
+     * Returns true if the queue is empty (no pending items).
      */
     getIsEmpty(): boolean;
     /**
-     * Returns true if the queuer is full
+     * Returns true if the queue is full (reached maxSize).
      */
     getIsFull(): boolean;
     /**
-     * Returns the current size of the queuer
+     * Returns the number of pending items in the queue.
      */
     getSize(): number;
     /**
-     * Returns a copy of all items in the queuer
+     * Returns a copy of all items in the queue, including active and pending items.
      */
-    getAllItems(): Array<TFn>;
+    getAllItems(): Array<TValue>;
     /**
-     * Returns the active items
+     * Returns the items currently being processed (active tasks).
      */
-    getActiveItems(): Array<TFn>;
+    getActiveItems(): Array<TValue>;
     /**
-     * Returns the pending items
+     * Returns the items waiting to be processed (pending tasks).
      */
-    getPendingItems(): Array<TFn>;
+    getPendingItems(): Array<TValue>;
     /**
-     * Returns the number of items that have been successfully processed
+     * Returns the number of items that have been successfully processed.
      */
     getSuccessCount(): number;
     /**
-     * Returns the number of items that have failed processing
+     * Returns the number of items that have failed processing.
      */
     getErrorCount(): number;
     /**
-     * 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(): number;
     /**
-     * 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(): number;
     /**
-     * Returns true if the queuer is running
+     * Returns true if the queuer is currently running (processing items).
      */
     getIsRunning(): boolean;
     /**
-     * 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(): boolean;
     /**
-     * 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(): number;
 }
 /**
- * Creates a new AsyncQueuer instance with the given options and returns a bound addItem function.
- * The queuer is automatically started and ready to process items.
+ * Creates a new AsyncQueuer instance and returns a bound addItem function for adding tasks.
+ * The queuer is started automatically and ready to process items.
  *
  * Error Handling:
  * - If an `onError` handler is provided, it will be called with the error and queuer instance
  * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
  * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
- * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - Both onError and throwOnError can be used together; the handler will be called before any error is thrown
  * - The error state can be checked using the underlying AsyncQueuer instance
  *
- * @example
+ * Example usage:
  * ```ts
- * const enqueue = asyncQueue<string>();
+ * const enqueue = asyncQueue<string>(async (item) => {
+ *   return item.toUpperCase();
+ * }, {...options});
  *
- * // Add items to be processed
- * enqueue(async () => {
- *   return 'Hello';
- * });
+ * enqueue('hello');
  * ```
- *
- * @param options - Configuration options for the AsyncQueuer
- * @returns A bound addItem function that can be used to add tasks to the queuer
  */
-export declare function asyncQueue<TFn extends AsyncQueuerFn>(options: AsyncQueuerOptions<TFn>): (fn: TFn, position?: QueuePosition, runOnItemsChange?: boolean) => void;
+export declare function asyncQueue<TValue>(fn: (value: TValue) => Promise<any>, initialOptions: AsyncQueuerOptions<TValue>): (item: TValue & {
+    priority?: number;
+}, position?: QueuePosition, runOnItemsChange?: boolean) => void;