@tanstack/preact-pacer 0.0.1 → 0.19.0

package/src/debouncer/useDebouncedValue.ts

@@ -0,0 +1,112 @@
+import { useEffect } from 'preact/hooks'
+import { useDebouncedState } from './useDebouncedState'
+import type { Dispatch, StateUpdater } from 'preact/hooks'
+import type { PreactDebouncer } from './useDebouncer'
+import type {
+  DebouncerOptions,
+  DebouncerState,
+} from '@tanstack/pacer/debouncer'
+
+/**
+ * A Preact hook that creates a debounced value that updates only after a specified delay.
+ * Unlike useDebouncedState, 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 the current debounced value and the underlying debouncer instance.
+ * The debouncer instance can be used to access additional functionality like cancellation
+ * and execution counts.
+ *
+ * ## 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 a re-render,
+ * optimizing performance by preventing unnecessary re-renders 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 re-renders and gives you
+ * full control over when your component updates. Only when you provide a selector will the
+ * component re-render when the selected state values change.
+ *
+ * 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] = useState('');
+ * const [debouncedQuery, debouncer] = useDebouncedValue(searchQuery, {
+ *   wait: 500 // Wait 500ms after last change
+ * });
+ *
+ * // Opt-in to re-render when pending state changes (optimized for loading indicators)
+ * const [debouncedQuery, debouncer] = useDebouncedValue(
+ *   searchQuery,
+ *   { wait: 500 },
+ *   (state) => ({ isPending: state.isPending })
+ * );
+ *
+ * // Opt-in to re-render when execution count changes (optimized for tracking executions)
+ * const [debouncedQuery, debouncer] = useDebouncedValue(
+ *   searchQuery,
+ *   { wait: 500 },
+ *   (state) => ({ executionCount: state.executionCount })
+ * );
+ *
+ * // Opt-in to re-render when debouncing status changes (optimized for status display)
+ * const [debouncedQuery, debouncer] = useDebouncedValue(
+ *   searchQuery,
+ *   { wait: 500 },
+ *   (state) => ({
+ *     status: state.status,
+ *     canLeadingExecute: state.canLeadingExecute
+ *   })
+ * );
+ *
+ * // debouncedQuery will update 500ms after searchQuery stops changing
+ * useEffect(() => {
+ *   fetchSearchResults(debouncedQuery);
+ * }, [debouncedQuery]);
+ *
+ * // Handle input changes
+ * const handleChange = (e) => {
+ *   setSearchQuery(e.target.value);
+ * };
+ *
+ * // Access the selected debouncer state (will be empty object {} unless selector provided)
+ * const { isPending, executionCount } = debouncer.state;
+ * ```
+ */
+export function useDebouncedValue<
+  TValue,
+  TSelected = DebouncerState<Dispatch<StateUpdater<TValue>>>,
+>(
+  value: TValue,
+  options: DebouncerOptions<Dispatch<StateUpdater<TValue>>>,
+  selector?: (
+    state: DebouncerState<Dispatch<StateUpdater<TValue>>>,
+  ) => TSelected,
+): [TValue, PreactDebouncer<Dispatch<StateUpdater<TValue>>, TSelected>] {
+  const [debouncedValue, setDebouncedValue, debouncer] = useDebouncedState(
+    value,
+    options,
+    selector,
+  )
+
+  useEffect(() => {
+    ;(setDebouncedValue as (value: TValue) => void)(value)
+  }, [value, setDebouncedValue])
+
+  return [debouncedValue, debouncer]
+}

package/src/debouncer/useDebouncer.ts

@@ -0,0 +1,189 @@
+import { useEffect, useMemo, useState } from 'preact/hooks'
+import { Debouncer } from '@tanstack/pacer/debouncer'
+import { useStore } from '@tanstack/preact-store'
+import { useDefaultPacerOptions } from '../provider/PacerProvider'
+import type { Store } from '@tanstack/preact-store'
+import type {
+  DebouncerOptions,
+  DebouncerState,
+} from '@tanstack/pacer/debouncer'
+import type { AnyFunction } from '@tanstack/pacer/types'
+import type { ComponentChildren } from 'preact'
+
+export interface PreactDebouncer<
+  TFn extends AnyFunction,
+  TSelected = {},
+> extends Omit<Debouncer<TFn>, 'store'> {
+  /**
+   * A Preact HOC (Higher Order Component) that allows you to subscribe to the debouncer state.
+   *
+   * This is useful for opting into state re-renders for 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 })}>
+   *   {({ isPending }) => (
+   *     <div>{isPending ? 'Loading...' : 'Ready'}</div>
+   *   )}
+   * </debouncer.Subscribe>
+   */
+  Subscribe: <TSelected>(props: {
+    selector: (state: DebouncerState<TFn>) => TSelected
+    children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+  }) => ComponentChildren
+  /**
+   * Reactive state that will be updated and re-rendered when the debouncer state changes
+   *
+   * Use this instead of `debouncer.store.state`
+   */
+  readonly state: 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 `useStore` hook internally.
+   * Although, you can make the state reactive by using the `useStore` in your own usage.
+   */
+  readonly store: Store<Readonly<DebouncerState<TFn>>>
+}
+
+/**
+ * A Preact 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 (useState, 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` HOC (Recommended for component tree subscriptions)**
+ *
+ * Use the `Subscribe` HOC 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 a re-render
+ * at the hook level, optimizing performance by preventing unnecessary re-renders 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` HOC. This prevents unnecessary
+ * re-renders and gives you full control over when your component updates.
+ *
+ * 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')
+ *
+ * @example
+ * ```tsx
+ * // Default behavior - no reactive state subscriptions
+ * const searchDebouncer = useDebouncer(
+ *   (query: string) => fetchSearchResults(query),
+ *   { wait: 500 }
+ * );
+ *
+ * // Subscribe to state changes deep in component tree using Subscribe HOC
+ * <searchDebouncer.Subscribe selector={(state) => ({ isPending: state.isPending })}>
+ *   {({ isPending }) => (
+ *     <div>{isPending ? 'Searching...' : 'Ready'}</div>
+ *   )}
+ * </searchDebouncer.Subscribe>
+ *
+ * // Opt-in to re-render when isPending changes at hook level (optimized for loading states)
+ * const searchDebouncer = useDebouncer(
+ *   (query: string) => fetchSearchResults(query),
+ *   { wait: 500 },
+ *   (state) => ({ isPending: state.isPending })
+ * );
+ *
+ * // Opt-in to re-render when executionCount changes (optimized for tracking execution)
+ * const searchDebouncer = useDebouncer(
+ *   (query: string) => fetchSearchResults(query),
+ *   { wait: 500 },
+ *   (state) => ({ executionCount: state.executionCount })
+ * );
+ *
+ * // Multiple state properties - re-render when any of these change
+ * const searchDebouncer = useDebouncer(
+ *   (query: string) => fetchSearchResults(query),
+ *   { wait: 500 },
+ *   (state) => ({
+ *     isPending: state.isPending,
+ *     executionCount: state.executionCount,
+ *     status: state.status
+ *   })
+ * );
+ *
+ * // In an event handler
+ * const handleChange = (e) => {
+ *   searchDebouncer.maybeExecute(e.target.value);
+ * };
+ *
+ * // Access the selected state (will be empty object {} unless selector provided)
+ * const { isPending } = searchDebouncer.state;
+ * ```
+ */
+export function useDebouncer<TFn extends AnyFunction, TSelected = {}>(
+  fn: TFn,
+  options: DebouncerOptions<TFn>,
+  selector: (state: DebouncerState<TFn>) => TSelected = () => ({}) as TSelected,
+): PreactDebouncer<TFn, TSelected> {
+  const mergedOptions = {
+    ...useDefaultPacerOptions().debouncer,
+    ...options,
+  } as DebouncerOptions<TFn>
+
+  const [debouncer] = useState(() => {
+    const debouncerInstance = new Debouncer(
+      fn,
+      mergedOptions,
+    ) as unknown as PreactDebouncer<TFn, TSelected>
+
+    debouncerInstance.Subscribe = function Subscribe<TSelected>(props: {
+      selector: (state: DebouncerState<TFn>) => TSelected
+      children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+    }) {
+      const selected = useStore(debouncerInstance.store, props.selector)
+
+      return typeof props.children === 'function'
+        ? props.children(selected)
+        : props.children
+    }
+
+    return debouncerInstance
+  })
+
+  debouncer.fn = fn
+  debouncer.setOptions(mergedOptions)
+
+  useEffect(() => {
+    return () => {
+      debouncer.cancel()
+    }
+  }, [debouncer])
+
+  const state = useStore(debouncer.store, selector)
+
+  return useMemo(
+    () =>
+      ({
+        ...debouncer,
+        state,
+      }) as PreactDebouncer<TFn, TSelected>, // omit `store` in favor of `state`
+    [debouncer, state],
+  )
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+// 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/useAsyncBatcher'
+export * from './async-batcher/useAsyncBatchedCallback'
+
+// async-debouncer
+export * from './async-debouncer/useAsyncDebouncer'
+export * from './async-debouncer/useAsyncDebouncedCallback'
+
+// async-queuer
+export * from './async-queuer/useAsyncQueuer'
+export * from './async-queuer/useAsyncQueuedState'
+
+// async-rate-limiter
+export * from './async-rate-limiter/useAsyncRateLimiter'
+export * from './async-rate-limiter/useAsyncRateLimitedCallback'
+
+// async-throttler
+export * from './async-throttler/useAsyncThrottler'
+export * from './async-throttler/useAsyncThrottledCallback'
+
+// batcher
+export * from './batcher/useBatcher'
+export * from './batcher/useBatchedCallback'
+
+// debouncer
+export * from './debouncer/useDebouncedCallback'
+export * from './debouncer/useDebouncedState'
+export * from './debouncer/useDebouncedValue'
+export * from './debouncer/useDebouncer'
+
+// queuer
+export * from './queuer/useQueuer'
+export * from './queuer/useQueuedState'
+export * from './queuer/useQueuedValue'
+
+// rate-limiter
+export * from './rate-limiter/useRateLimitedCallback'
+export * from './rate-limiter/useRateLimiter'
+export * from './rate-limiter/useRateLimitedState'
+export * from './rate-limiter/useRateLimitedValue'
+
+// throttler
+export * from './throttler/useThrottledCallback'
+export * from './throttler/useThrottledState'
+export * from './throttler/useThrottledValue'
+export * from './throttler/useThrottler'

package/src/provider/PacerProvider.tsx

@@ -0,0 +1,70 @@
+import { useContext, useMemo } from 'preact/hooks'
+import { createContext } from 'preact'
+import type { ComponentChildren } from 'preact'
+import type {
+  AnyAsyncFunction,
+  AnyFunction,
+  AsyncBatcherOptions,
+  AsyncDebouncerOptions,
+  AsyncQueuerOptions,
+  AsyncRateLimiterOptions,
+  AsyncThrottlerOptions,
+  BatcherOptions,
+  DebouncerOptions,
+  QueuerOptions,
+  RateLimiterOptions,
+  ThrottlerOptions,
+} from '@tanstack/pacer'
+
+export interface PacerProviderOptions {
+  asyncBatcher?: Partial<AsyncBatcherOptions<any>>
+  asyncDebouncer?: Partial<AsyncDebouncerOptions<AnyAsyncFunction>>
+  asyncQueuer?: Partial<AsyncQueuerOptions<any>>
+  asyncRateLimiter?: Partial<AsyncRateLimiterOptions<AnyAsyncFunction>>
+  asyncThrottler?: Partial<AsyncThrottlerOptions<AnyAsyncFunction>>
+  batcher?: Partial<BatcherOptions<any>>
+  debouncer?: Partial<DebouncerOptions<AnyFunction>>
+  queuer?: Partial<QueuerOptions<any>>
+  rateLimiter?: Partial<RateLimiterOptions<AnyFunction>>
+  throttler?: Partial<ThrottlerOptions<AnyFunction>>
+}
+
+interface PacerContextValue {
+  defaultOptions: PacerProviderOptions
+}
+
+const PacerContext = createContext<PacerContextValue | null>(null)
+
+export interface PacerProviderProps {
+  children: ComponentChildren
+  defaultOptions?: PacerProviderOptions
+}
+
+const DEFAULT_OPTIONS: PacerProviderOptions = {}
+
+export function PacerProvider({
+  children,
+  defaultOptions = DEFAULT_OPTIONS,
+}: PacerProviderProps) {
+  const contextValue: PacerContextValue = useMemo(
+    () => ({
+      defaultOptions,
+    }),
+    [defaultOptions],
+  )
+
+  return (
+    <PacerContext.Provider value={contextValue}>
+      {children}
+    </PacerContext.Provider>
+  )
+}
+
+export function usePacerContext() {
+  return useContext(PacerContext)
+}
+
+export function useDefaultPacerOptions() {
+  const context = useContext(PacerContext)
+  return context?.defaultOptions ?? {}
+}

package/src/provider/index.ts

@@ -0,0 +1 @@
+export * from './PacerProvider'

package/src/queuer/index.ts

@@ -0,0 +1,5 @@
+export * from '@tanstack/pacer/queuer'
+
+export * from './useQueuer'
+export * from './useQueuedState'
+export * from './useQueuedValue'

package/src/queuer/useQueuedState.ts

@@ -0,0 +1,133 @@
+import { useQueuer } from './useQueuer'
+import type { PreactQueuer } from './useQueuer'
+import type { Queuer, QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
+
+/**
+ * A Preact hook that creates a queuer with managed state, combining Preact's useState with queuing functionality.
+ * This hook provides both the current queue state and queue control methods.
+ *
+ * The queue state is automatically updated whenever items are added, removed, or reordered in the queue.
+ * All queue operations are reflected in the state array returned by the hook.
+ *
+ * The queue can be started and stopped to automatically process items at a specified interval,
+ * making it useful as a scheduler. When started, it will process one item per tick, with an
+ * optional wait time between ticks.
+ *
+ * The hook returns a tuple containing:
+ * - The current queue state as an array
+ * - The queue instance with methods for queue manipulation
+ *
+ * ## State Management and Selector
+ *
+ * The hook uses TanStack Store for reactive state management via the underlying queuer instance.
+ * The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,
+ * optimizing performance by preventing unnecessary re-renders 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 re-renders and gives you
+ * full control over when your component updates. Only when you provide a selector will the
+ * component re-render when the selected state values change.
+ *
+ * Available queuer state properties:
+ * - `executionCount`: Number of items that have been processed by the queuer
+ * - `expirationCount`: Number of items that have been removed due to expiration
+ * - `isEmpty`: Whether the queuer has no items to process
+ * - `isFull`: Whether the queuer has reached its maximum capacity
+ * - `isIdle`: Whether the queuer is not currently processing any items
+ * - `isRunning`: Whether the queuer is active and will process items automatically
+ * - `items`: Array of items currently waiting to be processed
+ * - `itemTimestamps`: Timestamps when items were added for expiration tracking
+ * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item
+ * - `rejectionCount`: Number of items that have been rejected from being added
+ * - `size`: Number of items currently in the queue
+ * - `status`: Current processing status ('idle' | 'running' | 'stopped')
+ *
+ * @example
+ * ```tsx
+ * // Default behavior - no reactive state subscriptions
+ * const [items, addItem, queue] = useQueuedState(
+ *   (item) => console.log('Processing:', item),
+ *   {
+ *     initialItems: ['item1', 'item2'],
+ *     started: true,
+ *     wait: 1000,
+ *     getPriority: (item) => item.priority
+ *   }
+ * );
+ *
+ * // Opt-in to re-render when queue contents change (optimized for displaying queue items)
+ * const [items, addItem, queue] = useQueuedState(
+ *   (item) => console.log('Processing:', item),
+ *   { started: true, wait: 1000 },
+ *   (state) => ({
+ *     items: state.items,
+ *     size: state.size,
+ *     isEmpty: state.isEmpty
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when processing state changes (optimized for loading indicators)
+ * const [items, addItem, queue] = useQueuedState(
+ *   (item) => console.log('Processing:', item),
+ *   { started: true, wait: 1000 },
+ *   (state) => ({
+ *     isRunning: state.isRunning,
+ *     isIdle: state.isIdle,
+ *     status: state.status,
+ *     pendingTick: state.pendingTick
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when execution metrics change (optimized for stats display)
+ * const [items, addItem, queue] = useQueuedState(
+ *   (item) => console.log('Processing:', item),
+ *   { started: true, wait: 1000 },
+ *   (state) => ({
+ *     executionCount: state.executionCount,
+ *     expirationCount: state.expirationCount,
+ *     rejectionCount: state.rejectionCount
+ *   })
+ * );
+ *
+ * // Add items to queue
+ * const handleAdd = (item) => {
+ *   addItem(item);
+ * };
+ *
+ * // Start automatic processing
+ * const startProcessing = () => {
+ *   queue.start();
+ * };
+ *
+ * // Stop automatic processing
+ * const stopProcessing = () => {
+ *   queue.stop();
+ * };
+ *
+ * // Manual processing still available
+ * const handleProcess = () => {
+ *   const nextItem = queue.getNextItem();
+ *   if (nextItem) {
+ *     processItem(nextItem);
+ *   }
+ * };
+ *
+ * // Access the selected queuer state (will be empty object {} unless selector provided)
+ * const { size, isRunning, executionCount } = queue.state;
+ * ```
+ */
+export function useQueuedState<
+  TValue,
+  TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<
+    QueuerState<TValue>,
+    'items'
+  >,
+>(
+  fn: (item: TValue) => void,
+  options: QueuerOptions<TValue> = {},
+  selector?: (state: QueuerState<TValue>) => TSelected,
+): [Array<TValue>, Queuer<TValue>['addItem'], PreactQueuer<TValue, TSelected>] {
+  const queue = useQueuer(fn, options, selector)
+
+  return [queue.state.items, queue.addItem, queue]
+}