@tanstack/angular-pacer 0.24.0 → 0.25.0

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

@@ -1,115 +0,0 @@
-import { DestroyRef, inject } from '@angular/core'
-import { injectSelector } 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/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 = {},
-> extends Omit<AsyncRateLimiter<TFn>, 'store'> {
-  /**
-   * Reactive state signal that will be updated when the async rate limiter state changes
-   *
-   * Use this instead of `rateLimiter.store.state`
-   */
-  readonly state: Signal<Readonly<TSelected>>
-  /**
-   * @deprecated Use `rateLimiter.state` instead of `rateLimiter.store.state` if you want to read reactive state.
-   * The state on the store object is not reactive in Angular signals.
-   */
-  readonly store: Store<Readonly<AsyncRateLimiterState<TFn>>>
-}
-
-/**
- * An Angular function that creates and manages an AsyncRateLimiter instance.
- *
- * This is a lower-level function that provides direct access to the AsyncRateLimiter's functionality.
- * This allows you to integrate it with any state management solution you prefer.
- *
- * This function provides async rate limiting functionality with promise support, error handling,
- * retry capabilities, and abort support.
- *
- * ## State Management and Selector
- *
- * The function uses TanStack Store for state management and wraps it with Angular signals.
- * The `selector` parameter allows you to specify which state changes will trigger signal updates,
- * optimizing performance by preventing unnecessary updates when irrelevant state changes occur.
- *
- * **By default, there will be no reactive state subscriptions** and you must opt-in to state
- * 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
- * const rateLimiter = injectAsyncRateLimiter(
- *   async (id: string) => {
- *     const response = await fetch(`/api/data/${id}`);
- *     return response.json();
- *   },
- *   { limit: 5, window: 60000, windowType: 'sliding' }
- * );
- *
- * // In an event handler
- * const handleRequest = async (id: string) => {
- *   const result = await rateLimiter.maybeExecute(id);
- *   console.log('Result:', result);
- * };
- * ```
- */
-export function injectAsyncRateLimiter<
-  TFn extends AnyAsyncFunction,
-  TSelected = {},
->(
-  fn: TFn,
-  options: AngularAsyncRateLimiterOptions<TFn, TSelected>,
-  selector: (state: AsyncRateLimiterState<TFn>) => TSelected = () =>
-    ({}) as TSelected,
-): AngularAsyncRateLimiter<TFn, TSelected> {
-  const mergedOptions = {
-    ...injectPacerOptions().asyncRateLimiter,
-    ...options,
-  } as AngularAsyncRateLimiterOptions<TFn, TSelected>
-
-  const rateLimiter = new AsyncRateLimiter<TFn>(fn, mergedOptions)
-  const state = injectSelector(rateLimiter.store, selector)
-
-  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-retryer/index.ts

@@ -1 +0,0 @@
-export * from '@tanstack/pacer/async-retryer'

package/src/async-throttler/index.ts

@@ -1,4 +0,0 @@
-export * from '@tanstack/pacer/async-throttler'
-
-export * from './injectAsyncThrottledCallback'
-export * from './injectAsyncThrottler'

package/src/async-throttler/injectAsyncThrottledCallback.ts

@@ -1,50 +0,0 @@
-import { injectAsyncThrottler } from './injectAsyncThrottler'
-import type { AsyncThrottlerOptions } from '@tanstack/pacer/async-throttler'
-import type { AnyAsyncFunction } from '@tanstack/pacer/types'
-
-/**
- * An Angular function that creates an async throttled version of a callback function.
- * This function is essentially a wrapper around `injectAsyncThrottler` that provides
- * a simplified API for basic async throttling needs.
- *
- * The throttled function will execute at most once within the specified wait time.
- *
- * This function provides a simpler API compared to `injectAsyncThrottler`, making it ideal for basic
- * async throttling needs. However, it does not expose the underlying AsyncThrottler instance.
- *
- * For advanced usage requiring features like:
- * - Manual cancellation
- * - Access to execution counts
- * - Error handling callbacks
- * - Retry support
- *
- * Consider using the `injectAsyncThrottler` function instead.
- *
- * @example
- * ```ts
- * // Throttle an async update handler
- * const handleUpdate = injectAsyncThrottledCallback(
- *   async (data: Data) => {
- *     const response = await fetch('/api/update', {
- *       method: 'POST',
- *       body: JSON.stringify(data)
- *     });
- *     return response.json();
- *   },
- *   { wait: 1000 }
- * );
- *
- * // Use in an event handler
- * const result = await handleUpdate(updateData);
- * ```
- */
-export function injectAsyncThrottledCallback<TFn extends AnyAsyncFunction>(
-  fn: TFn,
-  options: AsyncThrottlerOptions<TFn>,
-): (...args: Parameters<TFn>) => Promise<Awaited<ReturnType<TFn>> | undefined> {
-  const throttler = injectAsyncThrottler(fn, options)
-  return async (...args: Parameters<TFn>) => {
-    const result = await throttler.maybeExecute(...args)
-    return result !== undefined ? await result : undefined
-  }
-}

package/src/async-throttler/injectAsyncThrottler.ts

@@ -1,131 +0,0 @@
-import { DestroyRef, inject } from '@angular/core'
-import { injectSelector } 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/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 = {},
-> extends Omit<AsyncThrottler<TFn>, 'store'> {
-  /**
-   * Reactive state signal that will be updated when the async throttler state changes
-   *
-   * Use this instead of `throttler.store.state`
-   */
-  readonly state: Signal<Readonly<TSelected>>
-  /**
-   * @deprecated Use `throttler.state` instead of `throttler.store.state` if you want to read reactive state.
-   * The state on the store object is not reactive in Angular signals.
-   */
-  readonly store: Store<Readonly<AsyncThrottlerState<TFn>>>
-}
-
-/**
- * An Angular function that creates and manages an AsyncThrottler instance.
- *
- * This is a lower-level function that provides direct access to the AsyncThrottler's functionality.
- * This allows you to integrate it with any state management solution you prefer.
- *
- * This function provides async throttling functionality with promise support, error handling,
- * retry capabilities, and abort support.
- *
- * The throttler will execute the function at most once within the specified wait time.
- *
- * ## State Management and Selector
- *
- * The function uses TanStack Store for state management and wraps it with Angular signals.
- * The `selector` parameter allows you to specify which state changes will trigger signal updates,
- * optimizing performance by preventing unnecessary updates when irrelevant state changes occur.
- *
- * **By default, there will be no reactive state subscriptions** and you must opt-in to state
- * 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
- * const throttler = injectAsyncThrottler(
- *   async (data: Data) => {
- *     const response = await fetch('/api/update', {
- *       method: 'POST',
- *       body: JSON.stringify(data)
- *     });
- *     return response.json();
- *   },
- *   { wait: 1000 }
- * );
- *
- * // In an event handler
- * const handleUpdate = async (data: Data) => {
- *   const result = await throttler.maybeExecute(data);
- *   console.log('Update result:', result);
- * };
- * ```
- */
-export function injectAsyncThrottler<
-  TFn extends AnyAsyncFunction,
-  TSelected = {},
->(
-  fn: TFn,
-  options: AngularAsyncThrottlerOptions<TFn, TSelected>,
-  selector: (state: AsyncThrottlerState<TFn>) => TSelected = () =>
-    ({}) as TSelected,
-): AngularAsyncThrottler<TFn, TSelected> {
-  const mergedOptions = {
-    ...injectPacerOptions().asyncThrottler,
-    ...options,
-  } as AngularAsyncThrottlerOptions<TFn, TSelected>
-
-  const throttler = new AsyncThrottler<TFn>(fn, mergedOptions)
-  const state = injectSelector(throttler.store, selector)
-
-  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/index.ts

@@ -1,4 +0,0 @@
-export * from '@tanstack/pacer/batcher'
-
-export * from './injectBatchedCallback'
-export * from './injectBatcher'

package/src/batcher/injectBatchedCallback.ts

@@ -1,46 +0,0 @@
-import { injectBatcher } from './injectBatcher'
-import type { BatcherOptions } from '@tanstack/pacer/batcher'
-
-/**
- * An Angular function that creates a batched version of a callback function.
- * This function is essentially a wrapper around `injectBatcher` that provides
- * a simplified API for basic batching needs.
- *
- * The batched function will collect items and process them in batches based on
- * the configured conditions (maxSize, wait time, etc.).
- *
- * This function provides a simpler API compared to `injectBatcher`, making it ideal for basic
- * batching needs. However, it does not expose the underlying Batcher instance.
- *
- * For advanced usage requiring features like:
- * - Manual flushing
- * - Access to batch state
- * - State tracking
- *
- * Consider using the `injectBatcher` function instead.
- *
- * @example
- * ```ts
- * // Batch API calls
- * const batchApiCall = injectBatchedCallback(
- *   (items) => {
- *     return fetch('/api/batch', {
- *       method: 'POST',
- *       body: JSON.stringify(items)
- *     });
- *   },
- *   { maxSize: 10, wait: 1000 }
- * );
- *
- * // Items will be batched and sent together
- * batchApiCall('item1');
- * batchApiCall('item2');
- * ```
- */
-export function injectBatchedCallback<TValue>(
-  fn: (items: Array<TValue>) => void,
-  options: BatcherOptions<TValue>,
-): (item: TValue) => void {
-  const batcher = injectBatcher(fn, options)
-  return (item: TValue) => batcher.addItem(item)
-}

package/src/batcher/injectBatcher.ts

@@ -1,114 +0,0 @@
-import { DestroyRef, inject } from '@angular/core'
-import { injectSelector } 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/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'
-> {
-  /**
-   * Reactive state signal that will be updated when the batcher state changes
-   *
-   * Use this instead of `batcher.store.state`
-   */
-  readonly state: Signal<Readonly<TSelected>>
-  /**
-   * @deprecated Use `batcher.state` instead of `batcher.store.state` if you want to read reactive state.
-   * The state on the store object is not reactive in Angular signals.
-   */
-  readonly store: Store<Readonly<BatcherState<TValue>>>
-}
-
-/**
- * An Angular function that creates and manages a Batcher instance.
- *
- * This is a lower-level function that provides direct access to the Batcher's functionality.
- * This allows you to integrate it with any state management solution you prefer.
- *
- * The Batcher collects items and processes them in batches based on configurable conditions:
- * - Maximum batch size
- * - Time-based batching (process after X milliseconds)
- * - Custom batch processing logic via getShouldExecute
- *
- * ## State Management and Selector
- *
- * The function uses TanStack Store for state management and wraps it with Angular signals.
- * The `selector` parameter allows you to specify which state changes will trigger signal updates,
- * optimizing performance by preventing unnecessary updates when irrelevant state changes occur.
- *
- * **By default, there will be no reactive state subscriptions** and you must opt-in to state
- * 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
- * const batcher = injectBatcher(
- *   (items) => console.log('Processing batch:', items),
- *   { maxSize: 5, wait: 2000 }
- * );
- *
- * // Add items
- * batcher.addItem('task1');
- *
- * // Access the selected state
- * const { items, isPending } = batcher.state();
- * ```
- */
-export function injectBatcher<TValue, TSelected = {}>(
-  fn: (items: Array<TValue>) => void,
-  options: AngularBatcherOptions<TValue, TSelected> = {},
-  selector: (state: BatcherState<TValue>) => TSelected = () =>
-    ({}) as TSelected,
-): AngularBatcher<TValue, TSelected> {
-  const mergedOptions = {
-    ...injectPacerOptions().batcher,
-    ...options,
-  } as AngularBatcherOptions<TValue, TSelected>
-
-  const batcher = new Batcher<TValue>(fn, mergedOptions)
-  const state = injectSelector(batcher.store, selector)
-
-  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/index.ts

@@ -1,6 +0,0 @@
-export * from '@tanstack/pacer/debouncer'
-
-export * from './injectDebouncedCallback'
-export * from './injectDebouncedSignal'
-export * from './injectDebouncedValue'
-export * from './injectDebouncer'

package/src/debouncer/injectDebouncedCallback.ts

@@ -1,46 +0,0 @@
-import { injectDebouncer } from './injectDebouncer'
-import type { DebouncerOptions } from '@tanstack/pacer/debouncer'
-import type { AnyFunction } from '@tanstack/pacer/types'
-
-/**
- * An Angular function that creates a debounced version of a callback function.
- * This function is essentially a wrapper around `injectDebouncer` that provides
- * a simplified API for basic debouncing needs.
- *
- * The debounced function will only execute after the specified wait time has elapsed
- * since its last invocation. If called again before the wait time expires, the timer
- * resets and starts waiting again.
- *
- * This function provides a simpler API compared to `injectDebouncer`, making it ideal for basic
- * debouncing needs. However, it does not expose the underlying Debouncer instance.
- *
- * For advanced usage requiring features like:
- * - Manual cancellation
- * - Access to execution counts
- * - State tracking
- *
- * Consider using the `injectDebouncer` function instead.
- *
- * @example
- * ```ts
- * // Debounce a search handler
- * const handleSearch = injectDebouncedCallback((query: string) => {
- *   fetchSearchResults(query);
- * }, {
- *   wait: 500 // Wait 500ms between executions
- * });
- *
- * // Use in an input
- * <input
- *   type="search"
- *   (input)="handleSearch($event.target.value)"
- * />
- * ```
- */
-export function injectDebouncedCallback<TFn extends AnyFunction>(
-  fn: TFn,
-  options: DebouncerOptions<TFn>,
-): (...args: Parameters<TFn>) => void {
-  const debouncer = injectDebouncer(fn, options)
-  return (...args: Parameters<TFn>) => debouncer.maybeExecute(...args)
-}

package/src/debouncer/injectDebouncedSignal.ts

@@ -1,94 +0,0 @@
-import { signal } from '@angular/core'
-import { injectDebouncer } from './injectDebouncer'
-import type { AngularDebouncer } from './injectDebouncer'
-import type {
-  DebouncerOptions,
-  DebouncerState,
-} from '@tanstack/pacer/debouncer'
-
-type Setter<T> = (value: T | ((prev: T) => T)) => void
-
-export interface DebouncedSignal<TValue, TSelected = {}> {
-  (): TValue
-  set: Setter<TValue>
-  debouncer: AngularDebouncer<Setter<TValue>, TSelected>
-}
-
-/**
- * An Angular function that creates a debounced state signal, combining Angular's signal with debouncing functionality.
- * This function provides both the current debounced value and methods to update it.
- *
- * The state value is only updated after the specified wait time has elapsed since the last update attempt.
- * If another update is attempted before the wait time expires, the timer resets and starts waiting again.
- * This is useful for handling frequent state updates that should be throttled, like search input values
- * or window resize dimensions.
- *
- * The function returns a callable object:
- * - `debounced()`: Get the current debounced value
- * - `debounced.set(...)`: Set or update the debounced value (debounced via maybeExecute)
- * - `debounced.debouncer`: The debouncer instance with additional control methods and state signals
- *
- * ## State Management and Selector
- *
- * The function uses TanStack Store for reactive state management via the underlying debouncer instance.
- * The `selector` parameter allows you to specify which debouncer state changes will trigger signal updates,
- * optimizing performance by preventing unnecessary subscriptions when irrelevant state changes occur.
- *
- * **By default, there will be no reactive state subscriptions** and you must opt-in to state
- * tracking by providing a selector function. This prevents unnecessary updates and gives you
- * full control over when your component tracks state changes. Only when you provide a selector will
- * the reactive system track the selected state values.
- *
- * Available debouncer state properties:
- * - `canLeadingExecute`: Whether the debouncer can execute on the leading edge
- * - `executionCount`: Number of function executions that have been completed
- * - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution
- * - `lastArgs`: The arguments from the most recent call to maybeExecute
- * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
- *
- * @example
- * ```ts
- * const debouncedQuery = injectDebouncedSignal('', { wait: 500 })
- *
- * // Get value
- * console.log(debouncedQuery())
- *
- * // Set/update value (debounced)
- * debouncedQuery.set('hello')
- *
- * // Access debouncer
- * console.log(debouncedQuery.debouncer.state().isPending)
- * ```
- */
-export function injectDebouncedSignal<TValue, TSelected = {}>(
-  value: TValue,
-  initialOptions: DebouncerOptions<Setter<TValue>>,
-  selector?: (state: DebouncerState<Setter<TValue>>) => TSelected,
-): DebouncedSignal<TValue, TSelected> {
-  const debouncedValue = signal<TValue>(value)
-
-  const debouncer = injectDebouncer(
-    (newValue: TValue | ((prev: TValue) => TValue)) => {
-      if (typeof newValue === 'function') {
-        debouncedValue.update(newValue as (prev: TValue) => TValue)
-      } else {
-        debouncedValue.set(newValue)
-      }
-    },
-    initialOptions,
-    selector,
-  )
-
-  const set: Setter<TValue> = (
-    newValue: TValue | ((prev: TValue) => TValue),
-  ) => {
-    debouncer.maybeExecute(newValue)
-  }
-
-  const debounced = Object.assign(() => debouncedValue(), {
-    set,
-    debouncer,
-  }) as DebouncedSignal<TValue, TSelected>
-
-  return debounced
-}