@tanstack/angular-pacer 0.20.0 → 0.21.0

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

@@ -1,14 +1,26 @@
+import { DestroyRef, inject } from '@angular/core'
 import { injectStore } from '@tanstack/angular-store'
 import { AsyncRateLimiter } from '@tanstack/pacer/async-rate-limiter'
 import { injectPacerOptions } from '../provider/pacer-context'
 import type { Signal } from '@angular/core'
-import type { Store } from '@tanstack/store'
+import type { Store } from '@tanstack/angular-store'
 import type { AnyAsyncFunction } from '@tanstack/pacer/types'
 import type {
   AsyncRateLimiterOptions,
   AsyncRateLimiterState,
 } from '@tanstack/pacer/async-rate-limiter'
 
+export interface AngularAsyncRateLimiterOptions<
+  TFn extends AnyAsyncFunction,
+  TSelected = {},
+> extends AsyncRateLimiterOptions<TFn> {
+  /**
+   * Optional callback invoked when the component is destroyed. Receives the rate limiter instance.
+   * When provided, replaces the default cleanup (abort).
+   */
+  onUnmount?: (rateLimiter: AngularAsyncRateLimiter<TFn, TSelected>) => void
+}
+
 export interface AngularAsyncRateLimiter<
   TFn extends AnyAsyncFunction,
   TSelected = {},
@@ -45,6 +57,11 @@ export interface AngularAsyncRateLimiter<
  * tracking by providing a selector function. This prevents unnecessary updates and gives you
  * full control over when your component tracks state changes.
  *
+ * ## Cleanup on Destroy
+ *
+ * By default, the function aborts in-flight work when the component is destroyed.
+ * Use the `onUnmount` option to customize this.
+ *
  * @example
  * ```ts
  * // Default behavior - no reactive state subscriptions
@@ -68,20 +85,31 @@ export function injectAsyncRateLimiter<
   TSelected = {},
 >(
   fn: TFn,
-  options: AsyncRateLimiterOptions<TFn>,
+  options: AngularAsyncRateLimiterOptions<TFn, TSelected>,
   selector: (state: AsyncRateLimiterState<TFn>) => TSelected = () =>
     ({}) as TSelected,
 ): AngularAsyncRateLimiter<TFn, TSelected> {
   const mergedOptions = {
     ...injectPacerOptions().asyncRateLimiter,
     ...options,
-  } as AsyncRateLimiterOptions<TFn>
+  } as AngularAsyncRateLimiterOptions<TFn, TSelected>
 
   const rateLimiter = new AsyncRateLimiter<TFn>(fn, mergedOptions)
   const state = injectStore(rateLimiter.store, selector)
 
-  return {
+  const result = {
     ...rateLimiter,
     state,
   } as AngularAsyncRateLimiter<TFn, TSelected>
+
+  const destroyRef = inject(DestroyRef, { optional: true })
+  destroyRef?.onDestroy(() => {
+    if (mergedOptions.onUnmount) {
+      mergedOptions.onUnmount(result)
+    } else {
+      rateLimiter.abort()
+    }
+  })
+
+  return result
 }

package/src/async-throttler/injectAsyncThrottler.ts

@@ -1,14 +1,27 @@
+import { DestroyRef, inject } from '@angular/core'
 import { injectStore } from '@tanstack/angular-store'
 import { AsyncThrottler } from '@tanstack/pacer/async-throttler'
 import { injectPacerOptions } from '../provider/pacer-context'
 import type { Signal } from '@angular/core'
-import type { Store } from '@tanstack/store'
+import type { Store } from '@tanstack/angular-store'
 import type { AnyAsyncFunction } from '@tanstack/pacer/types'
 import type {
   AsyncThrottlerOptions,
   AsyncThrottlerState,
 } from '@tanstack/pacer/async-throttler'
 
+export interface AngularAsyncThrottlerOptions<
+  TFn extends AnyAsyncFunction,
+  TSelected = {},
+> extends AsyncThrottlerOptions<TFn> {
+  /**
+   * Optional callback invoked when the component is destroyed. Receives the throttler instance.
+   * When provided, replaces the default cleanup (cancel + abort); use it to call flush(), cancel(), add logging, etc.
+   * When using onUnmount with flush, guard your callbacks since the component may already be destroyed.
+   */
+  onUnmount?: (throttler: AngularAsyncThrottler<TFn, TSelected>) => void
+}
+
 export interface AngularAsyncThrottler<
   TFn extends AnyAsyncFunction,
   TSelected = {},
@@ -47,6 +60,20 @@ export interface AngularAsyncThrottler<
  * tracking by providing a selector function. This prevents unnecessary updates and gives you
  * full control over when your component tracks state changes.
  *
+ * ## Cleanup on Destroy
+ *
+ * By default, the function cancels any pending execution and aborts in-flight work when the component is destroyed.
+ * Use the `onUnmount` option to customize this. For example, to flush pending work instead:
+ *
+ * ```ts
+ * const throttler = injectAsyncThrottler(fn, {
+ *   wait: 1000,
+ *   onUnmount: (t) => t.flush()
+ * });
+ * ```
+ *
+ * When using onUnmount with flush, guard your callbacks since the component may already be destroyed.
+ *
  * @example
  * ```ts
  * // Default behavior - no reactive state subscriptions
@@ -73,20 +100,32 @@ export function injectAsyncThrottler<
   TSelected = {},
 >(
   fn: TFn,
-  options: AsyncThrottlerOptions<TFn>,
+  options: AngularAsyncThrottlerOptions<TFn, TSelected>,
   selector: (state: AsyncThrottlerState<TFn>) => TSelected = () =>
     ({}) as TSelected,
 ): AngularAsyncThrottler<TFn, TSelected> {
   const mergedOptions = {
     ...injectPacerOptions().asyncThrottler,
     ...options,
-  } as AsyncThrottlerOptions<TFn>
+  } as AngularAsyncThrottlerOptions<TFn, TSelected>
 
   const throttler = new AsyncThrottler<TFn>(fn, mergedOptions)
   const state = injectStore(throttler.store, selector)
 
-  return {
+  const result = {
     ...throttler,
     state,
   } as AngularAsyncThrottler<TFn, TSelected>
+
+  const destroyRef = inject(DestroyRef, { optional: true })
+  destroyRef?.onDestroy(() => {
+    if (mergedOptions.onUnmount) {
+      mergedOptions.onUnmount(result)
+    } else {
+      throttler.cancel()
+      throttler.abort()
+    }
+  })
+
+  return result
 }

package/src/batcher/injectBatcher.ts

@@ -1,10 +1,22 @@
+import { DestroyRef, inject } from '@angular/core'
 import { injectStore } from '@tanstack/angular-store'
 import { Batcher } from '@tanstack/pacer/batcher'
 import { injectPacerOptions } from '../provider/pacer-context'
 import type { Signal } from '@angular/core'
-import type { Store } from '@tanstack/store'
+import type { Store } from '@tanstack/angular-store'
 import type { BatcherOptions, BatcherState } from '@tanstack/pacer/batcher'
 
+export interface AngularBatcherOptions<
+  TValue,
+  TSelected = {},
+> extends BatcherOptions<TValue> {
+  /**
+   * Optional callback invoked when the component is destroyed. Receives the batcher instance.
+   * When provided, replaces the default cleanup (cancel); use it to call flush(), cancel(), add logging, etc.
+   */
+  onUnmount?: (batcher: AngularBatcher<TValue, TSelected>) => void
+}
+
 export interface AngularBatcher<TValue, TSelected = {}> extends Omit<
   Batcher<TValue>,
   'store'
@@ -43,6 +55,18 @@ export interface AngularBatcher<TValue, TSelected = {}> extends Omit<
  * tracking by providing a selector function. This prevents unnecessary updates and gives you
  * full control over when your component tracks state changes.
  *
+ * ## Cleanup on Destroy
+ *
+ * By default, the function cancels any pending batch when the component is destroyed.
+ * Use the `onUnmount` option to customize this. For example, to flush pending work instead:
+ *
+ * ```ts
+ * const batcher = injectBatcher(fn, {
+ *   maxSize: 5,
+ *   onUnmount: (b) => b.flush()
+ * });
+ * ```
+ *
  * @example
  * ```ts
  * // Default behavior - no reactive state subscriptions
@@ -60,20 +84,31 @@ export interface AngularBatcher<TValue, TSelected = {}> extends Omit<
  */
 export function injectBatcher<TValue, TSelected = {}>(
   fn: (items: Array<TValue>) => void,
-  options: BatcherOptions<TValue> = {},
+  options: AngularBatcherOptions<TValue, TSelected> = {},
   selector: (state: BatcherState<TValue>) => TSelected = () =>
     ({}) as TSelected,
 ): AngularBatcher<TValue, TSelected> {
   const mergedOptions = {
     ...injectPacerOptions().batcher,
     ...options,
-  } as BatcherOptions<TValue>
+  } as AngularBatcherOptions<TValue, TSelected>
 
   const batcher = new Batcher<TValue>(fn, mergedOptions)
   const state = injectStore(batcher.store, selector)
 
-  return {
+  const result = {
     ...batcher,
     state,
   } as AngularBatcher<TValue, TSelected>
+
+  const destroyRef = inject(DestroyRef, { optional: true })
+  destroyRef?.onDestroy(() => {
+    if (mergedOptions.onUnmount) {
+      mergedOptions.onUnmount(result)
+    } else {
+      batcher.cancel()
+    }
+  })
+
+  return result
 }

package/src/debouncer/injectDebouncer.ts

@@ -1,14 +1,26 @@
+import { DestroyRef, inject } from '@angular/core'
 import { injectStore } from '@tanstack/angular-store'
 import { Debouncer } from '@tanstack/pacer/debouncer'
 import { injectPacerOptions } from '../provider/pacer-context'
 import type { Signal } from '@angular/core'
-import type { Store } from '@tanstack/store'
+import type { Store } from '@tanstack/angular-store'
 import type { AnyFunction } from '@tanstack/pacer/types'
 import type {
   DebouncerOptions,
   DebouncerState,
 } from '@tanstack/pacer/debouncer'
 
+export interface AngularDebouncerOptions<
+  TFn extends AnyFunction,
+  TSelected = {},
+> extends DebouncerOptions<TFn> {
+  /**
+   * Optional callback invoked when the component is destroyed. Receives the debouncer instance.
+   * When provided, replaces the default cleanup (cancel); use it to call flush(), cancel(), add logging, etc.
+   */
+  onUnmount?: (debouncer: AngularDebouncer<TFn, TSelected>) => void
+}
+
 export interface AngularDebouncer<
   TFn extends AnyFunction,
   TSelected = {},
@@ -57,6 +69,18 @@ export interface AngularDebouncer<
  * - `lastArgs`: The arguments from the most recent call to maybeExecute
  * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
  *
+ * ## Cleanup on Destroy
+ *
+ * By default, the function cancels any pending execution when the component is destroyed.
+ * Use the `onUnmount` option to customize this. For example, to flush pending work instead:
+ *
+ * ```ts
+ * const debouncer = injectDebouncer(fn, {
+ *   wait: 500,
+ *   onUnmount: (d) => d.flush()
+ * });
+ * ```
+ *
  * @example
  * ```ts
  * // Default behavior - no reactive state subscriptions
@@ -84,19 +108,30 @@ export interface AngularDebouncer<
  */
 export function injectDebouncer<TFn extends AnyFunction, TSelected = {}>(
   fn: TFn,
-  options: DebouncerOptions<TFn>,
+  options: AngularDebouncerOptions<TFn, TSelected>,
   selector: (state: DebouncerState<TFn>) => TSelected = () => ({}) as TSelected,
 ): AngularDebouncer<TFn, TSelected> {
   const mergedOptions = {
     ...injectPacerOptions().debouncer,
     ...options,
-  } as DebouncerOptions<TFn>
+  } as AngularDebouncerOptions<TFn, TSelected>
 
   const debouncer = new Debouncer<TFn>(fn, mergedOptions)
   const state = injectStore(debouncer.store, selector)
 
-  return {
+  const result = {
     ...debouncer,
     state,
   } as AngularDebouncer<TFn, TSelected>
+
+  const destroyRef = inject(DestroyRef, { optional: true })
+  destroyRef?.onDestroy(() => {
+    if (mergedOptions.onUnmount) {
+      mergedOptions.onUnmount(result)
+    } else {
+      debouncer.cancel()
+    }
+  })
+
+  return result
 }

package/src/queuer/injectQueuer.ts

@@ -1,10 +1,22 @@
+import { DestroyRef, inject } from '@angular/core'
 import { injectStore } from '@tanstack/angular-store'
 import { Queuer } from '@tanstack/pacer/queuer'
 import { injectPacerOptions } from '../provider/pacer-context'
 import type { Signal } from '@angular/core'
-import type { Store } from '@tanstack/store'
+import type { Store } from '@tanstack/angular-store'
 import type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
 
+export interface AngularQueuerOptions<
+  TValue,
+  TSelected = {},
+> extends QueuerOptions<TValue> {
+  /**
+   * Optional callback invoked when the component is destroyed. Receives the queuer instance.
+   * When provided, replaces the default cleanup (stop); use it to call flush(), stop(), add logging, etc.
+   */
+  onUnmount?: (queuer: AngularQueuer<TValue, TSelected>) => void
+}
+
 export interface AngularQueuer<TValue, TSelected = {}> extends Omit<
   Queuer<TValue>,
   'store'
@@ -62,22 +74,45 @@ export interface AngularQueuer<TValue, TSelected = {}> extends Omit<
  * // Access the selected state
  * const { items, isRunning } = queue.state();
  * ```
+ *
+ * ## Cleanup on Destroy
+ *
+ * By default, the function stops the queuer when the component is destroyed.
+ * Use the `onUnmount` option to customize this. For example, to flush pending items instead:
+ *
+ * ```ts
+ * const queue = injectQueuer(fn, {
+ *   started: true,
+ *   onUnmount: (q) => q.flush()
+ * });
+ * ```
  */
 export function injectQueuer<TValue, TSelected = {}>(
   fn: (item: TValue) => void,
-  options: QueuerOptions<TValue> = {},
+  options: AngularQueuerOptions<TValue, TSelected> = {},
   selector: (state: QueuerState<TValue>) => TSelected = () => ({}) as TSelected,
 ): AngularQueuer<TValue, TSelected> {
   const mergedOptions = {
     ...injectPacerOptions().queuer,
     ...options,
-  } as QueuerOptions<TValue>
+  } as AngularQueuerOptions<TValue, TSelected>
 
   const queuer = new Queuer<TValue>(fn, mergedOptions)
   const state = injectStore(queuer.store, selector)
 
-  return {
+  const result = {
     ...queuer,
     state,
   } as AngularQueuer<TValue, TSelected>
+
+  const destroyRef = inject(DestroyRef, { optional: true })
+  destroyRef?.onDestroy(() => {
+    if (mergedOptions.onUnmount) {
+      mergedOptions.onUnmount(result)
+    } else {
+      queuer.stop()
+    }
+  })
+
+  return result
 }

package/src/rate-limiter/injectRateLimiter.ts

@@ -1,14 +1,25 @@
+import { DestroyRef, inject } from '@angular/core'
 import { injectStore } from '@tanstack/angular-store'
 import { RateLimiter } from '@tanstack/pacer/rate-limiter'
 import { injectPacerOptions } from '../provider/pacer-context'
 import type { Signal } from '@angular/core'
-import type { Store } from '@tanstack/store'
+import type { Store } from '@tanstack/angular-store'
 import type { AnyFunction } from '@tanstack/pacer/types'
 import type {
   RateLimiterOptions,
   RateLimiterState,
 } from '@tanstack/pacer/rate-limiter'
 
+export interface AngularRateLimiterOptions<
+  TFn extends AnyFunction,
+  TSelected = {},
+> extends RateLimiterOptions<TFn> {
+  /**
+   * Optional callback invoked when the component is destroyed. Receives the rate limiter instance.
+   */
+  onUnmount?: (rateLimiter: AngularRateLimiter<TFn, TSelected>) => void
+}
+
 export interface AngularRateLimiter<
   TFn extends AnyFunction,
   TSelected = {},
@@ -62,6 +73,10 @@ export interface AngularRateLimiter<
  * - `executionTimes`: Array of timestamps when executions occurred for rate limiting calculations
  * - `rejectionCount`: Number of function executions that have been rejected due to rate limiting
  *
+ * ## Cleanup on Destroy
+ *
+ * Use the `onUnmount` option to run a callback when the component is destroyed.
+ *
  * @example
  * ```ts
  * // Default behavior - no reactive state subscriptions
@@ -98,19 +113,28 @@ export interface AngularRateLimiter<
  */
 export function injectRateLimiter<TFn extends AnyFunction, TSelected = {}>(
   fn: TFn,
-  options: RateLimiterOptions<TFn>,
+  options: AngularRateLimiterOptions<TFn, TSelected>,
   selector: (state: RateLimiterState) => TSelected = () => ({}) as TSelected,
 ): AngularRateLimiter<TFn, TSelected> {
   const mergedOptions = {
     ...injectPacerOptions().rateLimiter,
     ...options,
-  } as RateLimiterOptions<TFn>
+  } as AngularRateLimiterOptions<TFn, TSelected>
 
   const rateLimiter = new RateLimiter<TFn>(fn, mergedOptions)
   const state = injectStore(rateLimiter.store, selector)
 
-  return {
+  const result = {
     ...rateLimiter,
     state,
   } as AngularRateLimiter<TFn, TSelected>
+
+  const destroyRef = inject(DestroyRef, { optional: true })
+  destroyRef?.onDestroy(() => {
+    if (mergedOptions.onUnmount) {
+      mergedOptions.onUnmount(result)
+    }
+  })
+
+  return result
 }

package/src/throttler/injectThrottler.ts

@@ -1,14 +1,26 @@
+import { DestroyRef, inject } from '@angular/core'
 import { injectStore } from '@tanstack/angular-store'
 import { Throttler } from '@tanstack/pacer/throttler'
 import { injectPacerOptions } from '../provider/pacer-context'
 import type { Signal } from '@angular/core'
-import type { Store } from '@tanstack/store'
+import type { Store } from '@tanstack/angular-store'
 import type { AnyFunction } from '@tanstack/pacer/types'
 import type {
   ThrottlerOptions,
   ThrottlerState,
 } from '@tanstack/pacer/throttler'
 
+export interface AngularThrottlerOptions<
+  TFn extends AnyFunction,
+  TSelected = {},
+> extends ThrottlerOptions<TFn> {
+  /**
+   * Optional callback invoked when the component is destroyed. Receives the throttler instance.
+   * When provided, replaces the default cleanup (cancel); use it to call flush(), cancel(), add logging, etc.
+   */
+  onUnmount?: (throttler: AngularThrottler<TFn, TSelected>) => void
+}
+
 export interface AngularThrottler<
   TFn extends AnyFunction,
   TSelected = {},
@@ -58,6 +70,18 @@ export interface AngularThrottler<
  * - `nextExecutionTime`: Timestamp of the next allowed execution
  * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
  *
+ * ## Cleanup on Destroy
+ *
+ * By default, the function cancels any pending execution when the component is destroyed.
+ * Use the `onUnmount` option to customize this. For example, to flush pending work instead:
+ *
+ * ```ts
+ * const throttler = injectThrottler(fn, {
+ *   wait: 100,
+ *   onUnmount: (t) => t.flush()
+ * });
+ * ```
+ *
  * @example
  * ```ts
  * // Default behavior - no reactive state subscriptions
@@ -84,19 +108,30 @@ export interface AngularThrottler<
  */
 export function injectThrottler<TFn extends AnyFunction, TSelected = {}>(
   fn: TFn,
-  options: ThrottlerOptions<TFn>,
+  options: AngularThrottlerOptions<TFn, TSelected>,
   selector: (state: ThrottlerState<TFn>) => TSelected = () => ({}) as TSelected,
 ): AngularThrottler<TFn, TSelected> {
   const mergedOptions = {
     ...injectPacerOptions().throttler,
     ...options,
-  } as ThrottlerOptions<TFn>
+  } as AngularThrottlerOptions<TFn, TSelected>
 
   const throttler = new Throttler<TFn>(fn, mergedOptions)
   const state = injectStore(throttler.store, selector)
 
-  return {
+  const result = {
     ...throttler,
     state,
   } as AngularThrottler<TFn, TSelected>
+
+  const destroyRef = inject(DestroyRef, { optional: true })
+  destroyRef?.onDestroy(() => {
+    if (mergedOptions.onUnmount) {
+      mergedOptions.onUnmount(result)
+    } else {
+      throttler.cancel()
+    }
+  })
+
+  return result
 }