@tanstack/preact-pacer 0.0.1 → 0.19.0

package/src/throttler/useThrottler.ts

@@ -0,0 +1,194 @@
+import { useEffect, useMemo, useState } from 'preact/hooks'
+import { Throttler } from '@tanstack/pacer/throttler'
+import { useStore } from '@tanstack/preact-store'
+import { useDefaultPacerOptions } from '../provider/PacerProvider'
+import type { Store } from '@tanstack/preact-store'
+import type { AnyFunction } from '@tanstack/pacer/types'
+import type {
+  ThrottlerOptions,
+  ThrottlerState,
+} from '@tanstack/pacer/throttler'
+import type { ComponentChildren } from 'preact'
+
+export interface PreactThrottler<
+  TFn extends AnyFunction,
+  TSelected = {},
+> extends Omit<Throttler<TFn>, 'store'> {
+  /**
+   * A Preact HOC (Higher Order Component) that allows you to subscribe to the throttler state.
+   *
+   * This is useful for opting into state re-renders for specific parts of the throttler state
+   * deep in your component tree without needing to pass a selector to the hook.
+   *
+   * @example
+   * <throttler.Subscribe selector={(state) => ({ isPending: state.isPending })}>
+   *   {({ isPending }) => (
+   *     <div>{isPending ? 'Loading...' : 'Ready'}</div>
+   *   )}
+   * </throttler.Subscribe>
+   */
+  Subscribe: <TSelected>(props: {
+    selector: (state: ThrottlerState<TFn>) => TSelected
+    children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+  }) => ComponentChildren
+  /**
+   * Reactive state that will be updated and re-rendered when the throttler state changes
+   *
+   * Use this instead of `throttler.store.state`
+   */
+  readonly state: Readonly<TSelected>
+  /**
+   * @deprecated Use `throttler.state` instead of `throttler.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<ThrottlerState<TFn>>>
+}
+
+/**
+ * A low-level Preact hook that creates a `Throttler` instance that limits how often the provided function can execute.
+ *
+ * This hook is designed to be flexible and state-management agnostic - it simply returns a throttler instance that
+ * you can integrate with any state management solution (useState, Redux, Zustand, Jotai, etc). For a simpler and higher-level hook that
+ * integrates directly with Preact's useState, see useThrottledState.
+ *
+ * Throttling ensures a function executes at most once within a specified time window,
+ * regardless of how many times it is called. This is useful for rate-limiting
+ * expensive operations or UI updates.
+ *
+ * ## State Management and Selector
+ *
+ * The hook uses TanStack Store for reactive state management. You can subscribe to state changes
+ * in two ways:
+ *
+ * **1. Using `throttler.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:
+ * - `executionCount`: Number of function executions that have been completed
+ * - `lastArgs`: The arguments from the most recent call to maybeExecute
+ * - `lastExecutionTime`: Timestamp of the last function execution in milliseconds
+ * - `nextExecutionTime`: Timestamp when the next execution can occur in milliseconds
+ * - `isPending`: Whether the throttler is waiting for the timeout to trigger execution
+ * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
+ *
+ * @example
+ * ```tsx
+ * // Default behavior - no reactive state subscriptions
+ * const [value, setValue] = useState(0);
+ * const throttler = useThrottler(setValue, { wait: 1000 });
+ *
+ * // Subscribe to state changes deep in component tree using Subscribe HOC
+ * <throttler.Subscribe selector={(state) => ({ isPending: state.isPending })}>
+ *   {({ isPending }) => (
+ *     <div>{isPending ? 'Processing...' : 'Ready'}</div>
+ *   )}
+ * </throttler.Subscribe>
+ *
+ * // Opt-in to re-render when execution count changes at hook level (optimized for tracking executions)
+ * const [value, setValue] = useState(0);
+ * const throttler = useThrottler(
+ *   setValue,
+ *   { wait: 1000 },
+ *   (state) => ({ executionCount: state.executionCount })
+ * );
+ *
+ * // Opt-in to re-render when throttling state changes (optimized for loading indicators)
+ * const [value, setValue] = useState(0);
+ * const throttler = useThrottler(
+ *   setValue,
+ *   { wait: 1000 },
+ *   (state) => ({
+ *     isPending: state.isPending,
+ *     status: state.status
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when timing information changes (optimized for timing displays)
+ * const [value, setValue] = useState(0);
+ * const throttler = useThrottler(
+ *   setValue,
+ *   { wait: 1000 },
+ *   (state) => ({
+ *     lastExecutionTime: state.lastExecutionTime,
+ *     nextExecutionTime: state.nextExecutionTime
+ *   })
+ * );
+ *
+ * // With any state manager
+ * const throttler = useThrottler(
+ *   (value) => stateManager.setState(value),
+ *   {
+ *     wait: 2000,
+ *     leading: true,   // Execute immediately on first call
+ *     trailing: false  // Skip trailing edge updates
+ *   }
+ * );
+ *
+ * // Access the selected state (will be empty object {} unless selector provided)
+ * const { executionCount, isPending } = throttler.state;
+ * ```
+ */
+export function useThrottler<TFn extends AnyFunction, TSelected = {}>(
+  fn: TFn,
+  options: ThrottlerOptions<TFn>,
+  selector: (state: ThrottlerState<TFn>) => TSelected = () => ({}) as TSelected,
+): PreactThrottler<TFn, TSelected> {
+  const mergedOptions = {
+    ...useDefaultPacerOptions().throttler,
+    ...options,
+  } as ThrottlerOptions<TFn>
+
+  const [throttler] = useState(() => {
+    const throttlerInstance = new Throttler<TFn>(
+      fn,
+      mergedOptions,
+    ) as unknown as PreactThrottler<TFn, TSelected>
+
+    throttlerInstance.Subscribe = function Subscribe<TSelected>(props: {
+      selector: (state: ThrottlerState<TFn>) => TSelected
+      children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+    }) {
+      const selected = useStore(throttlerInstance.store, props.selector)
+
+      return typeof props.children === 'function'
+        ? props.children(selected)
+        : props.children
+    }
+
+    return throttlerInstance
+  })
+
+  throttler.fn = fn
+  throttler.setOptions(mergedOptions)
+
+  const state = useStore(throttler.store, selector)
+
+  useEffect(() => {
+    return () => {
+      throttler.cancel()
+    }
+  }, [throttler])
+
+  return useMemo(
+    () =>
+      ({
+        ...throttler,
+        state,
+      }) as PreactThrottler<TFn, TSelected>, // omit `store` in favor of `state`
+    [throttler, state],
+  )
+}

package/src/types/index.ts

@@ -0,0 +1 @@
+export * from '@tanstack/pacer/types'

package/src/utils/index.ts

@@ -0,0 +1 @@
+export * from '@tanstack/pacer/utils'