@tanstack/pacer 0.21.1 → 0.23.0

package/dist/batcher.d.cts

@@ -1,180 +0,0 @@
-import { OptionalKeys } from "./types.cjs";
-import { Store } from "@tanstack/store";
-
-//#region src/batcher.d.ts
-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;
-  /**
-   * 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';
-  /**
-   * Total number of items that have been processed across all batches
-   */
-  totalItemsProcessed: number;
-}
-/**
- * Options for configuring a Batcher instance
- */
-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;
-  /**
-   * Initial state for the batcher
-   */
-  initialState?: Partial<BatcherState<TValue>>;
-  /**
-   * Optional key to identify this batcher instance.
-   * If provided, the batcher will be identified by this key in the devtools and PacerProvider if applicable.
-   */
-  key?: string;
-  /**
-   * Maximum number of items in a batch
-   * @default Infinity
-   */
-  maxSize?: number;
-  /**
-   * Callback fired after a batch is processed
-   */
-  onExecute?: (batch: Array<TValue>, 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 | ((batcher: Batcher<TValue>) => number);
-}
-type BatcherOptionsWithOptionalCallbacks<TValue> = OptionalKeys<Required<BatcherOptions<TValue>>, 'initialState' | 'onExecute' | 'onItemsChange' | 'key'>;
-/**
- * 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.
- * This synchronous version is lighter weight and often all you need - upgrade to AsyncBatcher when you need promises, retry support, abort/cancel capabilities, or advanced error handling.
- *
- * 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
- *
- * 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>(
- *   (items) => console.log('Processing batch:', items),
- *   {
- *     maxSize: 5,
- *     wait: 2000,
- *     onExecute: (batch, batcher) => console.log('Batch executed:', batch)
- *   }
- * );
- *
- * batcher.addItem(1);
- * batcher.addItem(2);
- * // After 2 seconds or when 5 items are added, whichever comes first,
- * // the batch will be processed
- * // batcher.flush() // manually trigger a batch
- * ```
- */
-declare class Batcher<TValue> {
-  #private;
-  fn: (items: Array<TValue>) => void;
-  readonly store: Store<Readonly<BatcherState<TValue>>>;
-  key: string | undefined;
-  options: BatcherOptionsWithOptionalCallbacks<TValue>;
-  constructor(fn: (items: Array<TValue>) => void, initialOptions: BatcherOptions<TValue>);
-  /**
-   * Updates the batcher options
-   */
-  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;
-  /**
-   * Processes the current batch of items immediately
-   */
-  flush: () => void;
-  /**
-   * Returns a copy of all items in the batcher
-   */
-  peekAllItems: () => Array<TValue>;
-  /**
-   * Removes all items from the batcher
-   */
-  clear: () => void;
-  /**
-   * Cancels any pending execution that was scheduled.
-   * Does NOT clear out the items.
-   */
-  cancel: () => void;
-  /**
-   * Resets the batcher state to its default values
-   */
-  reset: () => void;
-}
-/**
- * Creates a batcher that processes items in batches.
- *
- * This synchronous version is lighter weight and often all you need - upgrade to asyncBatch when you need promises, retry support, abort/cancel capabilities, or advanced error handling.
- *
- * @example
- * ```ts
- * const batchItems = batch<number>(
- *   (items) => console.log('Processing:', items),
- *   {
- *     maxSize: 3,
- *     onExecute: (batch, batcher) => console.log('Batch executed:', batch)
- *   }
- * );
- *
- * batchItems(1);
- * batchItems(2);
- * batchItems(3); // Triggers batch processing
- * ```
- */
-declare function batch<TValue>(fn: (items: Array<TValue>) => void, options: BatcherOptions<TValue>): (item: TValue) => void;
-//#endregion
-export { Batcher, BatcherOptions, BatcherState, batch };
-//# sourceMappingURL=batcher.d.cts.map

package/dist/batcher.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"batcher.js","names":["#setState","#execute","#clearTimeout","#timeoutId","#getWait"],"sources":["../src/batcher.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { parseFunctionOrValue } from './utils'\nimport { emitChange, pacerEventClient } from './event-client'\nimport type { OptionalKeys } from './types'\n\nexport interface BatcherState<TValue> {\n  /**\n   * Number of batch executions that have been completed\n   */\n  executionCount: number\n  /**\n   * Whether the batcher has no items to process (items array is empty)\n   */\n  isEmpty: boolean\n  /**\n   * Whether the batcher is waiting for the timeout to trigger batch processing\n   */\n  isPending: boolean\n  /**\n   * Array of items currently queued for batch processing\n   */\n  items: Array<TValue>\n  /**\n   * Number of items currently in the batch queue\n   */\n  size: number\n  /**\n   * Current processing status - 'idle' when not processing, 'pending' when waiting for timeout\n   */\n  status: 'idle' | 'pending'\n  /**\n   * Total number of items that have been processed across all batches\n   */\n  totalItemsProcessed: number\n}\n\nfunction getDefaultBatcherState<TValue>(): BatcherState<TValue> {\n  return {\n    executionCount: 0,\n    isEmpty: true,\n    isPending: false,\n    totalItemsProcessed: 0,\n    items: [],\n    size: 0,\n    status: 'idle',\n  }\n}\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   * Initial state for the batcher\n   */\n  initialState?: Partial<BatcherState<TValue>>\n  /**\n   * Optional key to identify this batcher instance.\n   * If provided, the batcher will be identified by this key in the devtools and PacerProvider if applicable.\n   */\n  key?: string\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?: (batch: Array<TValue>, 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 | ((batcher: Batcher<TValue>) => number)\n}\n\ntype BatcherOptionsWithOptionalCallbacks<TValue> = OptionalKeys<\n  Required<BatcherOptions<TValue>>,\n  'initialState' | 'onExecute' | 'onItemsChange' | 'key'\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 * This synchronous version is lighter weight and often all you need - upgrade to AsyncBatcher when you need promises, retry support, abort/cancel capabilities, or advanced error handling.\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 * State Management:\n * - Uses TanStack Store for reactive state management\n * - Use `initialState` to provide initial state values when creating the batcher\n * - Use `onExecute` callback to react to batch execution and implement custom logic\n * - Use `onItemsChange` callback to react to items being added or removed from the batcher\n * - The state includes batch execution count, total items processed, items, and running status\n * - State can be accessed via `batcher.store.state` when using the class directly\n * - When using framework adapters (React/Solid), state is accessed from `batcher.state`\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 *     onExecute: (batch, batcher) => console.log('Batch executed:', batch)\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.flush() // manually trigger a batch\n * ```\n */\nexport class Batcher<TValue> {\n  readonly store: Store<Readonly<BatcherState<TValue>>> = new Store(\n    getDefaultBatcherState<TValue>(),\n  )\n  key: string | undefined\n  options: BatcherOptionsWithOptionalCallbacks<TValue>\n  #timeoutId: ReturnType<typeof setTimeout> | null = null\n\n  constructor(\n    public fn: (items: Array<TValue>) => void,\n    initialOptions: BatcherOptions<TValue>,\n  ) {\n    this.key = initialOptions.key\n    this.options = {\n      ...defaultOptions,\n      ...initialOptions,\n    }\n    this.#setState(this.options.initialState ?? {})\n\n    if (this.key) {\n      pacerEventClient.on('d-Batcher', (event) => {\n        if (event.payload.key !== this.key) return\n        this.#setState(\n          event.payload.store.state as Partial<BatcherState<TValue>>,\n        )\n        this.setOptions(\n          event.payload.options as Partial<BatcherOptions<TValue>>,\n        )\n      })\n    }\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  #setState = (newState: Partial<BatcherState<TValue>>): void => {\n    this.store.setState((state) => {\n      const combinedState = {\n        ...state,\n        ...newState,\n      }\n      const { isPending, items } = combinedState\n      const size = items.length\n      const isEmpty = size === 0\n      return {\n        ...combinedState,\n        isEmpty,\n        size,\n        status: isPending ? 'pending' : 'idle',\n      }\n    })\n    emitChange('Batcher', this)\n  }\n\n  #getWait = (): number => {\n    return parseFunctionOrValue(this.options.wait, this)\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.#setState({\n      items: [...this.store.state.items, item],\n      isPending: this.options.wait !== Infinity,\n    })\n    this.options.onItemsChange?.(this)\n\n    const shouldProcess =\n      this.store.state.items.length >= this.options.maxSize ||\n      this.options.getShouldExecute(this.store.state.items, this)\n\n    if (shouldProcess) {\n      this.#execute()\n    } else if (this.options.wait !== Infinity) {\n      this.#clearTimeout() // clear any pending timeout to replace it with a new one\n      this.#timeoutId = setTimeout(() => this.#execute(), this.#getWait())\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.store.state.items.length === 0) {\n      return\n    }\n\n    const batch = this.peekAllItems() // copy of the items to be processed (to prevent race conditions)\n    this.clear() // 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) // EXECUTE\n    this.#setState({\n      executionCount: this.store.state.executionCount + 1,\n      totalItemsProcessed: this.store.state.totalItemsProcessed + batch.length,\n    })\n    this.options.onExecute?.(batch, this)\n  }\n\n  /**\n   * Processes the current batch of items immediately\n   */\n  flush = (): void => {\n    this.#clearTimeout() // clear any pending timeout\n    this.#execute() // execute immediately\n  }\n\n  /**\n   * Returns a copy of all items in the batcher\n   */\n  peekAllItems = (): Array<TValue> => {\n    return [...this.store.state.items]\n  }\n\n  #clearTimeout = (): void => {\n    if (this.#timeoutId) {\n      clearTimeout(this.#timeoutId)\n      this.#timeoutId = null\n    }\n  }\n\n  /**\n   * Removes all items from the batcher\n   */\n  clear = (): void => {\n    this.#setState({ items: [], isPending: false })\n  }\n\n  /**\n   * Cancels any pending execution that was scheduled.\n   * Does NOT clear out the items.\n   */\n  cancel = (): void => {\n    this.#clearTimeout()\n    this.#setState({ isPending: false })\n  }\n\n  /**\n   * Resets the batcher state to its default values\n   */\n  reset = (): void => {\n    this.#setState(getDefaultBatcherState<TValue>())\n    this.options.onItemsChange?.(this)\n  }\n}\n\n/**\n * Creates a batcher that processes items in batches.\n *\n * This synchronous version is lighter weight and often all you need - upgrade to asyncBatch when you need promises, retry support, abort/cancel capabilities, or advanced error handling.\n *\n * @example\n * ```ts\n * const batchItems = batch<number>(\n *   (items) => console.log('Processing:', items),\n *   {\n *     maxSize: 3,\n *     onExecute: (batch, batcher) => console.log('Batch executed:', batch)\n *   }\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\n}\n"],"mappings":"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"}

package/dist/debouncer.cjs

@@ -1,203 +0,0 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_utils = require('./utils.cjs');
-const require_event_client = require('./event-client.cjs');
-let _tanstack_store = require("@tanstack/store");
-
-//#region src/debouncer.ts
-function getDefaultDebouncerState() {
-	return {
-		canLeadingExecute: true,
-		executionCount: 0,
-		isPending: false,
-		lastArgs: void 0,
-		status: "idle",
-		maybeExecuteCount: 0
-	};
-}
-/**
-* Utility function for sharing common `DebouncerOptions` options between different `Debouncer` instances.
-*/
-function debouncerOptions(options) {
-	return options;
-}
-const defaultOptions = {
-	enabled: true,
-	leading: false,
-	trailing: true,
-	wait: 0
-};
-/**
-* A class that creates a debounced function.
-*
-* Debouncing ensures that a function is only executed after a certain amount of time has passed
-* since its last invocation. This is useful for handling frequent events like window resizing,
-* scroll events, or input changes where you want to limit the rate of execution.
-* This synchronous version is lighter weight and often all you need - upgrade to AsyncDebouncer when you need promises, retry support, abort/cancel capabilities, or advanced error handling.
-*
-* The debounced function can be configured to execute either at the start of the delay period
-* (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) => {
-*   saveToDatabase(value);
-* }, { wait: 500 });
-*
-* // Will only save after 500ms of no new input
-* inputElement.addEventListener('input', () => {
-*   debouncer.maybeExecute(inputElement.value);
-* });
-* ```
-*/
-var Debouncer = class {
-	#timeoutId;
-	constructor(fn, initialOptions) {
-		this.fn = fn;
-		this.store = new _tanstack_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"
-				};
-			});
-			require_event_client.emitChange("Debouncer", this);
-		};
-		this.#getEnabled = () => {
-			return !!require_utils.parseFunctionOrValue(this.options.enabled, this);
-		};
-		this.#getWait = () => {
-			return require_utils.parseFunctionOrValue(this.options.wait, this);
-		};
-		this.maybeExecute = (...args) => {
-			if (!this.#getEnabled()) return void 0;
-			this.#setState({ maybeExecuteCount: this.store.state.maybeExecuteCount + 1 });
-			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({
-				executionCount: this.store.state.executionCount + 1,
-				isPending: false,
-				lastArgs: void 0
-			});
-			this.options.onExecute?.(args, 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.key = initialOptions.key;
-		this.options = {
-			...defaultOptions,
-			...initialOptions
-		};
-		this.#setState(this.options.initialState ?? {});
-		if (this.key) require_event_client.pacerEventClient.on("d-Debouncer", (event) => {
-			if (event.payload.key !== this.key) return;
-			this.#setState(event.payload.store.state);
-			this.setOptions(event.payload.options);
-		});
-	}
-	#setState;
-	/**
-	* Returns the current enabled state of the debouncer
-	*/
-	#getEnabled;
-	/**
-	* Returns the current wait time in milliseconds
-	*/
-	#getWait;
-	#execute;
-	#clearTimeout;
-};
-/**
-* Creates a debounced function that delays invoking the provided function until after a specified wait time.
-* Multiple calls during the wait period will cancel previous pending invocations and reset the timer.
-*
-* This synchronous version is lighter weight and often all you need - upgrade to asyncDebounce when you need promises, retry support, abort/cancel capabilities, or advanced error handling.
-*
-* 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(() => {
-*   saveChanges();
-* }, { wait: 1000 });
-*
-* // Called repeatedly but executes at most once per second
-* inputElement.addEventListener('input', debounced);
-* ```
-*/
-function debounce(fn, initialOptions) {
-	return new Debouncer(fn, initialOptions).maybeExecute;
-}
-
-//#endregion
-exports.Debouncer = Debouncer;
-exports.debounce = debounce;
-exports.debouncerOptions = debouncerOptions;
-//# sourceMappingURL=debouncer.cjs.map

package/dist/debouncer.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"debouncer.cjs","names":["Store","#getEnabled","parseFunctionOrValue","#setState","#execute","#timeoutId","#getWait","#clearTimeout"],"sources":["../src/debouncer.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { parseFunctionOrValue } from './utils'\nimport { emitChange, pacerEventClient } from './event-client'\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   * Number of times maybeExecute has been called (for reduction calculations)\n   */\n  maybeExecuteCount: number\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 {\n    canLeadingExecute: true,\n    executionCount: 0,\n    isPending: false,\n    lastArgs: undefined,\n    status: 'idle',\n    maybeExecuteCount: 0,\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   * A key to identify the debouncer.\n   * If provided, the debouncer will be identified by this key in the devtools and PacerProvider if applicable.\n   */\n  key?: string\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?: (args: Parameters<TFn>, 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\n/**\n * Utility function for sharing common `DebouncerOptions` options between different `Debouncer` instances.\n */\nexport function debouncerOptions<\n  TFn extends AnyFunction = AnyFunction,\n  TOptions extends Partial<DebouncerOptions<TFn>> = Partial<\n    DebouncerOptions<TFn>\n  >,\n>(options: TOptions): TOptions {\n  return options\n}\n\nconst defaultOptions: Omit<\n  Required<DebouncerOptions<any>>,\n  'initialState' | 'onExecute' | 'key'\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 * This synchronous version is lighter weight and often all you need - upgrade to AsyncDebouncer when you need promises, retry support, abort/cancel capabilities, or advanced error handling.\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  key: string | undefined\n  options: DebouncerOptions<TFn>\n  #timeoutId: ReturnType<typeof setTimeout> | undefined\n\n  constructor(\n    public fn: TFn,\n    initialOptions: DebouncerOptions<TFn>,\n  ) {\n    this.key = initialOptions.key\n    this.options = {\n      ...defaultOptions,\n      ...initialOptions,\n    }\n    this.#setState(this.options.initialState ?? {})\n\n    if (this.key) {\n      pacerEventClient.on('d-Debouncer', (event) => {\n        if (event.payload.key !== this.key) return\n        this.#setState(\n          event.payload.store.state as Partial<DebouncerState<TFn>>,\n        )\n        this.setOptions(event.payload.options as Partial<DebouncerOptions<TFn>>)\n      })\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    // 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    emitChange('Debouncer', this)\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\n    this.#setState({\n      maybeExecuteCount: this.store.state.maybeExecuteCount + 1,\n    })\n\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      executionCount: this.store.state.executionCount + 1,\n      isPending: false,\n      lastArgs: undefined,\n    })\n    this.options.onExecute?.(args, 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 synchronous version is lighter weight and often all you need - upgrade to asyncDebounce when you need promises, retry support, abort/cancel capabilities, or advanced error handling.\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"],"mappings":"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"}

package/dist/debouncer.d.cts

@@ -1,167 +0,0 @@
-import { AnyFunction } from "./types.cjs";
-import { Store } from "@tanstack/store";
-
-//#region src/debouncer.d.ts
-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;
-  /**
-   * Number of times maybeExecute has been called (for reduction calculations)
-   */
-  maybeExecuteCount: number;
-  /**
-   * Current execution status - 'idle' when not active, 'pending' when waiting for timeout
-   */
-  status: 'disabled' | 'idle' | 'pending';
-}
-/**
- * Options for configuring a debounced function
- */
-interface DebouncerOptions<TFn extends AnyFunction> {
-  /**
-   * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.
-   * Can be a boolean or a function that returns a boolean.
-   * Defaults to true.
-   */
-  enabled?: boolean | ((debouncer: Debouncer<TFn>) => boolean);
-  /**
-   * Initial state for the debouncer
-   */
-  initialState?: Partial<DebouncerState<TFn>>;
-  /**
-   * A key to identify the debouncer.
-   * If provided, the debouncer will be identified by this key in the devtools and PacerProvider if applicable.
-   */
-  key?: string;
-  /**
-   * Whether to execute on the leading edge of the timeout.
-   * The first call will execute immediately and the rest will wait the delay.
-   * Defaults to false.
-   */
-  leading?: boolean;
-  /**
-   * Callback function that is called after the function is executed
-   */
-  onExecute?: (args: Parameters<TFn>, debouncer: Debouncer<TFn>) => void;
-  /**
-   * Whether to execute on the trailing edge of the timeout.
-   * Defaults to true.
-   */
-  trailing?: boolean;
-  /**
-   * Delay in milliseconds before executing the function.
-   * Can be a number or a function that returns a number.
-   * Defaults to 0ms
-   */
-  wait: number | ((debouncer: Debouncer<TFn>) => number);
-}
-/**
- * Utility function for sharing common `DebouncerOptions` options between different `Debouncer` instances.
- */
-declare function debouncerOptions<TFn extends AnyFunction = AnyFunction, TOptions extends Partial<DebouncerOptions<TFn>> = Partial<DebouncerOptions<TFn>>>(options: TOptions): TOptions;
-/**
- * A class that creates a debounced function.
- *
- * Debouncing ensures that a function is only executed after a certain amount of time has passed
- * since its last invocation. This is useful for handling frequent events like window resizing,
- * scroll events, or input changes where you want to limit the rate of execution.
- * This synchronous version is lighter weight and often all you need - upgrade to AsyncDebouncer when you need promises, retry support, abort/cancel capabilities, or advanced error handling.
- *
- * The debounced function can be configured to execute either at the start of the delay period
- * (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) => {
- *   saveToDatabase(value);
- * }, { wait: 500 });
- *
- * // Will only save after 500ms of no new input
- * inputElement.addEventListener('input', () => {
- *   debouncer.maybeExecute(inputElement.value);
- * });
- * ```
- */
-declare class Debouncer<TFn extends AnyFunction> {
-  #private;
-  fn: TFn;
-  readonly store: Store<Readonly<DebouncerState<TFn>>>;
-  key: string | undefined;
-  options: DebouncerOptions<TFn>;
-  constructor(fn: TFn, initialOptions: DebouncerOptions<TFn>);
-  /**
-   * Updates the debouncer options
-   */
-  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;
-  /**
-   * Processes the current pending execution immediately
-   */
-  flush: () => void;
-  /**
-   * Cancels any pending execution
-   */
-  cancel: () => void;
-  /**
-   * Resets the debouncer state to its default values
-   */
-  reset: () => void;
-}
-/**
- * Creates a debounced function that delays invoking the provided function until after a specified wait time.
- * Multiple calls during the wait period will cancel previous pending invocations and reset the timer.
- *
- * This synchronous version is lighter weight and often all you need - upgrade to asyncDebounce when you need promises, retry support, abort/cancel capabilities, or advanced error handling.
- *
- * 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(() => {
- *   saveChanges();
- * }, { wait: 1000 });
- *
- * // Called repeatedly but executes at most once per second
- * inputElement.addEventListener('input', debounced);
- * ```
- */
-declare function debounce<TFn extends AnyFunction>(fn: TFn, initialOptions: DebouncerOptions<TFn>): (...args: Parameters<TFn>) => void;
-//#endregion
-export { Debouncer, DebouncerOptions, DebouncerState, debounce, debouncerOptions };
-//# sourceMappingURL=debouncer.d.cts.map

package/dist/debouncer.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"debouncer.js","names":["#getEnabled","#setState","#execute","#timeoutId","#getWait","#clearTimeout"],"sources":["../src/debouncer.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { parseFunctionOrValue } from './utils'\nimport { emitChange, pacerEventClient } from './event-client'\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   * Number of times maybeExecute has been called (for reduction calculations)\n   */\n  maybeExecuteCount: number\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 {\n    canLeadingExecute: true,\n    executionCount: 0,\n    isPending: false,\n    lastArgs: undefined,\n    status: 'idle',\n    maybeExecuteCount: 0,\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   * A key to identify the debouncer.\n   * If provided, the debouncer will be identified by this key in the devtools and PacerProvider if applicable.\n   */\n  key?: string\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?: (args: Parameters<TFn>, 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\n/**\n * Utility function for sharing common `DebouncerOptions` options between different `Debouncer` instances.\n */\nexport function debouncerOptions<\n  TFn extends AnyFunction = AnyFunction,\n  TOptions extends Partial<DebouncerOptions<TFn>> = Partial<\n    DebouncerOptions<TFn>\n  >,\n>(options: TOptions): TOptions {\n  return options\n}\n\nconst defaultOptions: Omit<\n  Required<DebouncerOptions<any>>,\n  'initialState' | 'onExecute' | 'key'\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 * This synchronous version is lighter weight and often all you need - upgrade to AsyncDebouncer when you need promises, retry support, abort/cancel capabilities, or advanced error handling.\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  key: string | undefined\n  options: DebouncerOptions<TFn>\n  #timeoutId: ReturnType<typeof setTimeout> | undefined\n\n  constructor(\n    public fn: TFn,\n    initialOptions: DebouncerOptions<TFn>,\n  ) {\n    this.key = initialOptions.key\n    this.options = {\n      ...defaultOptions,\n      ...initialOptions,\n    }\n    this.#setState(this.options.initialState ?? {})\n\n    if (this.key) {\n      pacerEventClient.on('d-Debouncer', (event) => {\n        if (event.payload.key !== this.key) return\n        this.#setState(\n          event.payload.store.state as Partial<DebouncerState<TFn>>,\n        )\n        this.setOptions(event.payload.options as Partial<DebouncerOptions<TFn>>)\n      })\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    // 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    emitChange('Debouncer', this)\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\n    this.#setState({\n      maybeExecuteCount: this.store.state.maybeExecuteCount + 1,\n    })\n\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      executionCount: this.store.state.executionCount + 1,\n      isPending: false,\n      lastArgs: undefined,\n    })\n    this.options.onExecute?.(args, 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 synchronous version is lighter weight and often all you need - upgrade to asyncDebounce when you need promises, retry support, abort/cancel capabilities, or advanced error handling.\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"],"mappings":"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"}