@tanstack/solid-pacer 0.18.4 → 0.20.0

package/src/async-throttler/createAsyncThrottler.ts

@@ -1,3 +1,4 @@
+import { createEffect, onCleanup } from 'solid-js'
 import { AsyncThrottler } from '@tanstack/pacer/async-throttler'
 import { useStore } from '@tanstack/solid-store'
 import { useDefaultPacerOptions } from '../provider/PacerProvider'
@@ -9,6 +10,17 @@ import type {
   AsyncThrottlerState,
 } from '@tanstack/pacer/async-throttler'
 
+export interface SolidAsyncThrottlerOptions<
+  TFn extends AnyAsyncFunction,
+  TSelected = {},
+> extends AsyncThrottlerOptions<TFn> {
+  /**
+   * Optional callback invoked when the owning 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: SolidAsyncThrottler<TFn, TSelected>) => void
+}
+
 export interface SolidAsyncThrottler<
   TFn extends AnyAsyncFunction,
   TSelected = {},
@@ -100,6 +112,24 @@ export interface SolidAsyncThrottler<
  * - `nextExecutionTime`: Timestamp of the next allowed execution
  * - `status`: Current execution status ('disabled' | 'idle' | 'pending' | 'executing')
  *
+ * ## Unmount behavior
+ *
+ * By default, the primitive cancels any pending execution and aborts any in-flight execution when the owning 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 = createAsyncThrottler(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 Solid signals, those updates may run after the component has
+ * unmounted, which can cause unexpected reactive updates. Guard your callbacks accordingly when
+ * using onUnmount with flush.
+ *
  * @example
  * ```tsx
  * // Default behavior - no reactive state subscriptions
@@ -147,15 +177,14 @@ export function createAsyncThrottler<
   TSelected = {},
 >(
   fn: TFn,
-  options: AsyncThrottlerOptions<TFn>,
+  options: SolidAsyncThrottlerOptions<TFn, TSelected>,
   selector: (state: AsyncThrottlerState<TFn>) => TSelected = () =>
     ({}) as TSelected,
 ): SolidAsyncThrottler<TFn, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().asyncThrottler,
     ...options,
-  } as AsyncThrottlerOptions<TFn>
-
+  } as SolidAsyncThrottlerOptions<TFn, TSelected>
   const asyncThrottler = new AsyncThrottler(
     fn,
     mergedOptions,
@@ -174,6 +203,17 @@ export function createAsyncThrottler<
 
   const state = useStore(asyncThrottler.store, selector)
 
+  createEffect(() => {
+    onCleanup(() => {
+      if (mergedOptions.onUnmount) {
+        mergedOptions.onUnmount(asyncThrottler)
+      } else {
+        asyncThrottler.cancel()
+        asyncThrottler.abort()
+      }
+    })
+  })
+
   return {
     ...asyncThrottler,
     state,

package/src/batcher/createBatcher.ts

@@ -1,10 +1,22 @@
 import { Batcher } from '@tanstack/pacer/batcher'
 import { useStore } from '@tanstack/solid-store'
+import { createEffect, onCleanup } from 'solid-js'
 import { useDefaultPacerOptions } from '../provider/PacerProvider'
 import type { Store } from '@tanstack/solid-store'
 import type { Accessor, JSX } from 'solid-js'
 import type { BatcherOptions, BatcherState } from '@tanstack/pacer/batcher'
 
+export interface SolidBatcherOptions<
+  TValue,
+  TSelected = {},
+> extends BatcherOptions<TValue> {
+  /**
+   * Optional callback invoked when the owning component unmounts. Receives the batcher instance.
+   * When provided, replaces the default cleanup (cancel); use it to call flush(), reset(), cancel(), add logging, etc.
+   */
+  onUnmount?: (batcher: SolidBatcher<TValue, TSelected>) => void
+}
+
 export interface SolidBatcher<TValue, TSelected = {}> extends Omit<
   Batcher<TValue>,
   'store'
@@ -82,6 +94,19 @@ export interface SolidBatcher<TValue, TSelected = {}> extends Omit<
  * - `items`: Array of items currently queued for batching
  * - `totalItemsProcessed`: Total number of individual items that have been processed across all batches
  *
+ * ## Unmount behavior
+ *
+ * By default, the primitive cancels any pending batch when the owning component unmounts.
+ * Use the `onUnmount` option to customize this. For example, to flush pending work instead:
+ *
+ * ```tsx
+ * const batcher = createBatcher(fn, {
+ *   maxSize: 10,
+ *   wait: 2000,
+ *   onUnmount: (b) => b.flush()
+ * });
+ * ```
+ *
  * Example usage:
  * ```tsx
  * // Default behavior - no reactive state subscriptions
@@ -129,15 +154,14 @@ export interface SolidBatcher<TValue, TSelected = {}> extends Omit<
  */
 export function createBatcher<TValue, TSelected = {}>(
   fn: (items: Array<TValue>) => void,
-  options: BatcherOptions<TValue> = {},
+  options: SolidBatcherOptions<TValue, TSelected> = {},
   selector: (state: BatcherState<TValue>) => TSelected = () =>
     ({}) as TSelected,
 ): SolidBatcher<TValue, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().batcher,
     ...options,
-  } as BatcherOptions<TValue>
-
+  } as SolidBatcherOptions<TValue, TSelected>
   const batcher = new Batcher(fn, mergedOptions) as unknown as SolidBatcher<
     TValue,
     TSelected
@@ -155,6 +179,17 @@ export function createBatcher<TValue, TSelected = {}>(
   }
 
   const state = useStore(batcher.store, selector)
+
+  createEffect(() => {
+    onCleanup(() => {
+      if (mergedOptions.onUnmount) {
+        mergedOptions.onUnmount(batcher)
+      } else {
+        batcher.cancel()
+      }
+    })
+  })
+
   return {
     ...batcher,
     state,

package/src/debouncer/createDebouncedSignal.ts

@@ -1,11 +1,8 @@
 import { createSignal } from 'solid-js'
 import { createDebouncer } from './createDebouncer'
-import type { SolidDebouncer } from './createDebouncer'
+import type { SolidDebouncer, SolidDebouncerOptions } from './createDebouncer'
 import type { Accessor, Setter } from 'solid-js'
-import type {
-  DebouncerOptions,
-  DebouncerState,
-} from '@tanstack/pacer/debouncer'
+import type { DebouncerState } from '@tanstack/pacer/debouncer'
 
 /**
  * A Solid hook that creates a debounced state value, combining Solid's createSignal with debouncing functionality.
@@ -80,7 +77,7 @@ import type {
  */
 export function createDebouncedSignal<TValue, TSelected = {}>(
   value: TValue,
-  initialOptions: DebouncerOptions<Setter<TValue>>,
+  initialOptions: SolidDebouncerOptions<Setter<TValue>, TSelected>,
   selector?: (state: DebouncerState<Setter<TValue>>) => TSelected,
 ): [
   Accessor<TValue>,

package/src/debouncer/createDebouncedValue.ts

@@ -1,11 +1,8 @@
 import { createEffect } from 'solid-js'
 import { createDebouncedSignal } from './createDebouncedSignal'
-import type { SolidDebouncer } from './createDebouncer'
+import type { SolidDebouncer, SolidDebouncerOptions } from './createDebouncer'
 import type { Accessor, Setter } from 'solid-js'
-import type {
-  DebouncerOptions,
-  DebouncerState,
-} from '@tanstack/pacer/debouncer'
+import type { DebouncerState } from '@tanstack/pacer/debouncer'
 
 /**
  * A Solid hook that creates a debounced value that updates only after a specified delay.
@@ -71,7 +68,7 @@ import type {
  */
 export function createDebouncedValue<TValue, TSelected = {}>(
   value: Accessor<TValue>,
-  initialOptions: DebouncerOptions<Setter<TValue>>,
+  initialOptions: SolidDebouncerOptions<Setter<TValue>, TSelected>,
   selector?: (state: DebouncerState<Setter<TValue>>) => TSelected,
 ): [Accessor<TValue>, SolidDebouncer<Setter<TValue>, TSelected>] {
   const [debouncedValue, setDebouncedValue, debouncer] = createDebouncedSignal(

package/src/debouncer/createDebouncer.ts

@@ -10,6 +10,17 @@ import type {
   DebouncerState,
 } from '@tanstack/pacer/debouncer'
 
+export interface SolidDebouncerOptions<
+  TFn extends AnyFunction,
+  TSelected = {},
+> extends DebouncerOptions<TFn> {
+  /**
+   * Optional callback invoked when the owning 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: SolidDebouncer<TFn, TSelected>) => void
+}
+
 export interface SolidDebouncer<
   TFn extends AnyFunction,
   TSelected = {},
@@ -88,6 +99,18 @@ export interface SolidDebouncer<
  * - `lastArgs`: The arguments from the most recent call to maybeExecute
  * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
  *
+ * ## Unmount behavior
+ *
+ * By default, the primitive cancels any pending execution when the owning component unmounts.
+ * Use the `onUnmount` option to customize this. For example, to flush pending work instead:
+ *
+ * ```tsx
+ * const debouncer = createDebouncer(fn, {
+ *   wait: 500,
+ *   onUnmount: (d) => d.flush()
+ * });
+ * ```
+ *
  * @example
  * ```tsx
  * // Default behavior - no reactive state subscriptions
@@ -132,14 +155,13 @@ export interface SolidDebouncer<
  */
 export function createDebouncer<TFn extends AnyFunction, TSelected = {}>(
   fn: TFn,
-  options: DebouncerOptions<TFn>,
+  options: SolidDebouncerOptions<TFn, TSelected>,
   selector: (state: DebouncerState<TFn>) => TSelected = () => ({}) as TSelected,
 ): SolidDebouncer<TFn, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().debouncer,
     ...options,
-  } as DebouncerOptions<TFn>
-
+  } as SolidDebouncerOptions<TFn, TSelected>
   const asyncDebouncer = new Debouncer<TFn>(
     fn,
     mergedOptions,
@@ -160,7 +182,11 @@ export function createDebouncer<TFn extends AnyFunction, TSelected = {}>(
 
   createEffect(() => {
     onCleanup(() => {
-      asyncDebouncer.cancel()
+      if (mergedOptions.onUnmount) {
+        mergedOptions.onUnmount(asyncDebouncer)
+      } else {
+        asyncDebouncer.cancel()
+      }
     })
   })
 

package/src/queuer/createQueuedSignal.ts

@@ -1,6 +1,6 @@
 import { createQueuer } from './createQueuer'
-import type { SolidQueuer } from './createQueuer'
-import type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
+import type { SolidQueuer, SolidQueuerOptions } from './createQueuer'
+import type { QueuerState } from '@tanstack/pacer/queuer'
 
 /**
  * A Solid primitive that creates a queuer with managed state, combining Solid's signals with queuing functionality.
@@ -124,7 +124,7 @@ export function createQueuedSignal<
   >,
 >(
   fn: (item: TValue) => void,
-  options: QueuerOptions<TValue> = {},
+  options: SolidQueuerOptions<TValue, TSelected> = {},
   selector: (state: QueuerState<TValue>) => TSelected = (state) =>
     ({ items: state.items }) as TSelected,
 ): [

package/src/queuer/createQueuer.ts

@@ -1,10 +1,22 @@
 import { Queuer } from '@tanstack/pacer/queuer'
 import { useStore } from '@tanstack/solid-store'
+import { createEffect, onCleanup } from 'solid-js'
 import { useDefaultPacerOptions } from '../provider/PacerProvider'
 import type { Store } from '@tanstack/solid-store'
 import type { Accessor, JSX } from 'solid-js'
 import type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
 
+export interface SolidQueuerOptions<
+  TValue,
+  TSelected = {},
+> extends QueuerOptions<TValue> {
+  /**
+   * Optional callback invoked when the owning 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: SolidQueuer<TValue, TSelected>) => void
+}
+
 export interface SolidQueuer<TValue, TSelected = {}> extends Omit<
   Queuer<TValue>,
   'store'
@@ -84,6 +96,19 @@ export interface SolidQueuer<TValue, TSelected = {}> extends Omit<
  * - `items`: Array of items currently queued for processing
  * - `rejectionCount`: Number of items that were rejected (expired or failed validation)
  *
+ * ## Unmount behavior
+ *
+ * By default, the primitive stops the queuer when the owning component unmounts.
+ * Use the `onUnmount` option to customize this. For example, to flush pending items instead:
+ *
+ * ```tsx
+ * const queue = createQueuer(fn, {
+ *   started: true,
+ *   wait: 1000,
+ *   onUnmount: (q) => q.flush()
+ * });
+ * ```
+ *
  * Example usage:
  * ```tsx
  * // Default behavior - no reactive state subscriptions
@@ -130,14 +155,13 @@ export interface SolidQueuer<TValue, TSelected = {}> extends Omit<
  */
 export function createQueuer<TValue, TSelected = {}>(
   fn: (item: TValue) => void,
-  options: QueuerOptions<TValue> = {},
+  options: SolidQueuerOptions<TValue, TSelected> = {},
   selector: (state: QueuerState<TValue>) => TSelected = () => ({}) as TSelected,
 ): SolidQueuer<TValue, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().queuer,
     ...options,
-  } as QueuerOptions<TValue>
-
+  } as SolidQueuerOptions<TValue, TSelected>
   const queuer = new Queuer(fn, mergedOptions) as unknown as SolidQueuer<
     TValue,
     TSelected
@@ -156,6 +180,16 @@ export function createQueuer<TValue, TSelected = {}>(
 
   const state = useStore(queuer.store, selector)
 
+  createEffect(() => {
+    onCleanup(() => {
+      if (mergedOptions.onUnmount) {
+        mergedOptions.onUnmount(queuer)
+      } else {
+        queuer.stop()
+      }
+    })
+  })
+
   return {
     ...queuer,
     state,

package/src/rate-limiter/createRateLimitedSignal.ts

@@ -1,11 +1,11 @@
 import { createSignal } from 'solid-js'
 import { createRateLimiter } from './createRateLimiter'
-import type { SolidRateLimiter } from './createRateLimiter'
-import type { Accessor, Setter } from 'solid-js'
 import type {
-  RateLimiterOptions,
-  RateLimiterState,
-} from '@tanstack/pacer/rate-limiter'
+  SolidRateLimiter,
+  SolidRateLimiterOptions,
+} from './createRateLimiter'
+import type { Accessor, Setter } from 'solid-js'
+import type { RateLimiterState } from '@tanstack/pacer/rate-limiter'
 
 /**
  * A Solid hook that creates a rate-limited state value that enforces a hard limit on state updates within a time window.
@@ -94,7 +94,7 @@ import type {
  */
 export function createRateLimitedSignal<TValue, TSelected = {}>(
   value: TValue,
-  initialOptions: RateLimiterOptions<Setter<TValue>>,
+  initialOptions: SolidRateLimiterOptions<Setter<TValue>, TSelected>,
   selector?: (state: RateLimiterState) => TSelected,
 ): [
   Accessor<TValue>,

package/src/rate-limiter/createRateLimitedValue.ts

@@ -1,11 +1,11 @@
 import { createEffect } from 'solid-js'
 import { createRateLimitedSignal } from './createRateLimitedSignal'
-import type { SolidRateLimiter } from './createRateLimiter'
-import type { Accessor, Setter } from 'solid-js'
 import type {
-  RateLimiterOptions,
-  RateLimiterState,
-} from '@tanstack/pacer/rate-limiter'
+  SolidRateLimiter,
+  SolidRateLimiterOptions,
+} from './createRateLimiter'
+import type { Accessor, Setter } from 'solid-js'
+import type { RateLimiterState } from '@tanstack/pacer/rate-limiter'
 
 /**
  * A high-level Solid 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 createRateLimitedValue<TValue, TSelected = {}>(
   value: Accessor<TValue>,
-  initialOptions: RateLimiterOptions<Setter<TValue>>,
+  initialOptions: SolidRateLimiterOptions<Setter<TValue>, TSelected>,
   selector?: (state: RateLimiterState) => TSelected,
 ): [Accessor<TValue>, SolidRateLimiter<Setter<TValue>, TSelected>] {
   const [rateLimitedValue, setRateLimitedValue, rateLimiter] =

package/src/rate-limiter/createRateLimiter.ts

@@ -1,4 +1,5 @@
 import { RateLimiter } from '@tanstack/pacer/rate-limiter'
+import { createEffect, onCleanup } from 'solid-js'
 import { useStore } from '@tanstack/solid-store'
 import { useDefaultPacerOptions } from '../provider/PacerProvider'
 import type { Store } from '@tanstack/solid-store'
@@ -9,6 +10,17 @@ import type {
   RateLimiterState,
 } from '@tanstack/pacer/rate-limiter'
 
+export interface SolidRateLimiterOptions<
+  TFn extends AnyFunction,
+  TSelected = {},
+> extends RateLimiterOptions<TFn> {
+  /**
+   * Optional callback invoked when the owning component unmounts. Receives the rate limiter instance.
+   * When provided, replaces the default cleanup; use it to call reset(), add logging, etc.
+   */
+  onUnmount?: (rateLimiter: SolidRateLimiter<TFn, TSelected>) => void
+}
+
 export interface SolidRateLimiter<
   TFn extends AnyFunction,
   TSelected = {},
@@ -172,14 +184,13 @@ export interface SolidRateLimiter<
  */
 export function createRateLimiter<TFn extends AnyFunction, TSelected = {}>(
   fn: TFn,
-  options: RateLimiterOptions<TFn>,
+  options: SolidRateLimiterOptions<TFn, TSelected>,
   selector: (state: RateLimiterState) => TSelected = () => ({}) as TSelected,
 ): SolidRateLimiter<TFn, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().rateLimiter,
     ...options,
-  } as RateLimiterOptions<TFn>
-
+  } as SolidRateLimiterOptions<TFn, TSelected>
   const rateLimiter = new RateLimiter<TFn>(
     fn,
     mergedOptions,
@@ -198,6 +209,14 @@ export function createRateLimiter<TFn extends AnyFunction, TSelected = {}>(
 
   const state = useStore(rateLimiter.store, selector)
 
+  createEffect(() => {
+    onCleanup(() => {
+      if (mergedOptions.onUnmount) {
+        mergedOptions.onUnmount(rateLimiter)
+      }
+    })
+  })
+
   return {
     ...rateLimiter,
     state,

package/src/throttler/createThrottledSignal.ts

@@ -1,11 +1,8 @@
 import { createSignal } from 'solid-js'
 import { createThrottler } from './createThrottler'
-import type { SolidThrottler } from './createThrottler'
+import type { SolidThrottler, SolidThrottlerOptions } from './createThrottler'
 import type { Accessor, Setter } from 'solid-js'
-import type {
-  ThrottlerOptions,
-  ThrottlerState,
-} from '@tanstack/pacer/throttler'
+import type { ThrottlerState } from '@tanstack/pacer/throttler'
 
 /**
  * A Solid hook that creates a throttled state value that updates at most once within a specified time window.
@@ -71,7 +68,7 @@ import type {
  */
 export function createThrottledSignal<TValue, TSelected = {}>(
   value: TValue,
-  initialOptions: ThrottlerOptions<Setter<TValue>>,
+  initialOptions: SolidThrottlerOptions<Setter<TValue>, TSelected>,
   selector?: (state: ThrottlerState<Setter<TValue>>) => TSelected,
 ): [
   Accessor<TValue>,

package/src/throttler/createThrottledValue.ts

@@ -1,11 +1,8 @@
 import { createEffect } from 'solid-js'
 import { createThrottledSignal } from './createThrottledSignal'
-import type { SolidThrottler } from './createThrottler'
+import type { SolidThrottler, SolidThrottlerOptions } from './createThrottler'
 import type { Accessor, Setter } from 'solid-js'
-import type {
-  ThrottlerOptions,
-  ThrottlerState,
-} from '@tanstack/pacer/throttler'
+import type { ThrottlerState } from '@tanstack/pacer/throttler'
 
 /**
  * A high-level Solid hook that creates a throttled version of a value that updates at most once within a specified time window.
@@ -68,7 +65,7 @@ import type {
  */
 export function createThrottledValue<TValue, TSelected = {}>(
   value: Accessor<TValue>,
-  initialOptions: ThrottlerOptions<Setter<TValue>>,
+  initialOptions: SolidThrottlerOptions<Setter<TValue>, TSelected>,
   selector?: (state: ThrottlerState<Setter<TValue>>) => TSelected,
 ): [Accessor<TValue>, SolidThrottler<Setter<TValue>, TSelected>] {
   const [throttledValue, setThrottledValue, throttler] = createThrottledSignal(

package/src/throttler/createThrottler.ts

@@ -10,6 +10,17 @@ import type {
   ThrottlerState,
 } from '@tanstack/pacer/throttler'
 
+export interface SolidThrottlerOptions<
+  TFn extends AnyFunction,
+  TSelected = {},
+> extends ThrottlerOptions<TFn> {
+  /**
+   * Optional callback invoked when the owning 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: SolidThrottler<TFn, TSelected>) => void
+}
+
 export interface SolidThrottler<
   TFn extends AnyFunction,
   TSelected = {},
@@ -87,6 +98,18 @@ export interface SolidThrottler<
  * - `nextExecutionTime`: Timestamp of the next allowed execution
  * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
  *
+ * ## Unmount behavior
+ *
+ * By default, the primitive cancels any pending execution when the owning component unmounts.
+ * Use the `onUnmount` option to customize this. For example, to flush pending work instead:
+ *
+ * ```tsx
+ * const throttler = createThrottler(fn, {
+ *   wait: 1000,
+ *   onUnmount: (t) => t.flush()
+ * });
+ * ```
+ *
  * @example
  * ```tsx
  * // Default behavior - no reactive state subscriptions
@@ -135,14 +158,13 @@ export interface SolidThrottler<
  */
 export function createThrottler<TFn extends AnyFunction, TSelected = {}>(
   fn: TFn,
-  options: ThrottlerOptions<TFn>,
+  options: SolidThrottlerOptions<TFn, TSelected>,
   selector: (state: ThrottlerState<TFn>) => TSelected = () => ({}) as TSelected,
 ): SolidThrottler<TFn, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().throttler,
     ...options,
-  } as ThrottlerOptions<TFn>
-
+  } as SolidThrottlerOptions<TFn, TSelected>
   const asyncThrottler = new Throttler<TFn>(
     fn,
     mergedOptions,
@@ -163,7 +185,11 @@ export function createThrottler<TFn extends AnyFunction, TSelected = {}>(
 
   createEffect(() => {
     onCleanup(() => {
-      asyncThrottler.cancel()
+      if (mergedOptions.onUnmount) {
+        mergedOptions.onUnmount(asyncThrottler)
+      } else {
+        asyncThrottler.cancel()
+      }
     })
   })