@tanstack/pacer-lite 0.2.1 → 0.3.0

package/src/lite-batcher.ts

@@ -1,267 +0,0 @@
-/**
- * Options for configuring a lite batcher instance
- */
-export interface LiteBatcherOptions<TValue> {
-  /**
-   * Custom function to determine if a batch should be processed
-   * Return true to process the batch immediately
-   */
-  getShouldExecute?: (
-    items: Array<TValue>,
-    batcher: LiteBatcher<TValue>,
-  ) => boolean
-  /**
-   * Maximum number of items in a batch
-   * @default Infinity
-   */
-  maxSize?: number
-  /**
-   * Callback fired after a batch is processed
-   */
-  onExecute?: (batch: Array<TValue>, batcher: LiteBatcher<TValue>) => void
-  /**
-   * Callback fired after items are added to the batcher
-   */
-  onItemsChange?: (batcher: LiteBatcher<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: LiteBatcher<TValue>) => number)
-}
-
-/**
- * A lightweight class that collects items and processes them in batches.
- *
- * This is an alternative to the Batcher in the core @tanstack/pacer package, but is more
- * suitable for libraries and npm packages that need minimal overhead. Unlike the core Batcher,
- * this version does not use TanStack Store for state management, has no devtools integration,
- * no callbacks, and provides only essential batching functionality.
- *
- * 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.
- *
- * 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
- *
- * Features included:
- * - Core batching functionality (addItem, flush, clear, cancel)
- * - Size-based batching (maxSize)
- * - Time-based batching (wait timeout)
- * - Custom condition batching (getShouldExecute)
- * - Manual processing controls
- * - Public mutable options
- * - Callback support for monitoring batch execution and state changes
- *
- * Features NOT included (compared to core Batcher):
- * - No TanStack Store state management
- * - No devtools integration
- * - No complex state tracking (execution counts, etc.)
- * - No reactive state management
- *
- * @example
- * ```ts
- * // Basic batching
- * const batcher = new LiteBatcher<number>(
- *   (items) => console.log('Processing batch:', items),
- *   {
- *     maxSize: 5,
- *     wait: 2000,
- *     onExecute: (batch, batcher) => {
- *       console.log('Batch executed with', batch.length, 'items');
- *     },
- *     onItemsChange: (batcher) => {
- *       console.log('Batch size changed to:', batcher.size);
- *     }
- *   }
- * );
- *
- * batcher.addItem(1);
- * batcher.addItem(2);
- * // After 2 seconds or when 5 items are added, whichever comes first,
- * // the batch will be processed
- * ```
- *
- * @example
- * ```ts
- * // Custom condition batching
- * const batcher = new LiteBatcher<Task>(
- *   (items) => processTasks(items),
- *   {
- *     getShouldExecute: (items) => items.some(task => task.urgent),
- *     maxSize: 10,
- *   }
- * );
- *
- * batcher.addItem({ name: 'normal', urgent: false });
- * batcher.addItem({ name: 'urgent', urgent: true }); // Triggers immediate processing
- * ```
- */
-export class LiteBatcher<TValue> {
-  private items: Array<TValue> = []
-  private timeoutId: NodeJS.Timeout | null = null
-  private _isPending = false
-
-  constructor(
-    public fn: (items: Array<TValue>) => void,
-    public options: LiteBatcherOptions<TValue> = {},
-  ) {
-    // Set defaults
-    this.options.maxSize = this.options.maxSize ?? Infinity
-    this.options.started = this.options.started ?? true
-    this.options.wait = this.options.wait ?? Infinity
-    this.options.getShouldExecute =
-      this.options.getShouldExecute ?? (() => false)
-  }
-
-  /**
-   * Number of items currently in the batch
-   */
-  get size(): number {
-    return this.items.length
-  }
-
-  /**
-   * Whether the batch has no items to process (items array is empty)
-   */
-  get isEmpty(): boolean {
-    return this.items.length === 0
-  }
-
-  /**
-   * Whether the batcher is waiting for the timeout to trigger batch processing
-   */
-  get isPending(): boolean {
-    return this._isPending
-  }
-
-  private getWait(): number {
-    if (typeof this.options.wait === 'function') {
-      return this.options.wait(this)
-    }
-    return this.options.wait!
-  }
-
-  /**
-   * Adds an item to the batcher
-   * If the batch size is reached, timeout occurs, or getShouldExecute returns true, the batch will be processed
-   */
-  addItem = (item: TValue): void => {
-    this.items.push(item)
-    this._isPending = this.options.wait !== Infinity
-    this.options.onItemsChange?.(this)
-
-    const shouldProcess =
-      this.items.length >= this.options.maxSize! ||
-      this.options.getShouldExecute!(this.items, this)
-
-    if (shouldProcess) {
-      this.execute()
-    } else if (this.options.wait !== Infinity) {
-      this.clearTimeout() // clear any pending timeout to replace it with a new one
-      this.timeoutId = setTimeout(() => this.execute(), this.getWait())
-    }
-  }
-
-  /**
-   * 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 maxSize
-   * - 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.
-   */
-  private execute = (): void => {
-    if (this.items.length === 0) {
-      return
-    }
-
-    const batch = this.peekAllItems() // copy of the items to be processed (to prevent race conditions)
-    this.clear() // Clear items before processing to prevent race conditions
-
-    this.fn(batch) // EXECUTE
-    this.options.onExecute?.(batch, this)
-  }
-
-  /**
-   * Processes the current batch of items immediately
-   */
-  flush = (): void => {
-    this.clearTimeout() // clear any pending timeout
-    this.execute() // execute immediately
-  }
-
-  /**
-   * Returns a copy of all items in the batcher
-   */
-  peekAllItems = (): Array<TValue> => {
-    return [...this.items]
-  }
-
-  private clearTimeout = (): void => {
-    if (this.timeoutId) {
-      clearTimeout(this.timeoutId)
-      this.timeoutId = null
-    }
-  }
-
-  /**
-   * Removes all items from the batcher
-   */
-  clear = (): void => {
-    const hadItems = this.items.length > 0
-    this.items = []
-    this._isPending = false
-    if (hadItems) {
-      this.options.onItemsChange?.(this)
-    }
-  }
-
-  /**
-   * Cancels any pending execution that was scheduled.
-   * Does NOT clear out the items.
-   */
-  cancel = (): void => {
-    this.clearTimeout()
-    this._isPending = false
-  }
-}
-
-/**
- * Creates a batcher that processes items in batches.
- *
- * This is an alternative to the batch function in the core @tanstack/pacer package, but is more
- * suitable for libraries and npm packages that need minimal overhead. Unlike the core version,
- * this function creates a batcher with no external dependencies, devtools integration, or reactive state.
- *
- * @example
- * ```ts
- * const batchItems = liteBatch<number>(
- *   (items) => console.log('Processing:', items),
- *   {
- *     maxSize: 3,
- *   }
- * );
- *
- * batchItems(1);
- * batchItems(2);
- * batchItems(3); // Triggers batch processing
- * ```
- */
-export function liteBatch<TValue>(
-  fn: (items: Array<TValue>) => void,
-  options: LiteBatcherOptions<TValue> = {},
-): (item: TValue) => void {
-  const batcher = new LiteBatcher<TValue>(fn, options)
-  return batcher.addItem
-}

package/src/lite-debouncer.ts

@@ -1,184 +0,0 @@
-import type { AnyFunction } from '@tanstack/pacer/types'
-
-/**
- * Options for configuring a lite debounced function
- */
-export interface LiteDebouncerOptions<TFn extends AnyFunction = AnyFunction> {
-  /**
-   * 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: LiteDebouncer<TFn>) => void
-  /**
-   * Whether to execute on the trailing edge of the timeout.
-   * Defaults to true.
-   */
-  trailing?: boolean
-  /**
-   * Delay in milliseconds before executing the function.
-   */
-  wait: number
-}
-
-/**
- * A lightweight class that creates a debounced function.
- *
- * This is an alternative to the Debouncer in the core @tanstack/pacer package, but is more
- * suitable for libraries and npm packages that need minimal overhead. Unlike the core Debouncer,
- * this version does not use TanStack Store for state management, has no devtools integration,
- * and provides only essential debouncing functionality.
- *
- * 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.
- *
- * 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.
- *
- * Features:
- * - Zero dependencies - no external libraries required
- * - Minimal API surface - only essential methods (maybeExecute, flush, cancel)
- * - Simple state management - uses basic private properties instead of reactive stores
- * - Callback support for monitoring execution events
- * - Lightweight - designed for use in npm packages where bundle size matters
- *
- * @example
- * ```ts
- * const debouncer = new LiteDebouncer((value: string) => {
- *   saveToDatabase(value);
- * }, {
- *   wait: 500,
- *   onExecute: (args, debouncer) => {
- *     console.log('Saved value:', args[0]);
- *   }
- * });
- *
- * // Will only save after 500ms of no new input
- * inputElement.addEventListener('input', () => {
- *   debouncer.maybeExecute(inputElement.value);
- * });
- * ```
- */
-export class LiteDebouncer<TFn extends AnyFunction> {
-  private timeoutId: NodeJS.Timeout | undefined
-  private lastArgs: Parameters<TFn> | undefined
-  private canLeadingExecute = true
-
-  constructor(
-    public fn: TFn,
-    public options: LiteDebouncerOptions<TFn>,
-  ) {
-    // Default trailing to true if neither leading nor trailing is specified
-    if (
-      this.options.leading === undefined &&
-      this.options.trailing === undefined
-    ) {
-      this.options.trailing = true
-    }
-  }
-
-  /**
-   * Attempts to execute the debounced function.
-   * If leading is true and this is the first call, executes immediately.
-   * Otherwise, queues the execution for after the wait time.
-   * Each new call resets the timer.
-   */
-  maybeExecute = (...args: Parameters<TFn>): void => {
-    let didLeadingExecute = false
-
-    if (this.options.leading && this.canLeadingExecute) {
-      this.canLeadingExecute = false
-      didLeadingExecute = true
-      this.fn(...args)
-      this.options.onExecute?.(args, this)
-    }
-
-    this.lastArgs = args
-
-    if (this.timeoutId) {
-      clearTimeout(this.timeoutId)
-    }
-
-    this.timeoutId = setTimeout(() => {
-      this.canLeadingExecute = true
-      if (this.options.trailing && !didLeadingExecute && this.lastArgs) {
-        this.fn(...this.lastArgs)
-        this.options.onExecute?.(this.lastArgs, this)
-      }
-      this.lastArgs = undefined
-    }, this.options.wait)
-  }
-
-  /**
-   * Processes the current pending execution immediately.
-   * If there's a pending execution, it will be executed right away
-   * and the timeout will be cleared.
-   */
-  flush = (): void => {
-    if (this.timeoutId && this.lastArgs) {
-      clearTimeout(this.timeoutId)
-      this.timeoutId = undefined
-      const args = this.lastArgs
-      this.fn(...args)
-      this.options.onExecute?.(args, this)
-      this.lastArgs = undefined
-      this.canLeadingExecute = true
-    }
-  }
-
-  /**
-   * Cancels any pending execution.
-   * Clears the timeout and resets the internal state.
-   */
-  cancel = (): void => {
-    if (this.timeoutId) {
-      clearTimeout(this.timeoutId)
-      this.timeoutId = undefined
-    }
-    this.lastArgs = undefined
-    this.canLeadingExecute = true
-  }
-}
-
-/**
- * Creates a lightweight 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 is an alternative to the debounce function in the core @tanstack/pacer package, but is more
- * suitable for libraries and npm packages that need minimal overhead. Unlike the core version,
- * this function creates a debouncer with no external dependencies, devtools integration, or reactive state.
- *
- * If leading option is true, the function will execute immediately on the first call, then wait the delay
- * before allowing another execution.
- *
- * @example
- * ```ts
- * const debouncedSave = liteDebounce(() => {
- *   saveChanges();
- * }, { wait: 1000 });
- *
- * // Called repeatedly but executes at most once per second
- * inputElement.addEventListener('input', debouncedSave);
- * ```
- *
- * @example
- * ```ts
- * // Leading edge execution - fires immediately then waits
- * const debouncedSearch = liteDebounce((query: string) => {
- *   performSearch(query);
- * }, { wait: 300, leading: true });
- * ```
- */
-export function liteDebounce<TFn extends AnyFunction>(
-  fn: TFn,
-  options: LiteDebouncerOptions<TFn>,
-): (...args: Parameters<TFn>) => void {
-  const debouncer = new LiteDebouncer(fn, options)
-  return debouncer.maybeExecute
-}