@tanstack/angular-pacer 0.20.0 → 0.22.0

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/injectDebouncedSignal.ts

@@ -8,17 +8,10 @@ import type {
 
 type Setter<T> = (value: T | ((prev: T) => T)) => void
 
-export type DebouncedSignal<TValue, TSelected = {}> = ((
-  ...args: []
-) => TValue) & {
-  /**
-   * Set or update the debounced value. This calls `debouncer.maybeExecute(...)`.
-   */
-  readonly set: Setter<TValue>
-  /**
-   * The debouncer instance with additional control methods and state signals.
-   */
-  readonly debouncer: AngularDebouncer<Setter<TValue>, TSelected>
+export interface DebouncedSignal<TValue, TSelected = {}> {
+  (): TValue
+  set: Setter<TValue>
+  debouncer: AngularDebouncer<Setter<TValue>, TSelected>
 }
 
 /**

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/injectQueuedSignal.ts

@@ -3,15 +3,10 @@ import { injectQueuer } from './injectQueuer'
 import type { AngularQueuer } from './injectQueuer'
 import type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
 
-export type QueuedSignal<TValue, TSelected = {}> = (() => Array<TValue>) & {
-  /**
-   * Add an item to the queue.
-   */
-  readonly addItem: AngularQueuer<TValue, TSelected>['addItem']
-  /**
-   * The queuer instance with additional control methods and state signals.
-   */
-  readonly queuer: AngularQueuer<TValue, TSelected>
+export interface QueuedSignal<TValue, TSelected = {}> {
+  (): Array<TValue>
+  addItem: AngularQueuer<TValue, TSelected>['addItem']
+  queuer: AngularQueuer<TValue, TSelected>
 }
 
 /**

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/injectRateLimitedSignal.ts

@@ -8,17 +8,10 @@ import type {
 
 type Setter<T> = (value: T | ((prev: T) => T)) => void
 
-export type RateLimitedSignal<TValue, TSelected = {}> = ((
-  ...args: []
-) => TValue) & {
-  /**
-   * Set or update the rate-limited value. This calls `rateLimiter.maybeExecute(...)`.
-   */
-  readonly set: Setter<TValue>
-  /**
-   * The rate limiter instance with additional control methods and state signals.
-   */
-  readonly rateLimiter: AngularRateLimiter<Setter<TValue>, TSelected>
+export interface RateLimitedSignal<TValue, TSelected = {}> {
+  (): TValue
+  set: Setter<TValue>
+  rateLimiter: AngularRateLimiter<Setter<TValue>, TSelected>
 }
 
 /**

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/injectThrottledSignal.ts

@@ -8,17 +8,10 @@ import type {
 
 type Setter<T> = (value: T | ((prev: T) => T)) => void
 
-export type ThrottledSignal<TValue, TSelected = {}> = ((
-  ...args: []
-) => TValue) & {
-  /**
-   * Set or update the throttled value. This calls `throttler.maybeExecute(...)`.
-   */
-  readonly set: Setter<TValue>
-  /**
-   * The throttler instance with additional control methods and state signals.
-   */
-  readonly throttler: AngularThrottler<Setter<TValue>, TSelected>
+export interface ThrottledSignal<TValue, TSelected = {}> {
+  (): TValue
+  set: Setter<TValue>
+  throttler: AngularThrottler<Setter<TValue>, TSelected>
 }
 
 /**

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
 }