@tanstack/preact-pacer 0.19.4 → 0.20.0

package/src/debouncer/useDebouncedValue.ts

@@ -1,11 +1,8 @@
 import { useEffect } from 'preact/hooks'
 import { useDebouncedState } from './useDebouncedState'
+import type { PreactDebouncer, PreactDebouncerOptions } from './useDebouncer'
 import type { Dispatch, StateUpdater } from 'preact/hooks'
-import type { PreactDebouncer } from './useDebouncer'
-import type {
-  DebouncerOptions,
-  DebouncerState,
-} from '@tanstack/pacer/debouncer'
+import type { DebouncerState } from '@tanstack/pacer/debouncer'
 
 /**
  * A Preact hook that creates a debounced value that updates only after a specified delay.
@@ -93,7 +90,7 @@ export function useDebouncedValue<
   TSelected = DebouncerState<Dispatch<StateUpdater<TValue>>>,
 >(
   value: TValue,
-  options: DebouncerOptions<Dispatch<StateUpdater<TValue>>>,
+  options: PreactDebouncerOptions<Dispatch<StateUpdater<TValue>>, TSelected>,
   selector?: (
     state: DebouncerState<Dispatch<StateUpdater<TValue>>>,
   ) => TSelected,

package/src/debouncer/useDebouncer.ts

@@ -10,6 +10,17 @@ import type {
 import type { AnyFunction } from '@tanstack/pacer/types'
 import type { ComponentChildren } from 'preact'
 
+export interface PreactDebouncerOptions<
+  TFn extends AnyFunction,
+  TSelected = {},
+> extends DebouncerOptions<TFn> {
+  /**
+   * Optional callback invoked when the 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: PreactDebouncer<TFn, TSelected>) => void
+}
+
 export interface PreactDebouncer<
   TFn extends AnyFunction,
   TSelected = {},
@@ -88,6 +99,18 @@ export interface PreactDebouncer<
  * - `lastArgs`: The arguments from the most recent call to maybeExecute
  * - `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 debouncer = useDebouncer(fn, {
+ *   wait: 500,
+ *   onUnmount: (d) => d.flush()
+ * });
+ * ```
+ *
  * @example
  * ```tsx
  * // Default behavior - no reactive state subscriptions
@@ -139,14 +162,13 @@ export interface PreactDebouncer<
  */
 export function useDebouncer<TFn extends AnyFunction, TSelected = {}>(
   fn: TFn,
-  options: DebouncerOptions<TFn>,
+  options: PreactDebouncerOptions<TFn, TSelected>,
   selector: (state: DebouncerState<TFn>) => TSelected = () => ({}) as TSelected,
 ): PreactDebouncer<TFn, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().debouncer,
     ...options,
-  } as DebouncerOptions<TFn>
-
+  } as PreactDebouncerOptions<TFn, TSelected>
   const [debouncer] = useState(() => {
     const debouncerInstance = new Debouncer(
       fn,
@@ -170,11 +192,17 @@ export function useDebouncer<TFn extends AnyFunction, TSelected = {}>(
   debouncer.fn = fn
   debouncer.setOptions(mergedOptions)
 
+  /* eslint-disable react-hooks/exhaustive-deps -- cleanup only; runs on unmount */
   useEffect(() => {
     return () => {
-      debouncer.cancel()
+      if (mergedOptions.onUnmount) {
+        mergedOptions.onUnmount(debouncer)
+      } else {
+        debouncer.cancel()
+      }
     }
-  }, [debouncer])
+  }, [])
+  /* eslint-enable react-hooks/exhaustive-deps */
 
   const state = useStore(debouncer.store, selector)
 

package/src/queuer/useQueuedState.ts

@@ -1,6 +1,6 @@
 import { useQueuer } from './useQueuer'
-import type { PreactQueuer } from './useQueuer'
-import type { Queuer, QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
+import type { PreactQueuer, PreactQueuerOptions } from './useQueuer'
+import type { Queuer, QueuerState } from '@tanstack/pacer/queuer'
 
 /**
  * A Preact hook that creates a queuer with managed state, combining Preact's useState with queuing functionality.
@@ -124,7 +124,7 @@ export function useQueuedState<
   >,
 >(
   fn: (item: TValue) => void,
-  options: QueuerOptions<TValue> = {},
+  options: PreactQueuerOptions<TValue, TSelected> = {},
   selector?: (state: QueuerState<TValue>) => TSelected,
 ): [Array<TValue>, Queuer<TValue>['addItem'], PreactQueuer<TValue, TSelected>] {
   const queue = useQueuer(fn, options, selector)

package/src/queuer/useQueuedValue.ts

@@ -1,7 +1,7 @@
 import { useEffect, useState } from 'preact/hooks'
 import { useQueuedState } from './useQueuedState'
-import type { PreactQueuer } from './useQueuer'
-import type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
+import type { PreactQueuer, PreactQueuerOptions } from './useQueuer'
+import type { QueuerState } from '@tanstack/pacer/queuer'
 
 /**
  * A Preact hook that creates a queued value that processes state changes in order with an optional delay.
@@ -108,7 +108,7 @@ export function useQueuedValue<
   >,
 >(
   initialValue: TValue,
-  options: QueuerOptions<TValue> = {},
+  options: PreactQueuerOptions<TValue, TSelected> = {},
   selector?: (state: QueuerState<TValue>) => TSelected,
 ): [TValue, PreactQueuer<TValue, TSelected>] {
   const [value, setValue] = useState<TValue>(initialValue)

package/src/queuer/useQueuer.ts

@@ -1,4 +1,4 @@
-import { useMemo, useState } from 'preact/hooks'
+import { useEffect, useMemo, useState } from 'preact/hooks'
 import { Queuer } from '@tanstack/pacer/queuer'
 import { useStore } from '@tanstack/preact-store'
 import { useDefaultPacerOptions } from '../provider/PacerProvider'
@@ -6,6 +6,17 @@ import type { Store } from '@tanstack/preact-store'
 import type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
 import type { ComponentChildren } from 'preact'
 
+export interface PreactQueuerOptions<
+  TValue,
+  TSelected = {},
+> extends QueuerOptions<TValue> {
+  /**
+   * Optional callback invoked when the component unmounts. Receives the queuer instance.
+   * When provided, replaces the default cleanup (stop); use it to call flush(), flushAsBatch(), stop(), add logging, etc.
+   */
+  onUnmount?: (queuer: PreactQueuer<TValue, TSelected>) => void
+}
+
 export interface PreactQueuer<TValue, TSelected = {}> extends Omit<
   Queuer<TValue>,
   'store'
@@ -93,6 +104,19 @@ export interface PreactQueuer<TValue, TSelected = {}> extends Omit<
  * - `size`: Number of items currently in the queue
  * - `status`: Current processing status ('idle' | 'running' | 'stopped')
  *
+ * ## Unmount behavior
+ *
+ * By default, the hook stops the queuer when the component unmounts.
+ * Use the `onUnmount` option to customize this. For example, to flush pending items instead:
+ *
+ * ```tsx
+ * const queue = useQueuer(fn, {
+ *   started: true,
+ *   wait: 1000,
+ *   onUnmount: (q) => q.flush()
+ * });
+ * ```
+ *
  * @example
  * ```tsx
  * // Default behavior - no reactive state subscriptions
@@ -169,13 +193,13 @@ export interface PreactQueuer<TValue, TSelected = {}> extends Omit<
  */
 export function useQueuer<TValue, TSelected = {}>(
   fn: (item: TValue) => void,
-  options: QueuerOptions<TValue> = {},
+  options: PreactQueuerOptions<TValue, TSelected> = {},
   selector: (state: QueuerState<TValue>) => TSelected = () => ({}) as TSelected,
 ): PreactQueuer<TValue, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().queuer,
     ...options,
-  } as QueuerOptions<TValue>
+  } as PreactQueuerOptions<TValue, TSelected>
 
   const [queuer] = useState(() => {
     const queuerInstance = new Queuer<TValue>(
@@ -200,6 +224,18 @@ export function useQueuer<TValue, TSelected = {}>(
   queuer.fn = fn
   queuer.setOptions(mergedOptions)
 
+  /* eslint-disable react-hooks/exhaustive-deps -- cleanup only; runs on unmount */
+  useEffect(() => {
+    return () => {
+      if (mergedOptions.onUnmount) {
+        mergedOptions.onUnmount(queuer)
+      } else {
+        queuer.stop()
+      }
+    }
+  }, [])
+  /* eslint-enable react-hooks/exhaustive-deps */
+
   const state = useStore(queuer.store, selector)
 
   return useMemo(

package/src/rate-limiter/useRateLimitedCallback.ts

@@ -1,7 +1,7 @@
 import { useCallback } from 'preact/hooks'
 import { useRateLimiter } from './useRateLimiter'
 import type { AnyFunction } from '@tanstack/pacer/types'
-import type { RateLimiterOptions } from '@tanstack/pacer/rate-limiter'
+import type { PreactRateLimiterOptions } from './useRateLimiter'
 
 /**
  * A Preact hook that creates a rate-limited version of a callback function.
@@ -58,7 +58,7 @@ import type { RateLimiterOptions } from '@tanstack/pacer/rate-limiter'
  */
 export function useRateLimitedCallback<TFn extends AnyFunction>(
   fn: TFn,
-  options: RateLimiterOptions<TFn>,
+  options: PreactRateLimiterOptions<TFn, {}>,
 ): (...args: Parameters<TFn>) => boolean {
   const rateLimitedFn = useRateLimiter(fn, options).maybeExecute
   return useCallback(

package/src/rate-limiter/useRateLimitedState.ts

@@ -1,11 +1,11 @@
 import { useState } from 'preact/hooks'
 import { useRateLimiter } from './useRateLimiter'
-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 Preact hook that creates a rate-limited state value that enforces a hard limit on state updates within a time window.
@@ -107,7 +107,7 @@ import type {
  */
 export function useRateLimitedState<TValue, TSelected = RateLimiterState>(
   value: TValue,
-  options: RateLimiterOptions<Dispatch<StateUpdater<TValue>>>,
+  options: PreactRateLimiterOptions<Dispatch<StateUpdater<TValue>>, TSelected>,
   selector?: (state: RateLimiterState) => TSelected,
 ): [
   TValue,

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,4 +1,4 @@
-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 { useDefaultPacerOptions } from '../provider/PacerProvider'
@@ -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,
@@ -209,6 +219,16 @@ export function useRateLimiter<TFn extends AnyFunction, TSelected = {}>(
   rateLimiter.fn = fn
   rateLimiter.setOptions(mergedOptions)
 
+  /* 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)
 
   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

@@ -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,
@@ -177,11 +199,17 @@ export function useThrottler<TFn extends AnyFunction, TSelected = {}>(
 
   const state = useStore(throttler.store, selector)
 
+  /* 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(
     () =>