@tanstack/preact-pacer 0.19.4 → 0.21.0

package/src/rate-limiter/useRateLimitedValue.ts

@@ -1,11 +1,11 @@
 import { useEffect } from 'preact/hooks'
 import { useRateLimitedState } from './useRateLimitedState'
-import type { Dispatch, StateUpdater } from 'preact/hooks'
-import type { PreactRateLimiter } from './useRateLimiter'
 import type {
-  RateLimiterOptions,
-  RateLimiterState,
-} from '@tanstack/pacer/rate-limiter'
+  PreactRateLimiter,
+  PreactRateLimiterOptions,
+} from './useRateLimiter'
+import type { Dispatch, StateUpdater } from 'preact/hooks'
+import type { RateLimiterState } from '@tanstack/pacer/rate-limiter'
 
 /**
  * A high-level Preact hook that creates a rate-limited version of a value that updates at most a certain number of times within a time window.
@@ -96,7 +96,7 @@ import type {
  */
 export function useRateLimitedValue<TValue, TSelected = RateLimiterState>(
   value: TValue,
-  options: RateLimiterOptions<Dispatch<StateUpdater<TValue>>>,
+  options: PreactRateLimiterOptions<Dispatch<StateUpdater<TValue>>, TSelected>,
   selector?: (state: RateLimiterState) => TSelected,
 ): [TValue, PreactRateLimiter<Dispatch<StateUpdater<TValue>>, TSelected>] {
   const [rateLimitedValue, setRateLimitedValue, rateLimiter] =

package/src/rate-limiter/useRateLimiter.ts

@@ -1,6 +1,6 @@
-import { useMemo, useState } from 'preact/hooks'
+import { useEffect, useMemo, useState } from 'preact/hooks'
 import { RateLimiter } from '@tanstack/pacer/rate-limiter'
-import { useStore } from '@tanstack/preact-store'
+import { shallow, useStore } from '@tanstack/preact-store'
 import { useDefaultPacerOptions } from '../provider/PacerProvider'
 import type { Store } from '@tanstack/preact-store'
 import type {
@@ -10,6 +10,17 @@ import type {
 import type { AnyFunction } from '@tanstack/pacer/types'
 import type { ComponentChildren } from 'preact'
 
+export interface PreactRateLimiterOptions<
+  TFn extends AnyFunction,
+  TSelected = {},
+> extends RateLimiterOptions<TFn> {
+  /**
+   * Optional callback invoked when the component unmounts. Receives the rate limiter instance.
+   * When provided, replaces the default cleanup; use it to call reset(), add logging, etc.
+   */
+  onUnmount?: (rateLimiter: PreactRateLimiter<TFn, TSelected>) => void
+}
+
 export interface PreactRateLimiter<
   TFn extends AnyFunction,
   TSelected = {},
@@ -178,14 +189,13 @@ export interface PreactRateLimiter<
  */
 export function useRateLimiter<TFn extends AnyFunction, TSelected = {}>(
   fn: TFn,
-  options: RateLimiterOptions<TFn>,
+  options: PreactRateLimiterOptions<TFn, TSelected>,
   selector: (state: RateLimiterState) => TSelected = () => ({}) as TSelected,
 ): PreactRateLimiter<TFn, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().rateLimiter,
     ...options,
-  } as RateLimiterOptions<TFn>
-
+  } as PreactRateLimiterOptions<TFn, TSelected>
   const [rateLimiter] = useState(() => {
     const rateLimiterInstance = new RateLimiter<TFn>(
       fn,
@@ -196,7 +206,9 @@ export function useRateLimiter<TFn extends AnyFunction, TSelected = {}>(
       selector: (state: RateLimiterState) => TSelected
       children: ((state: TSelected) => ComponentChildren) | ComponentChildren
     }) {
-      const selected = useStore(rateLimiterInstance.store, props.selector)
+      const selected = useStore(rateLimiterInstance.store, props.selector, {
+        equal: shallow,
+      })
 
       return typeof props.children === 'function'
         ? props.children(selected)
@@ -209,7 +221,17 @@ export function useRateLimiter<TFn extends AnyFunction, TSelected = {}>(
   rateLimiter.fn = fn
   rateLimiter.setOptions(mergedOptions)
 
-  const state = useStore(rateLimiter.store, selector)
+  /* eslint-disable react-hooks/exhaustive-deps -- cleanup only; runs on unmount */
+  useEffect(() => {
+    return () => {
+      if (mergedOptions.onUnmount) {
+        mergedOptions.onUnmount(rateLimiter)
+      }
+    }
+  }, [])
+  /* eslint-enable react-hooks/exhaustive-deps */
+
+  const state = useStore(rateLimiter.store, selector, { equal: shallow })
 
   return useMemo(
     () =>

package/src/throttler/useThrottledCallback.ts

@@ -1,6 +1,6 @@
 import { useCallback } from 'preact/hooks'
 import { useThrottler } from './useThrottler'
-import type { ThrottlerOptions } from '@tanstack/pacer/throttler'
+import type { PreactThrottlerOptions } from './useThrottler'
 import type { AnyFunction } from '@tanstack/pacer/types'
 
 /**
@@ -42,7 +42,7 @@ import type { AnyFunction } from '@tanstack/pacer/types'
  */
 export function useThrottledCallback<TFn extends AnyFunction>(
   fn: TFn,
-  options: ThrottlerOptions<TFn>,
+  options: PreactThrottlerOptions<TFn, {}>,
 ): (...args: Parameters<TFn>) => void {
   const throttledFn = useThrottler(fn, options).maybeExecute
   return useCallback(

package/src/throttler/useThrottledState.ts

@@ -1,11 +1,8 @@
 import { useState } from 'preact/hooks'
 import { useThrottler } from './useThrottler'
 import type { Dispatch, StateUpdater } from 'preact/hooks'
-import type { PreactThrottler } from './useThrottler'
-import type {
-  ThrottlerOptions,
-  ThrottlerState,
-} from '@tanstack/pacer/throttler'
+import type { PreactThrottler, PreactThrottlerOptions } from './useThrottler'
+import type { ThrottlerState } from '@tanstack/pacer/throttler'
 
 /**
  * A Preact hook that creates a throttled state value that updates at most once within a specified time window.
@@ -96,7 +93,7 @@ export function useThrottledState<
   TSelected = ThrottlerState<Dispatch<StateUpdater<TValue>>>,
 >(
   value: TValue,
-  options: ThrottlerOptions<Dispatch<StateUpdater<TValue>>>,
+  options: PreactThrottlerOptions<Dispatch<StateUpdater<TValue>>, TSelected>,
   selector?: (
     state: ThrottlerState<Dispatch<StateUpdater<TValue>>>,
   ) => TSelected,

package/src/throttler/useThrottledValue.ts

@@ -1,11 +1,8 @@
 import { useEffect } from 'preact/hooks'
 import { useThrottledState } from './useThrottledState'
 import type { Dispatch, StateUpdater } from 'preact/hooks'
-import type { PreactThrottler } from './useThrottler'
-import type {
-  ThrottlerOptions,
-  ThrottlerState,
-} from '@tanstack/pacer/throttler'
+import type { PreactThrottler, PreactThrottlerOptions } from './useThrottler'
+import type { ThrottlerState } from '@tanstack/pacer/throttler'
 
 /**
  * A high-level Preact hook that creates a throttled version of a value that updates at most once within a specified time window.
@@ -88,7 +85,7 @@ export function useThrottledValue<
   TSelected = ThrottlerState<Dispatch<StateUpdater<TValue>>>,
 >(
   value: TValue,
-  options: ThrottlerOptions<Dispatch<StateUpdater<TValue>>>,
+  options: PreactThrottlerOptions<Dispatch<StateUpdater<TValue>>, TSelected>,
   selector?: (
     state: ThrottlerState<Dispatch<StateUpdater<TValue>>>,
   ) => TSelected,

package/src/throttler/useThrottler.ts

@@ -1,6 +1,6 @@
 import { useEffect, useMemo, useState } from 'preact/hooks'
 import { Throttler } from '@tanstack/pacer/throttler'
-import { useStore } from '@tanstack/preact-store'
+import { shallow, useStore } from '@tanstack/preact-store'
 import { useDefaultPacerOptions } from '../provider/PacerProvider'
 import type { Store } from '@tanstack/preact-store'
 import type { AnyFunction } from '@tanstack/pacer/types'
@@ -10,6 +10,17 @@ import type {
 } from '@tanstack/pacer/throttler'
 import type { ComponentChildren } from 'preact'
 
+export interface PreactThrottlerOptions<
+  TFn extends AnyFunction,
+  TSelected = {},
+> extends ThrottlerOptions<TFn> {
+  /**
+   * Optional callback invoked when the component unmounts. Receives the throttler instance.
+   * When provided, replaces the default cleanup (cancel); use it to call flush(), reset(), cancel(), add logging, etc.
+   */
+  onUnmount?: (throttler: PreactThrottler<TFn, TSelected>) => void
+}
+
 export interface PreactThrottler<
   TFn extends AnyFunction,
   TSelected = {},
@@ -85,6 +96,18 @@ export interface PreactThrottler<
  * - `isPending`: Whether the throttler is waiting for the timeout to trigger execution
  * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
  *
+ * ## Unmount behavior
+ *
+ * By default, the hook cancels any pending execution when the component unmounts.
+ * Use the `onUnmount` option to customize this. For example, to flush pending work instead:
+ *
+ * ```tsx
+ * const throttler = useThrottler(fn, {
+ *   wait: 1000,
+ *   onUnmount: (t) => t.flush()
+ * });
+ * ```
+ *
  * @example
  * ```tsx
  * // Default behavior - no reactive state subscriptions
@@ -144,14 +167,13 @@ export interface PreactThrottler<
  */
 export function useThrottler<TFn extends AnyFunction, TSelected = {}>(
   fn: TFn,
-  options: ThrottlerOptions<TFn>,
+  options: PreactThrottlerOptions<TFn, TSelected>,
   selector: (state: ThrottlerState<TFn>) => TSelected = () => ({}) as TSelected,
 ): PreactThrottler<TFn, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().throttler,
     ...options,
-  } as ThrottlerOptions<TFn>
-
+  } as PreactThrottlerOptions<TFn, TSelected>
   const [throttler] = useState(() => {
     const throttlerInstance = new Throttler<TFn>(
       fn,
@@ -162,7 +184,9 @@ export function useThrottler<TFn extends AnyFunction, TSelected = {}>(
       selector: (state: ThrottlerState<TFn>) => TSelected
       children: ((state: TSelected) => ComponentChildren) | ComponentChildren
     }) {
-      const selected = useStore(throttlerInstance.store, props.selector)
+      const selected = useStore(throttlerInstance.store, props.selector, {
+        equal: shallow,
+      })
 
       return typeof props.children === 'function'
         ? props.children(selected)
@@ -175,13 +199,19 @@ export function useThrottler<TFn extends AnyFunction, TSelected = {}>(
   throttler.fn = fn
   throttler.setOptions(mergedOptions)
 
-  const state = useStore(throttler.store, selector)
+  const state = useStore(throttler.store, selector, { equal: shallow })
 
+  /* eslint-disable react-hooks/exhaustive-deps -- cleanup only; runs on unmount */
   useEffect(() => {
     return () => {
-      throttler.cancel()
+      if (mergedOptions.onUnmount) {
+        mergedOptions.onUnmount(throttler)
+      } else {
+        throttler.cancel()
+      }
     }
-  }, [throttler])
+  }, [])
+  /* eslint-enable react-hooks/exhaustive-deps */
 
   return useMemo(
     () =>