@tanstack/pacer 0.7.0 → 0.9.0

package/dist/cjs/batcher.d.cts

@@ -1,3 +1,39 @@
+import { Store } from '@tanstack/store';
+import { OptionalKeys } from './types.cjs';
+export interface BatcherState<TValue> {
+    /**
+     * Number of batch executions that have been completed
+     */
+    executionCount: number;
+    /**
+     * Whether the batcher has no items to process (items array is empty)
+     */
+    isEmpty: boolean;
+    /**
+     * Whether the batcher is waiting for the timeout to trigger batch processing
+     */
+    isPending: boolean;
+    /**
+     * Whether the batcher is active and will process items automatically
+     */
+    isRunning: boolean;
+    /**
+     * Total number of items that have been processed across all batches
+     */
+    totalItemsProcessed: number;
+    /**
+     * Array of items currently queued for batch processing
+     */
+    items: Array<TValue>;
+    /**
+     * Number of items currently in the batch queue
+     */
+    size: number;
+    /**
+     * Current processing status - 'idle' when not processing, 'pending' when waiting for timeout
+     */
+    status: 'idle' | 'pending';
+}
 /**
  * Options for configuring a Batcher instance
  */
@@ -7,6 +43,10 @@ export interface BatcherOptions<TValue> {
      * Return true to process the batch immediately
      */
     getShouldExecute?: (items: Array<TValue>, batcher: Batcher<TValue>) => boolean;
+    /**
+     * Initial state for the batcher
+     */
+    initialState?: Partial<BatcherState<TValue>>;
     /**
      * Maximum number of items in a batch
      * @default Infinity
@@ -16,10 +56,6 @@ export interface BatcherOptions<TValue> {
      * Callback fired after a batch is processed
      */
     onExecute?: (batcher: Batcher<TValue>) => void;
-    /**
-     * Callback fired when the batcher's running state changes
-     */
-    onIsRunningChange?: (batcher: Batcher<TValue>) => void;
     /**
      * Callback fired after items are added to the batcher
      */
@@ -35,8 +71,9 @@ export interface BatcherOptions<TValue> {
      * If not provided, the batch will not be triggered by a timeout.
      * @default Infinity
      */
-    wait?: number;
+    wait?: number | ((batcher: Batcher<TValue>) => number);
 }
+type BatcherOptionsWithOptionalCallbacks<TValue> = OptionalKeys<Required<BatcherOptions<TValue>>, 'initialState' | 'onExecute' | 'onItemsChange'>;
 /**
  * A class that collects items and processes them in batches.
  *
@@ -48,6 +85,15 @@ export interface BatcherOptions<TValue> {
  * - Custom batch processing logic via getShouldExecute
  * - Event callbacks for monitoring batch operations
  *
+ * State Management:
+ * - Uses TanStack Store for reactive state management
+ * - Use `initialState` to provide initial state values when creating the batcher
+ * - Use `onExecute` callback to react to batch execution and implement custom logic
+ * - Use `onItemsChange` callback to react to items being added or removed from the batcher
+ * - The state includes batch execution count, total items processed, items, and running status
+ * - State can be accessed via `batcher.store.state` when using the class directly
+ * - When using framework adapters (React/Solid), state is accessed from `batcher.state`
+ *
  * @example
  * ```ts
  * const batcher = new Batcher<number>(
@@ -55,7 +101,7 @@ export interface BatcherOptions<TValue> {
  *   {
  *     maxSize: 5,
  *     wait: 2000,
- *     onExecuteBatch: (items) => console.log('Batch executed:', items)
+ *     onExecute: (batcher) => console.log('Batch executed:', batcher.peekAllItems())
  *   }
  * );
  *
@@ -63,83 +109,61 @@ export interface BatcherOptions<TValue> {
  * batcher.addItem(2);
  * // After 2 seconds or when 5 items are added, whichever comes first,
  * // the batch will be processed
- * // batcher.execute() // manually trigger a batch
+ * // batcher.flush() // manually trigger a batch
  * ```
  */
 export declare class Batcher<TValue> {
+    #private;
     private fn;
-    private _options;
-    private _batchExecutionCount;
-    private _itemExecutionCount;
-    private _items;
-    private _running;
-    private _timeoutId;
+    readonly store: Store<Readonly<BatcherState<TValue>>>;
+    options: BatcherOptionsWithOptionalCallbacks<TValue>;
     constructor(fn: (items: Array<TValue>) => void, initialOptions: BatcherOptions<TValue>);
     /**
      * Updates the batcher options
      */
-    setOptions(newOptions: Partial<BatcherOptions<TValue>>): void;
-    /**
-     * Returns the current batcher options
-     */
-    getOptions(): BatcherOptions<TValue>;
+    setOptions: (newOptions: Partial<BatcherOptions<TValue>>) => void;
     /**
      * Adds an item to the batcher
      * If the batch size is reached, timeout occurs, or shouldProcess returns true, the batch will be processed
      */
-    addItem(item: TValue): void;
+    addItem: (item: TValue) => void;
     /**
-     * Processes the current batch of items.
-     * This method will automatically be triggered if the batcher is running and any of these conditions are met:
-     * - The number of items reaches batchSize
-     * - The wait duration has elapsed
-     * - The getShouldExecute function returns true upon adding an item
-     *
-     * You can also call this method manually to process the current batch at any time.
+     * Processes the current batch of items immediately
      */
-    execute(): void;
+    flush: () => void;
     /**
      * Stops the batcher from processing batches
      */
-    stop(): void;
+    stop: () => void;
     /**
      * Starts the batcher and processes any pending items
      */
-    start(): void;
-    /**
-     * Returns the current number of items in the batcher
-     */
-    getSize(): number;
-    /**
-     * Returns true if the batcher is empty
-     */
-    getIsEmpty(): boolean;
-    /**
-     * Returns true if the batcher is running
-     */
-    getIsRunning(): boolean;
+    start: () => void;
     /**
-     * Returns a copy of all items currently in the batcher
+     * Returns a copy of all items in the batcher
      */
-    getAllItems(): Array<TValue>;
+    peekAllItems: () => Array<TValue>;
     /**
-     * Returns the number of times batches have been processed
+     * Removes all items from the batcher
      */
-    getBatchExecutionCount(): number;
+    clear: () => void;
     /**
-     * Returns the total number of individual items that have been processed
+     * Resets the batcher state to its default values
      */
-    getItemExecutionCount(): number;
+    reset: () => void;
 }
 /**
  * Creates a batcher that processes items in batches
  *
  * @example
  * ```ts
- * const batchItems = batch<number>({
- *   batchSize: 3,
- *   processBatch: (items) => console.log('Processing:', items)
- * });
+ * const batchItems = batch<number>(
+ *   (items) => console.log('Processing:', items),
+ *   {
+ *     maxSize: 3,
+ *     onExecute: (batcher) => console.log('Batch executed')
+ *   }
+ * );
  *
  * batchItems(1);
  * batchItems(2);
@@ -147,3 +171,4 @@ export declare class Batcher<TValue> {
  * ```
  */
 export declare function batch<TValue>(fn: (items: Array<TValue>) => void, options: BatcherOptions<TValue>): (item: TValue) => void;
+export {};

package/dist/cjs/debouncer.cjs

@@ -1,107 +1,119 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const store = require("@tanstack/store");
 const utils = require("./utils.cjs");
+function getDefaultDebouncerState() {
+  return structuredClone({
+    canLeadingExecute: true,
+    executionCount: 0,
+    isPending: false,
+    lastArgs: void 0,
+    status: "idle"
+  });
+}
 const defaultOptions = {
   enabled: true,
   leading: false,
-  onExecute: () => {
-  },
   trailing: true,
   wait: 0
 };
 class Debouncer {
   constructor(fn, initialOptions) {
     this.fn = fn;
-    this._canLeadingExecute = true;
-    this._executionCount = 0;
-    this._isPending = false;
-    this._options = {
+    this.store = new store.Store(
+      getDefaultDebouncerState()
+    );
+    this.setOptions = (newOptions) => {
+      this.options = { ...this.options, ...newOptions };
+      if (!this.#getEnabled()) {
+        this.cancel();
+      }
+    };
+    this.#setState = (newState) => {
+      this.store.setState((state) => {
+        const combinedState = {
+          ...state,
+          ...newState
+        };
+        const { isPending } = combinedState;
+        return {
+          ...combinedState,
+          status: !this.#getEnabled() ? "disabled" : isPending ? "pending" : "idle"
+        };
+      });
+    };
+    this.#getEnabled = () => {
+      return !!utils.parseFunctionOrValue(this.options.enabled, this);
+    };
+    this.#getWait = () => {
+      return utils.parseFunctionOrValue(this.options.wait, this);
+    };
+    this.maybeExecute = (...args) => {
+      if (!this.#getEnabled()) return void 0;
+      let _didLeadingExecute = false;
+      if (this.options.leading && this.store.state.canLeadingExecute) {
+        this.#setState({ canLeadingExecute: false });
+        _didLeadingExecute = true;
+        this.#execute(...args);
+      }
+      if (this.options.trailing) {
+        this.#setState({ isPending: true, lastArgs: args });
+      }
+      if (this.#timeoutId) clearTimeout(this.#timeoutId);
+      this.#timeoutId = setTimeout(() => {
+        this.#setState({ canLeadingExecute: true });
+        if (this.options.trailing && !_didLeadingExecute) {
+          this.#execute(...args);
+        }
+      }, this.#getWait());
+    };
+    this.#execute = (...args) => {
+      if (!this.#getEnabled()) return void 0;
+      this.fn(...args);
+      this.#setState({
+        isPending: false,
+        executionCount: this.store.state.executionCount + 1
+      });
+      this.options.onExecute?.(this);
+    };
+    this.flush = () => {
+      if (this.store.state.isPending && this.store.state.lastArgs) {
+        this.#clearTimeout();
+        this.#execute(...this.store.state.lastArgs);
+      }
+    };
+    this.#clearTimeout = () => {
+      if (this.#timeoutId) {
+        clearTimeout(this.#timeoutId);
+        this.#timeoutId = void 0;
+      }
+    };
+    this.cancel = () => {
+      this.#clearTimeout();
+      this.#setState({
+        canLeadingExecute: true,
+        isPending: false
+      });
+    };
+    this.reset = () => {
+      this.#setState(getDefaultDebouncerState());
+    };
+    this.options = {
       ...defaultOptions,
       ...initialOptions
     };
+    this.#setState(this.options.initialState ?? {});
   }
-  /**
-   * Updates the debouncer options
-   */
-  setOptions(newOptions) {
-    this._options = { ...this._options, ...newOptions };
-    if (!this._options.enabled) {
-      this._isPending = false;
-    }
-  }
-  /**
-   * Returns the current debouncer options
-   */
-  getOptions() {
-    return this._options;
-  }
-  /**
-   * Returns the current enabled state of the debouncer
-   */
-  getEnabled() {
-    return utils.parseFunctionOrValue(this._options.enabled, this);
-  }
-  /**
-   * Returns the current wait time in milliseconds
-   */
-  getWait() {
-    return utils.parseFunctionOrValue(this._options.wait, this);
-  }
-  /**
-   * Attempts to execute the debounced function
-   * If a call is already in progress, it will be queued
-   */
-  maybeExecute(...args) {
-    let _didLeadingExecute = false;
-    if (this._options.leading && this._canLeadingExecute) {
-      this._canLeadingExecute = false;
-      _didLeadingExecute = true;
-      this.execute(...args);
-    }
-    if (this._options.trailing) {
-      this._isPending = true;
-    }
-    if (this._timeoutId) clearTimeout(this._timeoutId);
-    this._timeoutId = setTimeout(() => {
-      this._canLeadingExecute = true;
-      if (this._options.trailing && !_didLeadingExecute) {
-        this.execute(...args);
-      }
-    }, this.getWait());
-  }
-  execute(...args) {
-    if (!this.getEnabled()) return void 0;
-    this.fn(...args);
-    this._isPending = false;
-    this._executionCount++;
-    this._options.onExecute(this);
-  }
-  /**
-   * Cancels any pending execution
-   */
-  cancel() {
-    if (this._timeoutId) {
-      clearTimeout(this._timeoutId);
-      this._canLeadingExecute = true;
-      this._isPending = false;
-    }
-  }
-  /**
-   * Returns the number of times the function has been executed
-   */
-  getExecutionCount() {
-    return this._executionCount;
-  }
-  /**
-   * Returns `true` if debouncing
-   */
-  getIsPending() {
-    return this.getEnabled() && this._isPending;
-  }
+  #timeoutId;
+  #setState;
+  #getEnabled;
+  #getWait;
+  #execute;
+  #clearTimeout;
 }
 function debounce(fn, initialOptions) {
   const debouncer = new Debouncer(fn, initialOptions);
-  return debouncer.maybeExecute.bind(debouncer);
+  return debouncer.maybeExecute;
 }
 exports.Debouncer = Debouncer;
 exports.debounce = debounce;

package/dist/cjs/debouncer.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"debouncer.cjs","sources":["../../src/debouncer.ts"],"sourcesContent":["import { parseFunctionOrValue } from './utils'\nimport type { AnyFunction } from './types'\n\n/**\n * Options for configuring a debounced function\n */\nexport interface DebouncerOptions<TFn extends AnyFunction> {\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: Debouncer<TFn>) => boolean)\n  /**\n   * Whether to execute on the leading edge of the timeout.\n   * The first call will execute immediately and the rest will wait the delay.\n   * Defaults to false.\n   */\n  leading?: boolean\n  /**\n   * Callback function that is called after the function is executed\n   */\n  onExecute?: (debouncer: Debouncer<TFn>) => void\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 before executing the function.\n   * Can be a number or a function that returns a number.\n   * Defaults to 0ms\n   */\n  wait: number | ((debouncer: Debouncer<TFn>) => number)\n}\n\nconst defaultOptions: Required<DebouncerOptions<any>> = {\n  enabled: true,\n  leading: false,\n  onExecute: () => {},\n  trailing: true,\n  wait: 0,\n}\n\n/**\n * A class that creates a debounced function.\n *\n * Debouncing ensures that a function is only executed after a certain amount of time has passed\n * since its last invocation. This is useful for handling frequent events like window resizing,\n * scroll events, or input changes where you want to limit the rate of execution.\n *\n * The debounced function can be configured to execute either at the start of the delay period\n * (leading edge) or at the end (trailing edge, default). Each new call during the wait period\n * will reset the timer.\n *\n * @example\n * ```ts\n * const debouncer = new Debouncer((value: string) => {\n *   saveToDatabase(value);\n * }, { wait: 500 });\n *\n * // Will only save after 500ms of no new input\n * inputElement.addEventListener('input', () => {\n *   debouncer.maybeExecute(inputElement.value);\n * });\n * ```\n */\nexport class Debouncer<TFn extends AnyFunction> {\n  private _canLeadingExecute = true\n  private _executionCount = 0\n  private _isPending = false\n  private _options: Required<DebouncerOptions<TFn>>\n  private _timeoutId: NodeJS.Timeout | undefined\n\n  constructor(\n    private fn: TFn,\n    initialOptions: DebouncerOptions<TFn>,\n  ) {\n    this._options = {\n      ...defaultOptions,\n      ...initialOptions,\n    }\n  }\n\n  /**\n   * Updates the debouncer options\n   */\n  setOptions(newOptions: Partial<DebouncerOptions<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(): Required<DebouncerOptions<TFn>> {\n    return this._options\n  }\n\n  /**\n   * Returns the current enabled state of the debouncer\n   */\n  getEnabled(): boolean {\n    return parseFunctionOrValue(this._options.enabled, this)\n  }\n\n  /**\n   * Returns the current wait time in milliseconds\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  maybeExecute(...args: Parameters<TFn>): void {\n    let _didLeadingExecute = false\n\n    // Handle leading execution\n    if (this._options.leading && this._canLeadingExecute) {\n      this._canLeadingExecute = false\n      _didLeadingExecute = true\n      this.execute(...args)\n    }\n\n    // Start pending state to indicate that the debouncer is waiting for the trailing edge\n    if (this._options.trailing) {\n      this._isPending = true\n    }\n\n    // Clear any existing timeout\n    if (this._timeoutId) clearTimeout(this._timeoutId)\n\n    // Set new timeout that will reset canLeadingExecute and execute trailing only if enabled and did not execute leading\n    this._timeoutId = setTimeout(() => {\n      this._canLeadingExecute = true\n      if (this._options.trailing && !_didLeadingExecute) {\n        this.execute(...args)\n      }\n    }, this.getWait())\n  }\n\n  private execute(...args: Parameters<TFn>): void {\n    if (!this.getEnabled()) return undefined\n    this.fn(...args) // EXECUTE!\n    this._isPending = false\n    this._executionCount++\n    this._options.onExecute(this)\n  }\n\n  /**\n   * Cancels any pending execution\n   */\n  cancel(): void {\n    if (this._timeoutId) {\n      clearTimeout(this._timeoutId)\n      this._canLeadingExecute = true\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 debouncing\n   */\n  getIsPending(): boolean {\n    return this.getEnabled() && this._isPending\n  }\n}\n\n/**\n * Creates a debounced function that delays invoking the provided function until after a specified wait time.\n * Multiple calls during the wait period will cancel previous pending invocations and reset the timer.\n *\n * This the the simple function wrapper implementation pulled from the Debouncer class. If you need\n * more control over the debouncing behavior, use the Debouncer class directly.\n *\n * If leading option is true, the function will execute immediately on the first call, then wait the delay\n * before allowing another execution.\n *\n * @example\n * ```ts\n * const debounced = debounce(() => {\n *   saveChanges();\n * }, { wait: 1000 });\n *\n * // Called repeatedly but executes at most once per second\n * inputElement.addEventListener('input', debounced);\n * ```\n */\nexport function debounce<TFn extends AnyFunction>(\n  fn: TFn,\n  initialOptions: DebouncerOptions<TFn>,\n): (...args: Parameters<TFn>) => void {\n  const debouncer = new Debouncer(fn, initialOptions)\n  return debouncer.maybeExecute.bind(debouncer)\n}\n"],"names":["parseFunctionOrValue"],"mappings":";;;AAoCA,MAAM,iBAAkD;AAAA,EACtD,SAAS;AAAA,EACT,SAAS;AAAA,EACT,WAAW,MAAM;AAAA,EAAC;AAAA,EAClB,UAAU;AAAA,EACV,MAAM;AACR;AAyBO,MAAM,UAAmC;AAAA,EAO9C,YACU,IACR,gBACA;AAFQ,SAAA,KAAA;AAPV,SAAQ,qBAAqB;AAC7B,SAAQ,kBAAkB;AAC1B,SAAQ,aAAa;AAQnB,SAAK,WAAW;AAAA,MACd,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMF,WAAW,YAAkD;AAC3D,SAAK,WAAW,EAAE,GAAG,KAAK,UAAU,GAAG,WAAW;AAG9C,QAAA,CAAC,KAAK,SAAS,SAAS;AAC1B,WAAK,aAAa;AAAA,IAAA;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA,EAMF,aAA8C;AAC5C,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,aAAsB;AACpB,WAAOA,MAAqB,qBAAA,KAAK,SAAS,SAAS,IAAI;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMzD,UAAkB;AAChB,WAAOA,MAAqB,qBAAA,KAAK,SAAS,MAAM,IAAI;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOtD,gBAAgB,MAA6B;AAC3C,QAAI,qBAAqB;AAGzB,QAAI,KAAK,SAAS,WAAW,KAAK,oBAAoB;AACpD,WAAK,qBAAqB;AACL,2BAAA;AAChB,WAAA,QAAQ,GAAG,IAAI;AAAA,IAAA;AAIlB,QAAA,KAAK,SAAS,UAAU;AAC1B,WAAK,aAAa;AAAA,IAAA;AAIpB,QAAI,KAAK,WAAyB,cAAA,KAAK,UAAU;AAG5C,SAAA,aAAa,WAAW,MAAM;AACjC,WAAK,qBAAqB;AAC1B,UAAI,KAAK,SAAS,YAAY,CAAC,oBAAoB;AAC5C,aAAA,QAAQ,GAAG,IAAI;AAAA,MAAA;AAAA,IACtB,GACC,KAAK,SAAS;AAAA,EAAA;AAAA,EAGX,WAAW,MAA6B;AAC9C,QAAI,CAAC,KAAK,WAAW,EAAU,QAAA;AAC1B,SAAA,GAAG,GAAG,IAAI;AACf,SAAK,aAAa;AACb,SAAA;AACA,SAAA,SAAS,UAAU,IAAI;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAM9B,SAAe;AACb,QAAI,KAAK,YAAY;AACnB,mBAAa,KAAK,UAAU;AAC5B,WAAK,qBAAqB;AAC1B,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,gBAAgB,KAAK;AAAA,EAAA;AAErC;AAsBgB,SAAA,SACd,IACA,gBACoC;AACpC,QAAM,YAAY,IAAI,UAAU,IAAI,cAAc;AAC3C,SAAA,UAAU,aAAa,KAAK,SAAS;AAC9C;;;"}
+{"version":3,"file":"debouncer.cjs","sources":["../../src/debouncer.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { parseFunctionOrValue } from './utils'\nimport type { AnyFunction } from './types'\n\nexport interface DebouncerState<TFn extends AnyFunction> {\n  /**\n   * Whether the debouncer can execute on the leading edge of the timeout\n   */\n  canLeadingExecute: boolean\n  /**\n   * Number of function executions that have been completed\n   */\n  executionCount: number\n  /**\n   * Whether the debouncer is waiting for the timeout to trigger execution\n   */\n  isPending: boolean\n  /**\n   * The arguments from the most recent call to maybeExecute\n   */\n  lastArgs: Parameters<TFn> | undefined\n  /**\n   * Current execution status - 'idle' when not active, 'pending' when waiting for timeout\n   */\n  status: 'disabled' | 'idle' | 'pending'\n}\n\nfunction getDefaultDebouncerState<\n  TFn extends AnyFunction,\n>(): DebouncerState<TFn> {\n  return structuredClone({\n    canLeadingExecute: true,\n    executionCount: 0,\n    isPending: false,\n    lastArgs: undefined,\n    status: 'idle',\n  })\n}\n\n/**\n * Options for configuring a debounced function\n */\nexport interface DebouncerOptions<TFn extends AnyFunction> {\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: Debouncer<TFn>) => boolean)\n  /**\n   * Initial state for the debouncer\n   */\n  initialState?: Partial<DebouncerState<TFn>>\n  /**\n   * Whether to execute on the leading edge of the timeout.\n   * The first call will execute immediately and the rest will wait the delay.\n   * Defaults to false.\n   */\n  leading?: boolean\n  /**\n   * Callback function that is called after the function is executed\n   */\n  onExecute?: (debouncer: Debouncer<TFn>) => void\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 before executing the function.\n   * Can be a number or a function that returns a number.\n   * Defaults to 0ms\n   */\n  wait: number | ((debouncer: Debouncer<TFn>) => number)\n}\n\nconst defaultOptions: Omit<\n  Required<DebouncerOptions<any>>,\n  'initialState' | 'onExecute'\n> = {\n  enabled: true,\n  leading: false,\n  trailing: true,\n  wait: 0,\n}\n\n/**\n * A class that creates a debounced function.\n *\n * Debouncing ensures that a function is only executed after a certain amount of time has passed\n * since its last invocation. This is useful for handling frequent events like window resizing,\n * scroll events, or input changes where you want to limit the rate of execution.\n *\n * The debounced function can be configured to execute either at the start of the delay period\n * (leading edge) or at the end (trailing edge, default). Each new call during the wait period\n * will reset the timer.\n *\n * State Management:\n * - Uses TanStack Store for reactive state management\n * - Use `initialState` to provide initial state values when creating the debouncer\n * - Use `onExecute` callback to react to function execution and implement custom logic\n * - The state includes canLeadingExecute, execution count, and isPending status\n * - State can be accessed via `debouncer.store.state` when using the class directly\n * - When using framework adapters (React/Solid), state is accessed from `debouncer.state`\n *\n * @example\n * ```ts\n * const debouncer = new Debouncer((value: string) => {\n *   saveToDatabase(value);\n * }, { wait: 500 });\n *\n * // Will only save after 500ms of no new input\n * inputElement.addEventListener('input', () => {\n *   debouncer.maybeExecute(inputElement.value);\n * });\n * ```\n */\nexport class Debouncer<TFn extends AnyFunction> {\n  readonly store: Store<Readonly<DebouncerState<TFn>>> = new Store(\n    getDefaultDebouncerState<TFn>(),\n  )\n  options: DebouncerOptions<TFn>\n  #timeoutId: NodeJS.Timeout | undefined\n\n  constructor(\n    private fn: TFn,\n    initialOptions: DebouncerOptions<TFn>,\n  ) {\n    this.options = {\n      ...defaultOptions,\n      ...initialOptions,\n    }\n    this.#setState(this.options.initialState ?? {})\n  }\n\n  /**\n   * Updates the debouncer options\n   */\n  setOptions = (newOptions: Partial<DebouncerOptions<TFn>>): void => {\n    this.options = { ...this.options, ...newOptions }\n\n    // Cancel pending execution if the debouncer is disabled\n    if (!this.#getEnabled()) {\n      this.cancel()\n    }\n  }\n\n  #setState = (newState: Partial<DebouncerState<TFn>>): void => {\n    this.store.setState((state) => {\n      const combinedState = {\n        ...state,\n        ...newState,\n      }\n      const { isPending } = combinedState\n      return {\n        ...combinedState,\n        status: !this.#getEnabled()\n          ? 'disabled'\n          : isPending\n            ? 'pending'\n            : 'idle',\n      }\n    })\n  }\n\n  /**\n   * Returns the current enabled state of the debouncer\n   */\n  #getEnabled = (): boolean => {\n    return !!parseFunctionOrValue(this.options.enabled, this)\n  }\n\n  /**\n   * Returns the current wait time in milliseconds\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  maybeExecute = (...args: Parameters<TFn>): void => {\n    if (!this.#getEnabled()) return undefined\n    let _didLeadingExecute = false\n\n    // Handle leading execution\n    if (this.options.leading && this.store.state.canLeadingExecute) {\n      this.#setState({ canLeadingExecute: false })\n      _didLeadingExecute = true\n      this.#execute(...args)\n    }\n\n    // Start pending state to indicate that the debouncer is waiting for the trailing edge\n    if (this.options.trailing) {\n      this.#setState({ isPending: true, lastArgs: args })\n    }\n\n    // Clear any existing timeout\n    if (this.#timeoutId) clearTimeout(this.#timeoutId)\n\n    // Set new timeout that will reset canLeadingExecute and execute trailing only if enabled and did not execute leading\n    this.#timeoutId = setTimeout(() => {\n      this.#setState({ canLeadingExecute: true })\n      if (this.options.trailing && !_didLeadingExecute) {\n        this.#execute(...args)\n      }\n    }, this.#getWait())\n  }\n\n  #execute = (...args: Parameters<TFn>): void => {\n    if (!this.#getEnabled()) return undefined\n    this.fn(...args) // EXECUTE!\n    this.#setState({\n      isPending: false,\n      executionCount: this.store.state.executionCount + 1,\n    })\n    this.options.onExecute?.(this)\n  }\n\n  /**\n   * Processes the current pending execution immediately\n   */\n  flush = (): void => {\n    if (this.store.state.isPending && this.store.state.lastArgs) {\n      this.#clearTimeout() // clear any pending timeout\n      this.#execute(...this.store.state.lastArgs) // execute immediately\n    }\n  }\n\n  #clearTimeout = (): void => {\n    if (this.#timeoutId) {\n      clearTimeout(this.#timeoutId)\n      this.#timeoutId = undefined\n    }\n  }\n\n  /**\n   * Cancels any pending execution\n   */\n  cancel = (): void => {\n    this.#clearTimeout()\n    this.#setState({\n      canLeadingExecute: true,\n      isPending: false,\n    })\n  }\n\n  /**\n   * Resets the debouncer state to its default values\n   */\n  reset = (): void => {\n    this.#setState(getDefaultDebouncerState<TFn>())\n  }\n}\n\n/**\n * Creates a debounced function that delays invoking the provided function until after a specified wait time.\n * Multiple calls during the wait period will cancel previous pending invocations and reset the timer.\n *\n * This the the simple function wrapper implementation pulled from the Debouncer class. If you need\n * more control over the debouncing behavior, use the Debouncer class directly.\n *\n * If leading option is true, the function will execute immediately on the first call, then wait the delay\n * before allowing another execution.\n *\n * State Management:\n * - Uses TanStack Store for reactive state management\n * - Use `initialState` to provide initial state values when creating the debouncer\n * - Use `onExecute` callback to react to function execution and implement custom logic\n * - The state includes canLeadingExecute, execution count, and isPending status\n * - State can be accessed via the underlying Debouncer instance's `store.state` property\n * - When using framework adapters (React/Solid), state is accessed from the hook's state property\n *\n * @example\n * ```ts\n * const debounced = debounce(() => {\n *   saveChanges();\n * }, { wait: 1000 });\n *\n * // Called repeatedly but executes at most once per second\n * inputElement.addEventListener('input', debounced);\n * ```\n */\nexport function debounce<TFn extends AnyFunction>(\n  fn: TFn,\n  initialOptions: DebouncerOptions<TFn>,\n): (...args: Parameters<TFn>) => void {\n  const debouncer = new Debouncer(fn, initialOptions)\n  return debouncer.maybeExecute\n}\n"],"names":["Store","parseFunctionOrValue"],"mappings":"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"}

package/dist/cjs/debouncer.d.cts

@@ -1,4 +1,27 @@
+import { Store } from '@tanstack/store';
 import { AnyFunction } from './types.cjs';
+export interface DebouncerState<TFn extends AnyFunction> {
+    /**
+     * Whether the debouncer can execute on the leading edge of the timeout
+     */
+    canLeadingExecute: boolean;
+    /**
+     * Number of function executions that have been completed
+     */
+    executionCount: number;
+    /**
+     * Whether the debouncer is waiting for the timeout to trigger execution
+     */
+    isPending: boolean;
+    /**
+     * The arguments from the most recent call to maybeExecute
+     */
+    lastArgs: Parameters<TFn> | undefined;
+    /**
+     * Current execution status - 'idle' when not active, 'pending' when waiting for timeout
+     */
+    status: 'disabled' | 'idle' | 'pending';
+}
 /**
  * Options for configuring a debounced function
  */
@@ -9,6 +32,10 @@ export interface DebouncerOptions<TFn extends AnyFunction> {
      * Defaults to true.
      */
     enabled?: boolean | ((debouncer: Debouncer<TFn>) => boolean);
+    /**
+     * Initial state for the debouncer
+     */
+    initialState?: Partial<DebouncerState<TFn>>;
     /**
      * Whether to execute on the leading edge of the timeout.
      * The first call will execute immediately and the rest will wait the delay.
@@ -42,6 +69,14 @@ export interface DebouncerOptions<TFn extends AnyFunction> {
  * (leading edge) or at the end (trailing edge, default). Each new call during the wait period
  * will reset the timer.
  *
+ * State Management:
+ * - Uses TanStack Store for reactive state management
+ * - Use `initialState` to provide initial state values when creating the debouncer
+ * - Use `onExecute` callback to react to function execution and implement custom logic
+ * - The state includes canLeadingExecute, execution count, and isPending status
+ * - State can be accessed via `debouncer.store.state` when using the class directly
+ * - When using framework adapters (React/Solid), state is accessed from `debouncer.state`
+ *
  * @example
  * ```ts
  * const debouncer = new Debouncer((value: string) => {
@@ -55,47 +90,32 @@ export interface DebouncerOptions<TFn extends AnyFunction> {
  * ```
  */
 export declare class Debouncer<TFn extends AnyFunction> {
+    #private;
     private fn;
-    private _canLeadingExecute;
-    private _executionCount;
-    private _isPending;
-    private _options;
-    private _timeoutId;
+    readonly store: Store<Readonly<DebouncerState<TFn>>>;
+    options: DebouncerOptions<TFn>;
     constructor(fn: TFn, initialOptions: DebouncerOptions<TFn>);
     /**
      * Updates the debouncer options
      */
-    setOptions(newOptions: Partial<DebouncerOptions<TFn>>): void;
-    /**
-     * Returns the current debouncer options
-     */
-    getOptions(): Required<DebouncerOptions<TFn>>;
-    /**
-     * Returns the current enabled state of the debouncer
-     */
-    getEnabled(): boolean;
-    /**
-     * Returns the current wait time in milliseconds
-     */
-    getWait(): number;
+    setOptions: (newOptions: Partial<DebouncerOptions<TFn>>) => void;
     /**
      * Attempts to execute the debounced function
      * If a call is already in progress, it will be queued
      */
-    maybeExecute(...args: Parameters<TFn>): void;
-    private execute;
+    maybeExecute: (...args: Parameters<TFn>) => void;
     /**
-     * Cancels any pending execution
+     * Processes the current pending execution immediately
      */
-    cancel(): void;
+    flush: () => void;
     /**
-     * Returns the number of times the function has been executed
+     * Cancels any pending execution
      */
-    getExecutionCount(): number;
+    cancel: () => void;
     /**
-     * Returns `true` if debouncing
+     * Resets the debouncer state to its default values
      */
-    getIsPending(): boolean;
+    reset: () => void;
 }
 /**
  * Creates a debounced function that delays invoking the provided function until after a specified wait time.
@@ -107,6 +127,14 @@ export declare class Debouncer<TFn extends AnyFunction> {
  * If leading option is true, the function will execute immediately on the first call, then wait the delay
  * before allowing another execution.
  *
+ * State Management:
+ * - Uses TanStack Store for reactive state management
+ * - Use `initialState` to provide initial state values when creating the debouncer
+ * - Use `onExecute` callback to react to function execution and implement custom logic
+ * - The state includes canLeadingExecute, execution count, and isPending status
+ * - State can be accessed via the underlying Debouncer instance's `store.state` property
+ * - When using framework adapters (React/Solid), state is accessed from the hook's state property
+ *
  * @example
  * ```ts
  * const debounced = debounce(() => {

package/dist/cjs/index.cjs

@@ -1,16 +1,18 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const asyncBatcher = require("./async-batcher.cjs");
 const asyncDebouncer = require("./async-debouncer.cjs");
 const asyncQueuer = require("./async-queuer.cjs");
 const asyncRateLimiter = require("./async-rate-limiter.cjs");
 const asyncThrottler = require("./async-throttler.cjs");
 const batcher = require("./batcher.cjs");
-const compare = require("./compare.cjs");
 const debouncer = require("./debouncer.cjs");
 const queuer = require("./queuer.cjs");
 const rateLimiter = require("./rate-limiter.cjs");
 const throttler = require("./throttler.cjs");
 const utils = require("./utils.cjs");
+exports.AsyncBatcher = asyncBatcher.AsyncBatcher;
+exports.asyncBatch = asyncBatcher.asyncBatch;
 exports.AsyncDebouncer = asyncDebouncer.AsyncDebouncer;
 exports.asyncDebounce = asyncDebouncer.asyncDebounce;
 exports.AsyncQueuer = asyncQueuer.AsyncQueuer;
@@ -21,10 +23,6 @@ exports.AsyncThrottler = asyncThrottler.AsyncThrottler;
 exports.asyncThrottle = asyncThrottler.asyncThrottle;
 exports.Batcher = batcher.Batcher;
 exports.batch = batcher.batch;
-exports.isPlainArray = compare.isPlainArray;
-exports.isPlainObject = compare.isPlainObject;
-exports.replaceEqualDeep = compare.replaceEqualDeep;
-exports.shallowEqualObjects = compare.shallowEqualObjects;
 exports.Debouncer = debouncer.Debouncer;
 exports.debounce = debouncer.debounce;
 exports.Queuer = queuer.Queuer;
@@ -33,7 +31,6 @@ exports.RateLimiter = rateLimiter.RateLimiter;
 exports.rateLimit = rateLimiter.rateLimit;
 exports.Throttler = throttler.Throttler;
 exports.throttle = throttler.throttle;
-exports.bindInstanceMethods = utils.bindInstanceMethods;
 exports.isFunction = utils.isFunction;
 exports.parseFunctionOrValue = utils.parseFunctionOrValue;
 //# sourceMappingURL=index.cjs.map

package/dist/cjs/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/index.d.cts

@@ -1,9 +1,9 @@
+export * from './async-batcher.cjs';
 export * from './async-debouncer.cjs';
 export * from './async-queuer.cjs';
 export * from './async-rate-limiter.cjs';
 export * from './async-throttler.cjs';
 export * from './batcher.cjs';
-export * from './compare.cjs';
 export * from './debouncer.cjs';
 export * from './queuer.cjs';
 export * from './rate-limiter.cjs';