@tanstack/preact-pacer 0.19.3 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/preact-pacer",
-  "version": "0.19.3",
+  "version": "0.20.0",
   "description": "Utilities for debouncing and throttling functions in Preact.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -28,64 +28,64 @@
   "module": "./dist/index.js",
   "exports": {
     ".": {
-      "require": "./dist/index.cjs",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     },
     "./async-batcher": {
-      "require": "./dist/async-batcher/index.cjs",
-      "import": "./dist/async-batcher/index.js"
+      "import": "./dist/async-batcher/index.js",
+      "require": "./dist/async-batcher/index.cjs"
     },
     "./async-debouncer": {
-      "require": "./dist/async-debouncer/index.cjs",
-      "import": "./dist/async-debouncer/index.js"
+      "import": "./dist/async-debouncer/index.js",
+      "require": "./dist/async-debouncer/index.cjs"
     },
     "./async-queuer": {
-      "require": "./dist/async-queuer/index.cjs",
-      "import": "./dist/async-queuer/index.js"
+      "import": "./dist/async-queuer/index.js",
+      "require": "./dist/async-queuer/index.cjs"
     },
     "./async-rate-limiter": {
-      "require": "./dist/async-rate-limiter/index.cjs",
-      "import": "./dist/async-rate-limiter/index.js"
+      "import": "./dist/async-rate-limiter/index.js",
+      "require": "./dist/async-rate-limiter/index.cjs"
     },
     "./async-retryer": {
-      "require": "./dist/async-retryer/index.cjs",
-      "import": "./dist/async-retryer/index.js"
+      "import": "./dist/async-retryer/index.js",
+      "require": "./dist/async-retryer/index.cjs"
     },
     "./async-throttler": {
-      "require": "./dist/async-throttler/index.cjs",
-      "import": "./dist/async-throttler/index.js"
+      "import": "./dist/async-throttler/index.js",
+      "require": "./dist/async-throttler/index.cjs"
     },
     "./batcher": {
-      "require": "./dist/batcher/index.cjs",
-      "import": "./dist/batcher/index.js"
+      "import": "./dist/batcher/index.js",
+      "require": "./dist/batcher/index.cjs"
     },
     "./debouncer": {
-      "require": "./dist/debouncer/index.cjs",
-      "import": "./dist/debouncer/index.js"
+      "import": "./dist/debouncer/index.js",
+      "require": "./dist/debouncer/index.cjs"
     },
     "./provider": {
-      "require": "./dist/provider/index.cjs",
-      "import": "./dist/provider/index.js"
+      "import": "./dist/provider/index.js",
+      "require": "./dist/provider/index.cjs"
     },
     "./queuer": {
-      "require": "./dist/queuer/index.cjs",
-      "import": "./dist/queuer/index.js"
+      "import": "./dist/queuer/index.js",
+      "require": "./dist/queuer/index.cjs"
     },
     "./rate-limiter": {
-      "require": "./dist/rate-limiter/index.cjs",
-      "import": "./dist/rate-limiter/index.js"
+      "import": "./dist/rate-limiter/index.js",
+      "require": "./dist/rate-limiter/index.cjs"
     },
     "./throttler": {
-      "require": "./dist/throttler/index.cjs",
-      "import": "./dist/throttler/index.js"
+      "import": "./dist/throttler/index.js",
+      "require": "./dist/throttler/index.cjs"
     },
     "./types": {
-      "require": "./dist/types/index.cjs",
-      "import": "./dist/types/index.js"
+      "import": "./dist/types/index.js",
+      "require": "./dist/types/index.cjs"
     },
     "./utils": {
-      "require": "./dist/utils/index.cjs",
-      "import": "./dist/utils/index.js"
+      "import": "./dist/utils/index.js",
+      "require": "./dist/utils/index.cjs"
     },
     "./package.json": "./package.json"
   },
@@ -98,19 +98,20 @@
     "src"
   ],
   "dependencies": {
-    "@tanstack/preact-store": "^0.10.1",
-    "@tanstack/pacer": "0.17.3"
+    "@tanstack/preact-store": "^0.10.2",
+    "@tanstack/pacer": "0.19.0"
   },
   "devDependencies": {
-    "@preact/preset-vite": "^2.10.2",
+    "@preact/preset-vite": "^2.10.3",
     "eslint-plugin-react-hooks": "^7.0.1",
-    "preact": "^10.28.2"
+    "preact": "^10.28.3"
   },
   "peerDependencies": {
     "preact": ">=10.0.0"
   },
   "scripts": {
     "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
     "test:eslint": "eslint ./src",
     "test:lib": "vitest --passWithNoTests",
     "test:lib:dev": "pnpm test:lib --watch",

package/src/async-batcher/useAsyncBatchedCallback.ts

@@ -1,7 +1,6 @@
 import { useCallback } from 'preact/hooks'
 import { useAsyncBatcher } from './useAsyncBatcher'
-import type { AsyncBatcherOptions } from '@tanstack/pacer/async-batcher'
-import type { AnyAsyncFunction } from '@tanstack/pacer/types'
+import type { PreactAsyncBatcherOptions } from './useAsyncBatcher'
 
 /**
  * A Preact hook that creates a batched version of an async callback function.
@@ -40,14 +39,14 @@ import type { AnyAsyncFunction } from '@tanstack/pacer/types'
  * </button>
  * ```
  */
-export function useAsyncBatchedCallback<TFn extends AnyAsyncFunction>(
-  fn: (items: Array<Parameters<TFn>[0]>) => Promise<any>,
-  options: AsyncBatcherOptions<Parameters<TFn>[0]>,
-): (...args: Parameters<TFn>) => Promise<void> {
+export function useAsyncBatchedCallback<TValue>(
+  fn: (items: Array<TValue>) => Promise<unknown>,
+  options: PreactAsyncBatcherOptions<TValue, {}>,
+): (item: TValue) => Promise<void> {
   const asyncBatchedFn = useAsyncBatcher(fn, options).addItem
   return useCallback(
-    async (...args: Parameters<TFn>) => {
-      asyncBatchedFn(args[0])
+    async (item: TValue) => {
+      await asyncBatchedFn(item)
     },
     [asyncBatchedFn],
   )

package/src/async-batcher/useAsyncBatcher.ts

@@ -1,4 +1,4 @@
-import { useMemo, useState } from 'preact/hooks'
+import { useEffect, useMemo, useState } from 'preact/hooks'
 import { AsyncBatcher } from '@tanstack/pacer/async-batcher'
 import { useStore } from '@tanstack/preact-store'
 import { useDefaultPacerOptions } from '../provider/PacerProvider'
@@ -9,6 +9,17 @@ import type {
 } from '@tanstack/pacer/async-batcher'
 import type { ComponentChildren } from 'preact'
 
+export interface PreactAsyncBatcherOptions<
+  TValue,
+  TSelected = {},
+> extends AsyncBatcherOptions<TValue> {
+  /**
+   * Optional callback invoked when the component unmounts. Receives the batcher instance.
+   * When provided, replaces the default cleanup (cancel + abort); use it to call flush(), reset(), cancel(), add logging, etc.
+   */
+  onUnmount?: (batcher: PreactAsyncBatcher<TValue, TSelected>) => void
+}
+
 export interface PreactAsyncBatcher<TValue, TSelected = {}> extends Omit<
   AsyncBatcher<TValue>,
   'store'
@@ -110,6 +121,25 @@ export interface PreactAsyncBatcher<TValue, TSelected = {}> extends Omit<
  * - `totalItemsProcessed`: Total number of items processed across all batches
  * - `totalItemsFailed`: Total number of items that have failed processing
  *
+ * ## Unmount behavior
+ *
+ * By default, the hook cancels any pending batch and aborts any in-flight execution when the component unmounts.
+ * Abort only cancels underlying operations (e.g. fetch) when the abort signal from `getAbortSignal()` is passed to them.
+ * Use the `onUnmount` option to customize this. For example, to flush pending work instead:
+ *
+ * ```tsx
+ * const batcher = useAsyncBatcher(fn, {
+ *   maxSize: 10,
+ *   wait: 2000,
+ *   onUnmount: (b) => b.flush()
+ * });
+ * ```
+ *
+ * Note: For async utils, `flush()` returns a Promise and runs fire-and-forget in the cleanup.
+ * If your batch function updates Preact state, those updates may run after the component has
+ * unmounted, which can cause "setState on unmounted component" warnings. Guard your callbacks
+ * accordingly when using onUnmount with flush.
+ *
  * @example
  * ```tsx
  * // Basic async batcher for API requests - no reactive state subscriptions
@@ -204,15 +234,14 @@ export interface PreactAsyncBatcher<TValue, TSelected = {}> extends Omit<
  */
 export function useAsyncBatcher<TValue, TSelected = {}>(
   fn: (items: Array<TValue>) => Promise<any>,
-  options: AsyncBatcherOptions<TValue> = {},
+  options: PreactAsyncBatcherOptions<TValue, TSelected> = {},
   selector: (state: AsyncBatcherState<TValue>) => TSelected = () =>
     ({}) as TSelected,
 ): PreactAsyncBatcher<TValue, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().asyncBatcher,
     ...options,
-  } as AsyncBatcherOptions<TValue>
-
+  } as PreactAsyncBatcherOptions<TValue, TSelected>
   const [asyncBatcher] = useState(() => {
     const batcherInstance = new AsyncBatcher<TValue>(
       fn,
@@ -236,6 +265,19 @@ export function useAsyncBatcher<TValue, TSelected = {}>(
   asyncBatcher.fn = fn
   asyncBatcher.setOptions(mergedOptions)
 
+  /* eslint-disable react-hooks/exhaustive-deps -- cleanup only; runs on unmount */
+  useEffect(() => {
+    return () => {
+      if (mergedOptions.onUnmount) {
+        mergedOptions.onUnmount(asyncBatcher)
+      } else {
+        asyncBatcher.cancel()
+        asyncBatcher.abort()
+      }
+    }
+  }, [])
+  /* eslint-enable react-hooks/exhaustive-deps */
+
   const state = useStore(asyncBatcher.store, selector)
 
   return useMemo(

package/src/async-debouncer/useAsyncDebouncedCallback.ts

@@ -1,6 +1,6 @@
 import { useCallback } from 'preact/hooks'
 import { useAsyncDebouncer } from './useAsyncDebouncer'
-import type { AsyncDebouncerOptions } from '@tanstack/pacer/async-debouncer'
+import type { PreactAsyncDebouncerOptions } from './useAsyncDebouncer'
 import type { AnyAsyncFunction } from '@tanstack/pacer/types'
 
 /**
@@ -43,7 +43,7 @@ import type { AnyAsyncFunction } from '@tanstack/pacer/types'
  */
 export function useAsyncDebouncedCallback<TFn extends AnyAsyncFunction>(
   fn: TFn,
-  options: AsyncDebouncerOptions<TFn>,
+  options: PreactAsyncDebouncerOptions<TFn, {}>,
 ): (...args: Parameters<TFn>) => Promise<ReturnType<TFn>> {
   const asyncDebouncedFn = useAsyncDebouncer(fn, options).maybeExecute
   return useCallback(

package/src/async-debouncer/useAsyncDebouncer.ts

@@ -10,6 +10,17 @@ import type {
 } from '@tanstack/pacer/async-debouncer'
 import type { ComponentChildren } from 'preact'
 
+export interface PreactAsyncDebouncerOptions<
+  TFn extends AnyAsyncFunction,
+  TSelected = {},
+> extends AsyncDebouncerOptions<TFn> {
+  /**
+   * Optional callback invoked when the component unmounts. Receives the debouncer instance.
+   * When provided, replaces the default cleanup (cancel + abort); use it to call flush(), reset(), cancel(), add logging, etc.
+   */
+  onUnmount?: (debouncer: PreactAsyncDebouncer<TFn, TSelected>) => void
+}
+
 export interface PreactAsyncDebouncer<
   TFn extends AnyAsyncFunction,
   TSelected = {},
@@ -101,6 +112,24 @@ export interface PreactAsyncDebouncer<
  * - `status`: Current execution status ('disabled' | 'idle' | 'pending' | 'executing' | 'settled')
  * - `successCount`: Number of function executions that have completed successfully
  *
+ * ## Unmount behavior
+ *
+ * By default, the hook cancels any pending execution and aborts any in-flight execution when the component unmounts.
+ * Abort only cancels underlying operations (e.g. fetch) when the abort signal from `getAbortSignal()` is passed to them.
+ * Use the `onUnmount` option to customize this. For example, to flush pending work instead:
+ *
+ * ```tsx
+ * const debouncer = useAsyncDebouncer(fn, {
+ *   wait: 500,
+ *   onUnmount: (d) => d.flush()
+ * });
+ * ```
+ *
+ * Note: For async utils, `flush()` returns a Promise and runs fire-and-forget in the cleanup.
+ * If your debounced function updates Preact state, those updates may run after the component has
+ * unmounted, which can cause "setState on unmounted component" warnings. Guard your callbacks
+ * accordingly when using onUnmount with flush.
+ *
  * @example
  * ```tsx
  * // Default behavior - no reactive state subscriptions
@@ -184,15 +213,14 @@ export interface PreactAsyncDebouncer<
  */
 export function useAsyncDebouncer<TFn extends AnyAsyncFunction, TSelected = {}>(
   fn: TFn,
-  options: AsyncDebouncerOptions<TFn>,
+  options: PreactAsyncDebouncerOptions<TFn, TSelected>,
   selector: (state: AsyncDebouncerState<TFn>) => TSelected = () =>
     ({}) as TSelected,
 ): PreactAsyncDebouncer<TFn, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().asyncDebouncer,
     ...options,
-  } as AsyncDebouncerOptions<TFn>
-
+  } as PreactAsyncDebouncerOptions<TFn, TSelected>
   const [asyncDebouncer] = useState(() => {
     const debouncerInstance = new AsyncDebouncer<TFn>(
       fn,
@@ -218,11 +246,18 @@ export function useAsyncDebouncer<TFn extends AnyAsyncFunction, TSelected = {}>(
 
   const state = useStore(asyncDebouncer.store, selector)
 
+  /* eslint-disable react-hooks/exhaustive-deps -- cleanup only; runs on unmount */
   useEffect(() => {
     return () => {
-      asyncDebouncer.cancel()
+      if (mergedOptions.onUnmount) {
+        mergedOptions.onUnmount(asyncDebouncer)
+      } else {
+        asyncDebouncer.cancel()
+        asyncDebouncer.abort()
+      }
     }
-  }, [asyncDebouncer])
+  }, [])
+  /* eslint-enable react-hooks/exhaustive-deps */
 
   return useMemo(
     () =>

package/src/async-queuer/useAsyncQueuedState.ts

@@ -1,9 +1,9 @@
 import { useAsyncQueuer } from './useAsyncQueuer'
-import type { PreactAsyncQueuer } from './useAsyncQueuer'
 import type {
-  AsyncQueuerOptions,
-  AsyncQueuerState,
-} from '@tanstack/pacer/async-queuer'
+  PreactAsyncQueuer,
+  PreactAsyncQueuerOptions,
+} from './useAsyncQueuer'
+import type { AsyncQueuerState } from '@tanstack/pacer/async-queuer'
 
 /**
  * A higher-level Preact hook that creates an `AsyncQueuer` instance with built-in state management.
@@ -156,7 +156,7 @@ export function useAsyncQueuedState<
   >,
 >(
   fn: (value: TValue) => Promise<any>,
-  options: AsyncQueuerOptions<TValue> = {},
+  options: PreactAsyncQueuerOptions<TValue, TSelected> = {},
   selector?: (state: AsyncQueuerState<TValue>) => TSelected,
 ): [Array<TValue>, PreactAsyncQueuer<TValue, TSelected>] {
   const asyncQueuer = useAsyncQueuer(fn, options, selector)

package/src/async-queuer/useAsyncQueuer.ts

@@ -1,4 +1,4 @@
-import { useMemo, useState } from 'preact/hooks'
+import { useEffect, useMemo, useState } from 'preact/hooks'
 import { AsyncQueuer } from '@tanstack/pacer/async-queuer'
 import { useStore } from '@tanstack/preact-store'
 import { useDefaultPacerOptions } from '../provider/PacerProvider'
@@ -9,6 +9,17 @@ import type {
 } from '@tanstack/pacer/async-queuer'
 import type { ComponentChildren } from 'preact'
 
+export interface PreactAsyncQueuerOptions<
+  TValue,
+  TSelected = {},
+> extends AsyncQueuerOptions<TValue> {
+  /**
+   * Optional callback invoked when the component unmounts. Receives the queuer instance.
+   * When provided, replaces the default cleanup (stop + abort); use it to call flush(), flushAsBatch(), stop(), add logging, etc.
+   */
+  onUnmount?: (queuer: PreactAsyncQueuer<TValue, TSelected>) => void
+}
+
 export interface PreactAsyncQueuer<TValue, TSelected = {}> extends Omit<
   AsyncQueuer<TValue>,
   'store'
@@ -105,6 +116,25 @@ export interface PreactAsyncQueuer<TValue, TSelected = {}> extends Omit<
  * - `status`: Current processing status ('idle' | 'running' | 'stopped')
  * - `successCount`: Number of task executions that have completed successfully
  *
+ * ## Unmount behavior
+ *
+ * By default, the hook stops the queuer and aborts any in-flight task executions when the component unmounts.
+ * Abort only cancels underlying operations (e.g. fetch) when the abort signal from `getAbortSignal()` is passed to them.
+ * Use the `onUnmount` option to customize this. For example, to flush pending items instead:
+ *
+ * ```tsx
+ * const queuer = useAsyncQueuer(fn, {
+ *   concurrency: 2,
+ *   started: false,
+ *   onUnmount: (q) => q.flush()
+ * });
+ * ```
+ *
+ * Note: For async utils, `flush()` returns a Promise and runs fire-and-forget in the cleanup.
+ * If your task function updates Preact state, those updates may run after the component has
+ * unmounted, which can cause "setState on unmounted component" warnings. Guard your callbacks
+ * accordingly when using onUnmount with flush.
+ *
  * @example
  * ```tsx
  * // Default behavior - no reactive state subscriptions
@@ -204,15 +234,14 @@ export interface PreactAsyncQueuer<TValue, TSelected = {}> extends Omit<
  */
 export function useAsyncQueuer<TValue, TSelected = {}>(
   fn: (value: TValue) => Promise<any>,
-  options: AsyncQueuerOptions<TValue> = {},
+  options: PreactAsyncQueuerOptions<TValue, TSelected> = {},
   selector: (state: AsyncQueuerState<TValue>) => TSelected = () =>
     ({}) as TSelected,
 ): PreactAsyncQueuer<TValue, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().asyncQueuer,
     ...options,
-  } as AsyncQueuerOptions<TValue>
-
+  } as PreactAsyncQueuerOptions<TValue, TSelected>
   const [asyncQueuer] = useState(() => {
     const queuerInstance = new AsyncQueuer<TValue>(
       fn,
@@ -236,6 +265,19 @@ export function useAsyncQueuer<TValue, TSelected = {}>(
   asyncQueuer.fn = fn
   asyncQueuer.setOptions(mergedOptions)
 
+  /* eslint-disable react-hooks/exhaustive-deps -- cleanup only; runs on unmount */
+  useEffect(() => {
+    return () => {
+      if (mergedOptions.onUnmount) {
+        mergedOptions.onUnmount(asyncQueuer)
+      } else {
+        asyncQueuer.stop()
+        asyncQueuer.abort()
+      }
+    }
+  }, [])
+  /* eslint-enable react-hooks/exhaustive-deps */
+
   const state = useStore(asyncQueuer.store, selector)
 
   return useMemo(

package/src/async-rate-limiter/useAsyncRateLimitedCallback.ts

@@ -1,7 +1,7 @@
 import { useCallback } from 'preact/hooks'
 import { useAsyncRateLimiter } from './useAsyncRateLimiter'
 import type { AnyAsyncFunction } from '@tanstack/pacer/types'
-import type { AsyncRateLimiterOptions } from '@tanstack/pacer/async-rate-limiter'
+import type { PreactAsyncRateLimiterOptions } from './useAsyncRateLimiter'
 
 /**
  * A Preact hook that creates a rate-limited version of an async callback function.
@@ -58,7 +58,7 @@ import type { AsyncRateLimiterOptions } from '@tanstack/pacer/async-rate-limiter
  */
 export function useAsyncRateLimitedCallback<TFn extends AnyAsyncFunction>(
   fn: TFn,
-  options: AsyncRateLimiterOptions<TFn>,
+  options: PreactAsyncRateLimiterOptions<TFn, {}>,
 ): (...args: Parameters<TFn>) => Promise<ReturnType<TFn>> {
   const asyncRateLimitedFn = useAsyncRateLimiter(fn, options).maybeExecute
   return useCallback(

package/src/async-rate-limiter/useAsyncRateLimiter.ts

@@ -1,4 +1,4 @@
-import { useMemo, useState } from 'preact/hooks'
+import { useEffect, useMemo, useState } from 'preact/hooks'
 import { AsyncRateLimiter } from '@tanstack/pacer/async-rate-limiter'
 import { useStore } from '@tanstack/preact-store'
 import { useDefaultPacerOptions } from '../provider/PacerProvider'
@@ -10,6 +10,17 @@ import type {
 } from '@tanstack/pacer/async-rate-limiter'
 import type { ComponentChildren } from 'preact'
 
+export interface PreactAsyncRateLimiterOptions<
+  TFn extends AnyAsyncFunction,
+  TSelected = {},
+> extends AsyncRateLimiterOptions<TFn> {
+  /**
+   * Optional callback invoked when the component unmounts. Receives the rate limiter instance.
+   * When provided, replaces the default cleanup (abort); use it to call reset(), add logging, etc.
+   */
+  onUnmount?: (rateLimiter: PreactAsyncRateLimiter<TFn, TSelected>) => void
+}
+
 export interface PreactAsyncRateLimiter<
   TFn extends AnyAsyncFunction,
   TSelected = {},
@@ -103,6 +114,12 @@ export interface PreactAsyncRateLimiter<
  * - `settleCount`: Number of function executions that have completed (success or error)
  * - `successCount`: Number of function executions that have completed successfully
  *
+ * ## Unmount behavior
+ *
+ * By default, the hook aborts any in-flight execution when the component unmounts.
+ * Abort only cancels underlying operations (e.g. fetch) when the abort signal from `getAbortSignal()` is passed to them.
+ * Use the `onUnmount` option to customize this.
+ *
  * @example
  * ```tsx
  * // Default behavior - no reactive state subscriptions
@@ -216,14 +233,14 @@ export function useAsyncRateLimiter<
   TSelected = {},
 >(
   fn: TFn,
-  options: AsyncRateLimiterOptions<TFn>,
+  options: PreactAsyncRateLimiterOptions<TFn, TSelected>,
   selector: (state: AsyncRateLimiterState<TFn>) => TSelected = () =>
     ({}) as TSelected,
 ): PreactAsyncRateLimiter<TFn, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().asyncRateLimiter,
     ...options,
-  } as AsyncRateLimiterOptions<TFn>
+  } as PreactAsyncRateLimiterOptions<TFn, TSelected>
 
   const [asyncRateLimiter] = useState(() => {
     const rateLimiterInstance = new AsyncRateLimiter<TFn>(
@@ -248,6 +265,18 @@ export function useAsyncRateLimiter<
   asyncRateLimiter.fn = fn
   asyncRateLimiter.setOptions(mergedOptions)
 
+  /* eslint-disable react-hooks/exhaustive-deps -- cleanup only; runs on unmount */
+  useEffect(() => {
+    return () => {
+      if (mergedOptions.onUnmount) {
+        mergedOptions.onUnmount(asyncRateLimiter)
+      } else {
+        asyncRateLimiter.abort()
+      }
+    }
+  }, [])
+  /* eslint-enable react-hooks/exhaustive-deps */
+
   const state = useStore(asyncRateLimiter.store, selector)
 
   return useMemo(

package/src/async-throttler/useAsyncThrottledCallback.ts

@@ -1,6 +1,6 @@
 import { useCallback } from 'preact/hooks'
 import { useAsyncThrottler } from './useAsyncThrottler'
-import type { AsyncThrottlerOptions } from '@tanstack/pacer/async-throttler'
+import type { PreactAsyncThrottlerOptions } from './useAsyncThrottler'
 import type { AnyAsyncFunction } from '@tanstack/pacer/types'
 
 /**
@@ -41,7 +41,7 @@ import type { AnyAsyncFunction } from '@tanstack/pacer/types'
  */
 export function useAsyncThrottledCallback<TFn extends AnyAsyncFunction>(
   fn: TFn,
-  options: AsyncThrottlerOptions<TFn>,
+  options: PreactAsyncThrottlerOptions<TFn, {}>,
 ): (...args: Parameters<TFn>) => Promise<ReturnType<TFn>> {
   const asyncThrottledFn = useAsyncThrottler(fn, options).maybeExecute
   return useCallback(

package/src/async-throttler/useAsyncThrottler.ts

@@ -10,6 +10,17 @@ import type {
 } from '@tanstack/pacer/async-throttler'
 import type { ComponentChildren } from 'preact'
 
+export interface PreactAsyncThrottlerOptions<
+  TFn extends AnyAsyncFunction,
+  TSelected = {},
+> extends AsyncThrottlerOptions<TFn> {
+  /**
+   * Optional callback invoked when the component unmounts. Receives the throttler instance.
+   * When provided, replaces the default cleanup (cancel + abort); use it to call flush(), reset(), cancel(), add logging, etc.
+   */
+  onUnmount?: (throttler: PreactAsyncThrottler<TFn, TSelected>) => void
+}
+
 export interface PreactAsyncThrottler<
   TFn extends AnyAsyncFunction,
   TSelected = {},
@@ -99,6 +110,24 @@ export interface PreactAsyncThrottler<
  * - `status`: Current execution status ('disabled' | 'idle' | 'pending' | 'executing' | 'settled')
  * - `successCount`: Number of function executions that have completed successfully
  *
+ * ## Unmount behavior
+ *
+ * By default, the hook cancels any pending execution and aborts any in-flight execution when the component unmounts.
+ * Abort only cancels underlying operations (e.g. fetch) when the abort signal from `getAbortSignal()` is passed to them.
+ * Use the `onUnmount` option to customize this. For example, to flush pending work instead:
+ *
+ * ```tsx
+ * const throttler = useAsyncThrottler(fn, {
+ *   wait: 1000,
+ *   onUnmount: (t) => t.flush()
+ * });
+ * ```
+ *
+ * Note: For async utils, `flush()` returns a Promise and runs fire-and-forget in the cleanup.
+ * If your throttled function updates Preact state, those updates may run after the component has
+ * unmounted, which can cause "setState on unmounted component" warnings. Guard your callbacks
+ * accordingly when using onUnmount with flush.
+ *
  * @example
  * ```tsx
  * // Default behavior - no reactive state subscriptions
@@ -195,15 +224,14 @@ export interface PreactAsyncThrottler<
  */
 export function useAsyncThrottler<TFn extends AnyAsyncFunction, TSelected = {}>(
   fn: TFn,
-  options: AsyncThrottlerOptions<TFn>,
+  options: PreactAsyncThrottlerOptions<TFn, TSelected>,
   selector: (state: AsyncThrottlerState<TFn>) => TSelected = () =>
     ({}) as TSelected,
 ): PreactAsyncThrottler<TFn, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().asyncThrottler,
     ...options,
-  } as AsyncThrottlerOptions<TFn>
-
+  } as PreactAsyncThrottlerOptions<TFn, TSelected>
   const [asyncThrottler] = useState(() => {
     const throttlerInstance = new AsyncThrottler<TFn>(
       fn,
@@ -229,9 +257,18 @@ export function useAsyncThrottler<TFn extends AnyAsyncFunction, TSelected = {}>(
 
   const state = useStore(asyncThrottler.store, selector)
 
+  /* eslint-disable react-hooks/exhaustive-deps -- cleanup only; runs on unmount */
   useEffect(() => {
-    return () => asyncThrottler.cancel()
-  }, [asyncThrottler])
+    return () => {
+      if (mergedOptions.onUnmount) {
+        mergedOptions.onUnmount(asyncThrottler)
+      } else {
+        asyncThrottler.cancel()
+        asyncThrottler.abort()
+      }
+    }
+  }, [])
+  /* eslint-enable react-hooks/exhaustive-deps */
 
   return useMemo(
     () =>