@tanstack/solid-pacer 0.21.1 → 0.23.0

package/src/batcher/createBatcher.ts

@@ -1,199 +0,0 @@
-import { Batcher } from '@tanstack/pacer/batcher'
-import { shallow, useSelector } from '@tanstack/solid-store'
-import { createEffect, onCleanup } from 'solid-js'
-import { useDefaultPacerOptions } from '../provider/PacerProvider'
-import type { Store } from '@tanstack/solid-store'
-import type { Accessor, JSX } from 'solid-js'
-import type { BatcherOptions, BatcherState } from '@tanstack/pacer/batcher'
-
-export interface SolidBatcherOptions<
-  TValue,
-  TSelected = {},
-> extends BatcherOptions<TValue> {
-  /**
-   * Optional callback invoked when the owning component unmounts. Receives the batcher instance.
-   * When provided, replaces the default cleanup (cancel); use it to call flush(), reset(), cancel(), add logging, etc.
-   */
-  onUnmount?: (batcher: SolidBatcher<TValue, TSelected>) => void
-}
-
-export interface SolidBatcher<TValue, TSelected = {}> extends Omit<
-  Batcher<TValue>,
-  'store'
-> {
-  /**
-   * A Solid component that allows you to subscribe to the batcher state.
-   *
-   * This is useful for tracking specific parts of the batcher state
-   * deep in your component tree without needing to pass a selector to the hook.
-   *
-   * @example
-   * <batcher.Subscribe selector={(state) => ({ size: state.size, isRunning: state.isRunning })}>
-   *   {(state) => (
-   *     <div>Batch: {state().size} items, {state().isRunning ? 'Processing' : 'Idle'}</div>
-   *   )}
-   * </batcher.Subscribe>
-   */
-  Subscribe: <TSelected>(props: {
-    selector: (state: BatcherState<TValue>) => TSelected
-    children: ((state: Accessor<TSelected>) => JSX.Element) | JSX.Element
-  }) => JSX.Element
-  /**
-   * Reactive state that will be updated when the batcher state changes
-   *
-   * Use this instead of `batcher.store.state`
-   */
-  readonly state: Accessor<Readonly<TSelected>>
-  /**
-   * @deprecated Use `batcher.state` instead of `batcher.store.state` if you want to read reactive state.
-   * The state on the store object is not reactive, as it has not been wrapped in a `useSelector` hook internally.
-   * Although, you can make the state reactive by using the `useSelector` in your own usage.
-   */
-  readonly store: Store<Readonly<BatcherState<TValue>>>
-}
-
-/**
- * Creates a Solid-compatible Batcher instance for managing batches of items, exposing Solid signals for all stateful properties.
- *
- * Features:
- * - Batch processing of items using the provided `fn` function
- * - Configurable batch size and wait time
- * - Custom batch processing logic via getShouldExecute
- * - Event callbacks for monitoring batch operations
- * - All stateful properties (items, counts, etc.) are exposed as Solid signals for reactivity
- *
- * The batcher collects items and processes them in batches based on:
- * - Maximum batch size
- * - Time-based batching (process after X milliseconds)
- * - Custom batch processing logic via getShouldExecute
- *
- * ## State Management and Selector
- *
- * The hook uses TanStack Store for reactive state management. You can subscribe to state changes
- * in two ways:
- *
- * **1. Using `batcher.Subscribe` component (Recommended for component tree subscriptions)**
- *
- * Use the `Subscribe` component to subscribe to state changes deep in your component tree without
- * needing to pass a selector to the hook. This is ideal when you want to subscribe to state
- * in child components.
- *
- * **2. Using the `selector` parameter (For hook-level subscriptions)**
- *
- * The `selector` parameter allows you to specify which state changes will trigger reactive updates
- * at the hook level, optimizing performance by preventing unnecessary updates when irrelevant
- * state changes occur.
- *
- * **By default, there will be no reactive state subscriptions** and you must opt-in to state
- * tracking by providing a selector function or using the `Subscribe` component. This prevents unnecessary
- * updates and gives you full control over when your component tracks state changes.
- *
- * Available state properties:
- * - `executionCount`: Number of batch executions that have been completed
- * - `isRunning`: Whether the batcher is currently running (not stopped)
- * - `items`: Array of items currently queued for batching
- * - `totalItemsProcessed`: Total number of individual items that have been processed across all batches
- *
- * ## Unmount behavior
- *
- * By default, the primitive cancels any pending batch when the owning component unmounts.
- * Use the `onUnmount` option to customize this. For example, to flush pending work instead:
- *
- * ```tsx
- * const batcher = createBatcher(fn, {
- *   maxSize: 10,
- *   wait: 2000,
- *   onUnmount: (b) => b.flush()
- * });
- * ```
- *
- * Example usage:
- * ```tsx
- * // Default behavior - no reactive state subscriptions
- * const batcher = createBatcher(
- *   (items) => {
- *     // Process batch of items
- *     console.log('Processing batch:', items);
- *   },
- *   {
- *     maxSize: 5,
- *     wait: 2000,
- *     onExecute: (batcher) => console.log('Batch executed'),
- *     getShouldExecute: (items) => items.length >= 3
- *   }
- * );
- *
- * // Opt-in to track items or isRunning changes (optimized for UI updates)
- * const batcher = createBatcher(
- *   (items) => console.log('Processing batch:', items),
- *   { maxSize: 5, wait: 2000 },
- *   (state) => ({ items: state.items, isRunning: state.isRunning })
- * );
- *
- * // Opt-in to track execution metrics changes (optimized for tracking progress)
- * const batcher = createBatcher(
- *   (items) => console.log('Processing batch:', items),
- *   { maxSize: 5, wait: 2000 },
- *   (state) => ({
- *     executionCount: state.executionCount,
- *     totalItemsProcessed: state.totalItemsProcessed
- *   })
- * );
- *
- * // Add items to batch
- * batcher.addItem('task1');
- * batcher.addItem('task2');
- *
- * // Control the batcher
- * batcher.stop();  // Pause processing
- * batcher.start(); // Resume processing
- *
- * // Access the selected state (will be empty object {} unless selector provided)
- * const { items, isRunning } = batcher.state();
- * ```
- */
-export function createBatcher<TValue, TSelected = {}>(
-  fn: (items: Array<TValue>) => void,
-  options: SolidBatcherOptions<TValue, TSelected> = {},
-  selector: (state: BatcherState<TValue>) => TSelected = () =>
-    ({}) as TSelected,
-): SolidBatcher<TValue, TSelected> {
-  const mergedOptions = {
-    ...useDefaultPacerOptions().batcher,
-    ...options,
-  } as SolidBatcherOptions<TValue, TSelected>
-  const batcher = new Batcher(fn, mergedOptions) as unknown as SolidBatcher<
-    TValue,
-    TSelected
-  >
-
-  batcher.Subscribe = function Subscribe<TSelected>(props: {
-    selector: (state: BatcherState<TValue>) => TSelected
-    children: ((state: Accessor<TSelected>) => JSX.Element) | JSX.Element
-  }) {
-    const selected = useSelector(batcher.store, props.selector, {
-      compare: shallow,
-    })
-
-    return typeof props.children === 'function'
-      ? props.children(selected)
-      : props.children
-  }
-
-  const state = useSelector(batcher.store, selector, { compare: shallow })
-
-  createEffect(() => {
-    onCleanup(() => {
-      if (mergedOptions.onUnmount) {
-        mergedOptions.onUnmount(batcher)
-      } else {
-        batcher.cancel()
-      }
-    })
-  })
-
-  return {
-    ...batcher,
-    state,
-  } as SolidBatcher<TValue, TSelected>
-}

package/src/batcher/index.ts

@@ -1,3 +0,0 @@
-export * from '@tanstack/pacer/batcher'
-
-export * from './createBatcher'

package/src/debouncer/createDebouncedSignal.ts

@@ -1,92 +0,0 @@
-import { createSignal } from 'solid-js'
-import { createDebouncer } from './createDebouncer'
-import type { SolidDebouncer, SolidDebouncerOptions } from './createDebouncer'
-import type { Accessor, Setter } from 'solid-js'
-import type { DebouncerState } from '@tanstack/pacer/debouncer'
-
-/**
- * A Solid hook that creates a debounced state value, combining Solid's createSignal with debouncing functionality.
- * This hook provides both the current debounced value and methods to update it.
- *
- * The state value is only updated after the specified wait time has elapsed since the last update attempt.
- * If another update is attempted before the wait time expires, the timer resets and starts waiting again.
- * This is useful for handling frequent state updates that should be throttled, like search input values
- * or window resize dimensions.
- *
- * The hook returns a tuple containing:
- * - The current debounced value accessor
- * - A function to update the debounced value
- * - The debouncer instance with additional control methods and state signals
- *
- * ## State Management and Selector
- *
- * The hook uses TanStack Store for reactive state management via the underlying debouncer instance.
- * The `selector` parameter allows you to specify which debouncer state changes will trigger reactive updates,
- * optimizing performance by preventing unnecessary subscriptions when irrelevant state changes occur.
- *
- * **By default, there will be no reactive state subscriptions** and you must opt-in to state
- * tracking by providing a selector function. This prevents unnecessary reactive updates and gives you
- * full control over when your component subscribes to state changes. Only when you provide a selector will
- * the reactive system track the selected state values.
- *
- * Available debouncer state properties:
- * - `canLeadingExecute`: Whether the debouncer can execute on the leading edge
- * - `executionCount`: Number of function executions that have been completed
- * - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution
- * - `lastArgs`: The arguments from the most recent call to maybeExecute
- * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
- *
- * @example
- * ```tsx
- * // Default behavior - no reactive state subscriptions
- * const [searchTerm, setSearchTerm, debouncer] = createDebouncedSignal('', {
- *   wait: 500 // Wait 500ms after last keystroke
- * });
- *
- * // Opt-in to reactive updates when pending state changes (optimized for loading indicators)
- * const [searchTerm, setSearchTerm, debouncer] = createDebouncedSignal(
- *   '',
- *   { wait: 500 },
- *   (state) => ({ isPending: state.isPending })
- * );
- *
- * // Opt-in to reactive updates when execution count changes (optimized for tracking executions)
- * const [searchTerm, setSearchTerm, debouncer] = createDebouncedSignal(
- *   '',
- *   { wait: 500 },
- *   (state) => ({ executionCount: state.executionCount })
- * );
- *
- * // Update value - will be debounced
- * const handleChange = (e) => {
- *   setSearchTerm(e.target.value);
- * };
- *
- * // Access debouncer state via signals
- * console.log('Executions:', debouncer.state().executionCount);
- * console.log('Is pending:', debouncer.state().isPending);
- *
- * // In onExecute callback, use get* methods
- * const [searchTerm, setSearchTerm, debouncer] = createDebouncedSignal('', {
- *   wait: 500,
- *   onExecute: (debouncer) => {
- *     console.log('Total executions:', debouncer.getExecutionCount());
- *   }
- * });
- * ```
- */
-export function createDebouncedSignal<TValue, TSelected = {}>(
-  value: TValue,
-  initialOptions: SolidDebouncerOptions<Setter<TValue>, TSelected>,
-  selector?: (state: DebouncerState<Setter<TValue>>) => TSelected,
-): [
-  Accessor<TValue>,
-  Setter<TValue>,
-  SolidDebouncer<Setter<TValue>, TSelected>,
-] {
-  const [debouncedValue, setDebouncedValue] = createSignal<TValue>(value)
-
-  const debouncer = createDebouncer(setDebouncedValue, initialOptions, selector)
-
-  return [debouncedValue, debouncer.maybeExecute as Setter<TValue>, debouncer]
-}

package/src/debouncer/createDebouncedValue.ts

@@ -1,85 +0,0 @@
-import { createEffect } from 'solid-js'
-import { createDebouncedSignal } from './createDebouncedSignal'
-import type { SolidDebouncer, SolidDebouncerOptions } from './createDebouncer'
-import type { Accessor, Setter } from 'solid-js'
-import type { DebouncerState } from '@tanstack/pacer/debouncer'
-
-/**
- * A Solid hook that creates a debounced value that updates only after a specified delay.
- * Unlike createDebouncedSignal, this hook automatically tracks changes to the input value
- * and updates the debounced value accordingly.
- *
- * The debounced value will only update after the specified wait time has elapsed since
- * the last change to the input value. If the input value changes again before the wait
- * time expires, the timer resets and starts waiting again.
- *
- * This is useful for deriving debounced values from props or state that change frequently,
- * like search queries or form inputs, where you want to limit how often downstream effects
- * or calculations occur.
- *
- * The hook returns a tuple containing:
- * - An Accessor that provides the current debounced value
- * - The debouncer instance with control methods
- *
- * ## State Management and Selector
- *
- * The hook uses TanStack Store for reactive state management via the underlying debouncer instance.
- * The `selector` parameter allows you to specify which debouncer state changes will trigger reactive updates,
- * optimizing performance by preventing unnecessary subscriptions when irrelevant state changes occur.
- *
- * **By default, there will be no reactive state subscriptions** and you must opt-in to state
- * tracking by providing a selector function. This prevents unnecessary reactive updates and gives you
- * full control over when your component subscribes to state changes. Only when you provide a selector will
- * the reactive system track the selected state values.
- *
- * Available debouncer state properties:
- * - `canLeadingExecute`: Whether the debouncer can execute on the leading edge
- * - `executionCount`: Number of function executions that have been completed
- * - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution
- * - `lastArgs`: The arguments from the most recent call to maybeExecute
- * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
- *
- * @example
- * ```tsx
- * // Default behavior - no reactive state subscriptions
- * const [searchQuery, setSearchQuery] = createSignal('');
- * const [debouncedQuery, debouncer] = createDebouncedValue(searchQuery, {
- *   wait: 500 // Wait 500ms after last change
- * });
- *
- * // Opt-in to reactive updates when pending state changes (optimized for loading indicators)
- * const [debouncedQuery, debouncer] = createDebouncedValue(
- *   searchQuery,
- *   { wait: 500 },
- *   (state) => ({ isPending: state.isPending })
- * );
- *
- * // debouncedQuery will update 500ms after searchQuery stops changing
- * createEffect(() => {
- *   fetchSearchResults(debouncedQuery());
- * });
- *
- * // Access debouncer state via signals
- * console.log('Is pending:', debouncer.state().isPending);
- *
- * // Control the debouncer
- * debouncer.cancel(); // Cancel any pending updates
- * ```
- */
-export function createDebouncedValue<TValue, TSelected = {}>(
-  value: Accessor<TValue>,
-  initialOptions: SolidDebouncerOptions<Setter<TValue>, TSelected>,
-  selector?: (state: DebouncerState<Setter<TValue>>) => TSelected,
-): [Accessor<TValue>, SolidDebouncer<Setter<TValue>, TSelected>] {
-  const [debouncedValue, setDebouncedValue, debouncer] = createDebouncedSignal(
-    value(),
-    initialOptions,
-    selector,
-  )
-
-  createEffect(() => {
-    setDebouncedValue(value() as any)
-  })
-
-  return [debouncedValue, debouncer]
-}

package/src/debouncer/createDebouncer.ts

@@ -1,201 +0,0 @@
-import { Debouncer } from '@tanstack/pacer/debouncer'
-import { createEffect, onCleanup } from 'solid-js'
-import { shallow, useSelector } from '@tanstack/solid-store'
-import { useDefaultPacerOptions } from '../provider/PacerProvider'
-import type { Store } from '@tanstack/solid-store'
-import type { Accessor, JSX } from 'solid-js'
-import type { AnyFunction } from '@tanstack/pacer/types'
-import type {
-  DebouncerOptions,
-  DebouncerState,
-} from '@tanstack/pacer/debouncer'
-
-export interface SolidDebouncerOptions<
-  TFn extends AnyFunction,
-  TSelected = {},
-> extends DebouncerOptions<TFn> {
-  /**
-   * Optional callback invoked when the owning component unmounts. Receives the debouncer instance.
-   * When provided, replaces the default cleanup (cancel); use it to call flush(), reset(), cancel(), add logging, etc.
-   */
-  onUnmount?: (debouncer: SolidDebouncer<TFn, TSelected>) => void
-}
-
-export interface SolidDebouncer<
-  TFn extends AnyFunction,
-  TSelected = {},
-> extends Omit<Debouncer<TFn>, 'store'> {
-  /**
-   * A Solid component that allows you to subscribe to the debouncer state.
-   *
-   * This is useful for tracking specific parts of the debouncer state
-   * deep in your component tree without needing to pass a selector to the hook.
-   *
-   * @example
-   * <debouncer.Subscribe selector={(state) => ({ isPending: state.isPending })}>
-   *   {(state) => (
-   *     <div>{state().isPending ? 'Waiting...' : 'Ready'}</div>
-   *   )}
-   * </debouncer.Subscribe>
-   */
-  Subscribe: <TSelected>(props: {
-    selector: (state: DebouncerState<TFn>) => TSelected
-    children: ((state: Accessor<TSelected>) => JSX.Element) | JSX.Element
-  }) => JSX.Element
-  /**
-   * Reactive state that will be updated when the debouncer state changes
-   *
-   * Use this instead of `debouncer.store.state`
-   */
-  readonly state: Accessor<Readonly<TSelected>>
-  /**
-   * @deprecated Use `debouncer.state` instead of `debouncer.store.state` if you want to read reactive state.
-   * The state on the store object is not reactive, as it has not been wrapped in a `useSelector` hook internally.
-   * Although, you can make the state reactive by using the `useSelector` in your own usage.
-   */
-  readonly store: Store<Readonly<DebouncerState<TFn>>>
-}
-
-/**
- * A Solid hook that creates and manages a Debouncer instance.
- *
- * This is a lower-level hook that provides direct access to the Debouncer's functionality without
- * any built-in state management. This allows you to integrate it with any state management solution
- * you prefer (createSignal, Redux, Zustand, etc.).
- *
- * This hook provides debouncing functionality to limit how often a function can be called,
- * waiting for a specified delay before executing the latest call. This is useful for handling
- * frequent events like window resizing, scroll events, or real-time search inputs.
- *
- * The debouncer will only execute the function after the specified wait time has elapsed
- * since the last call. If the function is called again before the wait time expires, the
- * timer resets and starts waiting again.
- *
- * ## State Management and Selector
- *
- * The hook uses TanStack Store for reactive state management. You can subscribe to state changes
- * in two ways:
- *
- * **1. Using `debouncer.Subscribe` component (Recommended for component tree subscriptions)**
- *
- * Use the `Subscribe` component to subscribe to state changes deep in your component tree without
- * needing to pass a selector to the hook. This is ideal when you want to subscribe to state
- * in child components.
- *
- * **2. Using the `selector` parameter (For hook-level subscriptions)**
- *
- * The `selector` parameter allows you to specify which state changes will trigger reactive updates
- * at the hook level, optimizing performance by preventing unnecessary updates when irrelevant
- * state changes occur.
- *
- * **By default, there will be no reactive state subscriptions** and you must opt-in to state
- * tracking by providing a selector function or using the `Subscribe` component. This prevents unnecessary
- * updates and gives you full control over when your component tracks state changes.
- *
- * Available state properties:
- * - `canLeadingExecute`: Whether the debouncer can execute on the leading edge
- * - `executionCount`: Number of function executions that have been completed
- * - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution
- * - `lastArgs`: The arguments from the most recent call to maybeExecute
- * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
- *
- * ## Unmount behavior
- *
- * By default, the primitive cancels any pending execution when the owning component unmounts.
- * Use the `onUnmount` option to customize this. For example, to flush pending work instead:
- *
- * ```tsx
- * const debouncer = createDebouncer(fn, {
- *   wait: 500,
- *   onUnmount: (d) => d.flush()
- * });
- * ```
- *
- * @example
- * ```tsx
- * // Default behavior - no reactive state subscriptions
- * const debouncer = createDebouncer(
- *   (query: string) => fetchSearchResults(query),
- *   { wait: 500 }
- * );
- *
- * // Opt-in to track isPending changes (optimized for loading states)
- * const debouncer = createDebouncer(
- *   (query: string) => fetchSearchResults(query),
- *   { wait: 500 },
- *   (state) => ({ isPending: state.isPending })
- * );
- *
- * // Opt-in to track executionCount changes (optimized for tracking execution)
- * const debouncer = createDebouncer(
- *   (query: string) => fetchSearchResults(query),
- *   { wait: 500 },
- *   (state) => ({ executionCount: state.executionCount })
- * );
- *
- * // Multiple state properties - track when any of these change
- * const debouncer = createDebouncer(
- *   (query: string) => fetchSearchResults(query),
- *   { wait: 500 },
- *   (state) => ({
- *     isPending: state.isPending,
- *     executionCount: state.executionCount,
- *     status: state.status
- *   })
- * );
- *
- * // In an event handler
- * const handleChange = (e) => {
- *   debouncer.maybeExecute(e.target.value);
- * };
- *
- * // Access the selected state (will be empty object {} unless selector provided)
- * const { isPending } = debouncer.state();
- * ```
- */
-export function createDebouncer<TFn extends AnyFunction, TSelected = {}>(
-  fn: TFn,
-  options: SolidDebouncerOptions<TFn, TSelected>,
-  selector: (state: DebouncerState<TFn>) => TSelected = () => ({}) as TSelected,
-): SolidDebouncer<TFn, TSelected> {
-  const mergedOptions = {
-    ...useDefaultPacerOptions().debouncer,
-    ...options,
-  } as SolidDebouncerOptions<TFn, TSelected>
-  const asyncDebouncer = new Debouncer<TFn>(
-    fn,
-    mergedOptions,
-  ) as unknown as SolidDebouncer<TFn, TSelected>
-
-  asyncDebouncer.Subscribe = function Subscribe<TSelected>(props: {
-    selector: (state: DebouncerState<TFn>) => TSelected
-    children: ((state: Accessor<TSelected>) => JSX.Element) | JSX.Element
-  }) {
-    const selected = useSelector(asyncDebouncer.store, props.selector, {
-      compare: shallow,
-    })
-
-    return typeof props.children === 'function'
-      ? props.children(selected)
-      : props.children
-  }
-
-  const state = useSelector(asyncDebouncer.store, selector, {
-    compare: shallow,
-  })
-
-  createEffect(() => {
-    onCleanup(() => {
-      if (mergedOptions.onUnmount) {
-        mergedOptions.onUnmount(asyncDebouncer)
-      } else {
-        asyncDebouncer.cancel()
-      }
-    })
-  })
-
-  return {
-    ...asyncDebouncer,
-    state,
-  } as SolidDebouncer<TFn, TSelected> // omit `store` in favor of `state`
-}

package/src/debouncer/index.ts

@@ -1,6 +0,0 @@
-// re-export everything from the core pacer package, BUT ONLY from the debouncer module
-export * from '@tanstack/pacer/debouncer'
-
-export * from './createDebouncedSignal'
-export * from './createDebouncedValue'
-export * from './createDebouncer'

package/src/index.ts

@@ -1,46 +0,0 @@
-// re-export everything from the core pacer package
-export * from '@tanstack/pacer'
-
-// provider
-export * from './provider/PacerProvider'
-
-/**
- * Export every hook individually - DON'T export from barrel files
- */
-
-// async-batcher
-export * from './async-batcher/createAsyncBatcher'
-
-// async-debouncer
-export * from './async-debouncer/createAsyncDebouncer'
-
-// async-queuer
-export * from './async-queuer/createAsyncQueuer'
-
-// async-rate-limiter
-export * from './async-rate-limiter/createAsyncRateLimiter'
-
-// async-throttler
-export * from './async-throttler/createAsyncThrottler'
-
-// batcher
-export * from './batcher/createBatcher'
-
-// debouncer
-export * from './debouncer/createDebouncedSignal'
-export * from './debouncer/createDebouncedValue'
-export * from './debouncer/createDebouncer'
-
-// queuer
-export * from './queuer/createQueuer'
-export * from './queuer/createQueuedSignal'
-
-// rate-limiter
-export * from './rate-limiter/createRateLimiter'
-export * from './rate-limiter/createRateLimitedSignal'
-export * from './rate-limiter/createRateLimitedValue'
-
-// throttler
-export * from './throttler/createThrottledSignal'
-export * from './throttler/createThrottledValue'
-export * from './throttler/createThrottler'