@tanstack/pacer 0.5.0 → 0.7.0

package/dist/esm/batcher.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Options for configuring a Batcher instance
+ */
+export interface BatcherOptions<TValue> {
+    /**
+     * Custom function to determine if a batch should be processed
+     * Return true to process the batch immediately
+     */
+    getShouldExecute?: (items: Array<TValue>, batcher: Batcher<TValue>) => boolean;
+    /**
+     * Maximum number of items in a batch
+     * @default Infinity
+     */
+    maxSize?: number;
+    /**
+     * 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
+     */
+    onItemsChange?: (batcher: Batcher<TValue>) => void;
+    /**
+     * Whether the batcher should start processing immediately
+     * @default true
+     */
+    started?: boolean;
+    /**
+     * Maximum time in milliseconds to wait before processing a batch.
+     * If the wait duration has elapsed, the batch will be processed.
+     * If not provided, the batch will not be triggered by a timeout.
+     * @default Infinity
+     */
+    wait?: number;
+}
+/**
+ * A class that collects items and processes them in batches.
+ *
+ * Batching is a technique for grouping multiple operations together to be processed as a single unit.
+ *
+ * The Batcher provides a flexible way to implement batching with configurable:
+ * - Maximum batch size (number of items per batch)
+ * - Time-based batching (process after X milliseconds)
+ * - Custom batch processing logic via getShouldExecute
+ * - Event callbacks for monitoring batch operations
+ *
+ * @example
+ * ```ts
+ * const batcher = new Batcher<number>(
+ *   (items) => console.log('Processing batch:', items),
+ *   {
+ *     maxSize: 5,
+ *     wait: 2000,
+ *     onExecuteBatch: (items) => console.log('Batch executed:', items)
+ *   }
+ * );
+ *
+ * batcher.addItem(1);
+ * 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
+ * ```
+ */
+export declare class Batcher<TValue> {
+    private fn;
+    private _options;
+    private _batchExecutionCount;
+    private _itemExecutionCount;
+    private _items;
+    private _running;
+    private _timeoutId;
+    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>;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    execute(): void;
+    /**
+     * Stops the batcher from processing batches
+     */
+    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;
+    /**
+     * Returns a copy of all items currently in the batcher
+     */
+    getAllItems(): Array<TValue>;
+    /**
+     * Returns the number of times batches have been processed
+     */
+    getBatchExecutionCount(): number;
+    /**
+     * Returns the total number of individual items that have been processed
+     */
+    getItemExecutionCount(): number;
+}
+/**
+ * Creates a batcher that processes items in batches
+ *
+ * @example
+ * ```ts
+ * const batchItems = batch<number>({
+ *   batchSize: 3,
+ *   processBatch: (items) => console.log('Processing:', items)
+ * });
+ *
+ * batchItems(1);
+ * batchItems(2);
+ * batchItems(3); // Triggers batch processing
+ * ```
+ */
+export declare function batch<TValue>(fn: (items: Array<TValue>) => void, options: BatcherOptions<TValue>): (item: TValue) => void;

package/dist/esm/batcher.js

@@ -0,0 +1,138 @@
+const defaultOptions = {
+  getShouldExecute: () => false,
+  maxSize: Infinity,
+  started: true,
+  wait: Infinity
+};
+class Batcher {
+  constructor(fn, initialOptions) {
+    this.fn = fn;
+    this._batchExecutionCount = 0;
+    this._itemExecutionCount = 0;
+    this._items = [];
+    this._timeoutId = null;
+    this._options = { ...defaultOptions, ...initialOptions };
+    this._running = this._options.started;
+  }
+  /**
+   * Updates the batcher options
+   */
+  setOptions(newOptions) {
+    this._options = { ...this._options, ...newOptions };
+  }
+  /**
+   * Returns the current batcher options
+   */
+  getOptions() {
+    return this._options;
+  }
+  /**
+   * 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) {
+    var _a, _b;
+    this._items.push(item);
+    (_b = (_a = this._options).onItemsChange) == null ? void 0 : _b.call(_a, this);
+    const shouldProcess = this._items.length >= this._options.maxSize || this._options.getShouldExecute(this._items, this);
+    if (shouldProcess) {
+      this.execute();
+    } else if (this._running && !this._timeoutId && this._options.wait !== Infinity) {
+      this._timeoutId = setTimeout(() => this.execute(), this._options.wait);
+    }
+  }
+  /**
+   * 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.
+   */
+  execute() {
+    var _a, _b, _c, _d;
+    if (this._timeoutId) {
+      clearTimeout(this._timeoutId);
+      this._timeoutId = null;
+    }
+    if (this._items.length === 0) {
+      return;
+    }
+    const batch2 = this.getAllItems();
+    this._items = [];
+    (_b = (_a = this._options).onItemsChange) == null ? void 0 : _b.call(_a, this);
+    this.fn(batch2);
+    this._batchExecutionCount++;
+    this._itemExecutionCount += batch2.length;
+    (_d = (_c = this._options).onExecute) == null ? void 0 : _d.call(_c, this);
+  }
+  /**
+   * Stops the batcher from processing batches
+   */
+  stop() {
+    var _a, _b;
+    this._running = false;
+    (_b = (_a = this._options).onIsRunningChange) == null ? void 0 : _b.call(_a, this);
+    if (this._timeoutId) {
+      clearTimeout(this._timeoutId);
+      this._timeoutId = null;
+    }
+  }
+  /**
+   * Starts the batcher and processes any pending items
+   */
+  start() {
+    var _a, _b;
+    this._running = true;
+    (_b = (_a = this._options).onIsRunningChange) == null ? void 0 : _b.call(_a, this);
+    if (this._items.length > 0 && !this._timeoutId) {
+      this._timeoutId = setTimeout(() => this.execute(), this._options.wait);
+    }
+  }
+  /**
+   * Returns the current number of items in the batcher
+   */
+  getSize() {
+    return this._items.length;
+  }
+  /**
+   * Returns true if the batcher is empty
+   */
+  getIsEmpty() {
+    return this._items.length === 0;
+  }
+  /**
+   * Returns true if the batcher is running
+   */
+  getIsRunning() {
+    return this._running;
+  }
+  /**
+   * Returns a copy of all items currently in the batcher
+   */
+  getAllItems() {
+    return [...this._items];
+  }
+  /**
+   * Returns the number of times batches have been processed
+   */
+  getBatchExecutionCount() {
+    return this._batchExecutionCount;
+  }
+  /**
+   * Returns the total number of individual items that have been processed
+   */
+  getItemExecutionCount() {
+    return this._itemExecutionCount;
+  }
+}
+function batch(fn, options) {
+  const batcher = new Batcher(fn, options);
+  return batcher.addItem.bind(batcher);
+}
+export {
+  Batcher,
+  batch
+};
+//# sourceMappingURL=batcher.js.map

package/dist/esm/batcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batcher.js","sources":["../../src/batcher.ts"],"sourcesContent":["import type { OptionalKeys } from './types'\n\n/**\n * Options for configuring a Batcher instance\n */\nexport interface BatcherOptions<TValue> {\n  /**\n   * Custom function to determine if a batch should be processed\n   * Return true to process the batch immediately\n   */\n  getShouldExecute?: (items: Array<TValue>, batcher: Batcher<TValue>) => boolean\n  /**\n   * Maximum number of items in a batch\n   * @default Infinity\n   */\n  maxSize?: number\n  /**\n   * Callback fired after a batch is processed\n   */\n  onExecute?: (batcher: Batcher<TValue>) => void\n  /**\n   * Callback fired when the batcher's running state changes\n   */\n  onIsRunningChange?: (batcher: Batcher<TValue>) => void\n  /**\n   * Callback fired after items are added to the batcher\n   */\n  onItemsChange?: (batcher: Batcher<TValue>) => void\n  /**\n   * Whether the batcher should start processing immediately\n   * @default true\n   */\n  started?: boolean\n  /**\n   * Maximum time in milliseconds to wait before processing a batch.\n   * If the wait duration has elapsed, the batch will be processed.\n   * If not provided, the batch will not be triggered by a timeout.\n   * @default Infinity\n   */\n  wait?: number\n}\n\ntype BatcherOptionsWithOptionalCallbacks<TValue> = OptionalKeys<\n  Required<BatcherOptions<TValue>>,\n  'onExecute' | 'onItemsChange' | 'onIsRunningChange'\n>\n\nconst defaultOptions: BatcherOptionsWithOptionalCallbacks<any> = {\n  getShouldExecute: () => false,\n  maxSize: Infinity,\n  started: true,\n  wait: Infinity,\n}\n\n/**\n * A class that collects items and processes them in batches.\n *\n * Batching is a technique for grouping multiple operations together to be processed as a single unit.\n *\n * The Batcher provides a flexible way to implement batching with configurable:\n * - Maximum batch size (number of items per batch)\n * - Time-based batching (process after X milliseconds)\n * - Custom batch processing logic via getShouldExecute\n * - Event callbacks for monitoring batch operations\n *\n * @example\n * ```ts\n * const batcher = new Batcher<number>(\n *   (items) => console.log('Processing batch:', items),\n *   {\n *     maxSize: 5,\n *     wait: 2000,\n *     onExecuteBatch: (items) => console.log('Batch executed:', items)\n *   }\n * );\n *\n * batcher.addItem(1);\n * batcher.addItem(2);\n * // After 2 seconds or when 5 items are added, whichever comes first,\n * // the batch will be processed\n * // batcher.execute() // manually trigger a batch\n * ```\n */\nexport class Batcher<TValue> {\n  private _options: BatcherOptionsWithOptionalCallbacks<TValue>\n  private _batchExecutionCount = 0\n  private _itemExecutionCount = 0\n  private _items: Array<TValue> = []\n  private _running: boolean\n  private _timeoutId: NodeJS.Timeout | null = null\n\n  constructor(\n    private fn: (items: Array<TValue>) => void,\n    initialOptions: BatcherOptions<TValue>,\n  ) {\n    this._options = { ...defaultOptions, ...initialOptions }\n    this._running = this._options.started\n  }\n\n  /**\n   * Updates the batcher options\n   */\n  setOptions(newOptions: Partial<BatcherOptions<TValue>>): void {\n    this._options = { ...this._options, ...newOptions }\n  }\n\n  /**\n   * Returns the current batcher options\n   */\n  getOptions(): BatcherOptions<TValue> {\n    return this._options\n  }\n\n  /**\n   * Adds an item to the batcher\n   * If the batch size is reached, timeout occurs, or shouldProcess returns true, the batch will be processed\n   */\n  addItem(item: TValue): void {\n    this._items.push(item)\n    this._options.onItemsChange?.(this)\n\n    const shouldProcess =\n      this._items.length >= this._options.maxSize ||\n      this._options.getShouldExecute(this._items, this)\n\n    if (shouldProcess) {\n      this.execute()\n    } else if (\n      this._running &&\n      !this._timeoutId &&\n      this._options.wait !== Infinity\n    ) {\n      this._timeoutId = setTimeout(() => this.execute(), this._options.wait)\n    }\n  }\n\n  /**\n   * Processes the current batch of items.\n   * This method will automatically be triggered if the batcher is running and any of these conditions are met:\n   * - The number of items reaches batchSize\n   * - The wait duration has elapsed\n   * - The getShouldExecute function returns true upon adding an item\n   *\n   * You can also call this method manually to process the current batch at any time.\n   */\n  execute(): void {\n    if (this._timeoutId) {\n      clearTimeout(this._timeoutId)\n      this._timeoutId = null\n    }\n\n    if (this._items.length === 0) {\n      return\n    }\n\n    const batch = this.getAllItems() // copy of the items to be processed (to prevent race conditions)\n    this._items = [] // Clear items before processing to prevent race conditions\n    this._options.onItemsChange?.(this) // Call onItemsChange to notify listeners that the items have changed\n\n    this.fn(batch)\n    this._batchExecutionCount++\n    this._itemExecutionCount += batch.length\n    this._options.onExecute?.(this)\n  }\n\n  /**\n   * Stops the batcher from processing batches\n   */\n  stop(): void {\n    this._running = false\n    this._options.onIsRunningChange?.(this)\n    if (this._timeoutId) {\n      clearTimeout(this._timeoutId)\n      this._timeoutId = null\n    }\n  }\n\n  /**\n   * Starts the batcher and processes any pending items\n   */\n  start(): void {\n    this._running = true\n    this._options.onIsRunningChange?.(this)\n    if (this._items.length > 0 && !this._timeoutId) {\n      this._timeoutId = setTimeout(() => this.execute(), this._options.wait)\n    }\n  }\n\n  /**\n   * Returns the current number of items in the batcher\n   */\n  getSize(): number {\n    return this._items.length\n  }\n\n  /**\n   * Returns true if the batcher is empty\n   */\n  getIsEmpty(): boolean {\n    return this._items.length === 0\n  }\n\n  /**\n   * Returns true if the batcher is running\n   */\n  getIsRunning(): boolean {\n    return this._running\n  }\n\n  /**\n   * Returns a copy of all items currently in the batcher\n   */\n  getAllItems(): Array<TValue> {\n    return [...this._items]\n  }\n\n  /**\n   * Returns the number of times batches have been processed\n   */\n  getBatchExecutionCount(): number {\n    return this._batchExecutionCount\n  }\n\n  /**\n   * Returns the total number of individual items that have been processed\n   */\n  getItemExecutionCount(): number {\n    return this._itemExecutionCount\n  }\n}\n\n/**\n * Creates a batcher that processes items in batches\n *\n * @example\n * ```ts\n * const batchItems = batch<number>({\n *   batchSize: 3,\n *   processBatch: (items) => console.log('Processing:', items)\n * });\n *\n * batchItems(1);\n * batchItems(2);\n * batchItems(3); // Triggers batch processing\n * ```\n */\nexport function batch<TValue>(\n  fn: (items: Array<TValue>) => void,\n  options: BatcherOptions<TValue>,\n) {\n  const batcher = new Batcher<TValue>(fn, options)\n  return batcher.addItem.bind(batcher)\n}\n"],"names":["batch"],"mappings":"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"}

package/dist/esm/debouncer.d.ts

@@ -64,7 +64,6 @@ export declare class Debouncer<TFn extends AnyFunction> {
     constructor(fn: TFn, initialOptions: DebouncerOptions<TFn>);
     /**
      * Updates the debouncer options
-     * Returns the new options state
      */
     setOptions(newOptions: Partial<DebouncerOptions<TFn>>): void;
     /**
@@ -84,7 +83,7 @@ export declare class Debouncer<TFn extends AnyFunction> {
      * If a call is already in progress, it will be queued
      */
     maybeExecute(...args: Parameters<TFn>): void;
-    private executeFunction;
+    private execute;
     /**
      * Cancels any pending execution
      */

package/dist/esm/debouncer.js

@@ -20,7 +20,6 @@ class Debouncer {
   }
   /**
    * Updates the debouncer options
-   * Returns the new options state
    */
   setOptions(newOptions) {
     this._options = { ...this._options, ...newOptions };
@@ -55,7 +54,7 @@ class Debouncer {
     if (this._options.leading && this._canLeadingExecute) {
       this._canLeadingExecute = false;
       _didLeadingExecute = true;
-      this.executeFunction(...args);
+      this.execute(...args);
     }
     if (this._options.trailing) {
       this._isPending = true;
@@ -64,11 +63,11 @@ class Debouncer {
     this._timeoutId = setTimeout(() => {
       this._canLeadingExecute = true;
       if (this._options.trailing && !_didLeadingExecute) {
-        this.executeFunction(...args);
+        this.execute(...args);
       }
     }, this.getWait());
   }
-  executeFunction(...args) {
+  execute(...args) {
     if (!this.getEnabled()) return void 0;
     this.fn(...args);
     this._isPending = false;

package/dist/esm/debouncer.js.map

@@ -1 +1 @@
-{"version":3,"file":"debouncer.js","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   * Returns the new options state\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.executeFunction(...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.executeFunction(...args)\n      }\n    }, this.getWait())\n  }\n\n  private executeFunction(...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":[],"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;AAAA,EAOF,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,WAAO,qBAAqB,KAAK,SAAS,SAAS,IAAI;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMzD,UAAkB;AAChB,WAAO,qBAAqB,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,gBAAgB,GAAG,IAAI;AAAA,IAAA;AAI1B,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,gBAAgB,GAAG,IAAI;AAAA,MAAA;AAAA,IAC9B,GACC,KAAK,SAAS;AAAA,EAAA;AAAA,EAGX,mBAAmB,MAA6B;AACtD,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.js","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":[],"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,WAAO,qBAAqB,KAAK,SAAS,SAAS,IAAI;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMzD,UAAkB;AAChB,WAAO,qBAAqB,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;"}

package/dist/esm/index.d.ts

@@ -2,6 +2,7 @@ export * from './async-debouncer.js';
 export * from './async-queuer.js';
 export * from './async-rate-limiter.js';
 export * from './async-throttler.js';
+export * from './batcher.js';
 export * from './compare.js';
 export * from './debouncer.js';
 export * from './queuer.js';

package/dist/esm/index.js

@@ -2,6 +2,7 @@ import { AsyncDebouncer, asyncDebounce } from "./async-debouncer.js";
 import { AsyncQueuer, asyncQueue } from "./async-queuer.js";
 import { AsyncRateLimiter, asyncRateLimit } from "./async-rate-limiter.js";
 import { AsyncThrottler, asyncThrottle } from "./async-throttler.js";
+import { Batcher, batch } from "./batcher.js";
 import { isPlainArray, isPlainObject, replaceEqualDeep, shallowEqualObjects } from "./compare.js";
 import { Debouncer, debounce } from "./debouncer.js";
 import { Queuer, queue } from "./queuer.js";
@@ -13,6 +14,7 @@ export {
   AsyncQueuer,
   AsyncRateLimiter,
   AsyncThrottler,
+  Batcher,
   Debouncer,
   Queuer,
   RateLimiter,
@@ -21,6 +23,7 @@ export {
   asyncQueue,
   asyncRateLimit,
   asyncThrottle,
+  batch,
   bindInstanceMethods,
   debounce,
   isFunction,

package/dist/esm/index.js.map

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