@tanstack/angular-pacer 0.20.0

package/src/async-debouncer/injectAsyncDebouncer.ts

@@ -0,0 +1,113 @@
+import { injectStore } from '@tanstack/angular-store'
+import { AsyncDebouncer } from '@tanstack/pacer/async-debouncer'
+import { injectPacerOptions } from '../provider/pacer-context'
+import type { Signal } from '@angular/core'
+import type { Store } from '@tanstack/store'
+import type { AnyAsyncFunction } from '@tanstack/pacer/types'
+import type {
+  AsyncDebouncerOptions,
+  AsyncDebouncerState,
+} from '@tanstack/pacer/async-debouncer'
+
+export interface AngularAsyncDebouncer<
+  TFn extends AnyAsyncFunction,
+  TSelected = {},
+> extends Omit<AsyncDebouncer<TFn>, 'store'> {
+  /**
+   * Reactive state signal that will be updated when the async debouncer state changes
+   *
+   * Use this instead of `debouncer.store.state`
+   */
+  readonly state: Signal<Readonly<TSelected>>
+  /**
+   * @deprecated Use `debouncer.state` instead of `debouncer.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<AsyncDebouncerState<TFn>>>
+}
+
+/**
+ * An Angular function that creates and manages an AsyncDebouncer instance.
+ *
+ * This is a lower-level function that provides direct access to the AsyncDebouncer's functionality.
+ * This allows you to integrate it with any state management solution you prefer.
+ *
+ * This function provides async debouncing functionality with promise support, error handling,
+ * retry capabilities, and abort support.
+ *
+ * The debouncer will only execute the function after the specified wait time has elapsed
+ * since the last call. If the function is called again before the wait time expires, the
+ * timer resets and starts waiting again.
+ *
+ * ## 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.
+ *
+ * Available state properties:
+ * - `canLeadingExecute`: Whether the debouncer can execute on the leading edge
+ * - `errorCount`: Number of function executions that have resulted in errors
+ * - `isExecuting`: Whether the debounced function is currently executing asynchronously
+ * - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution
+ * - `lastArgs`: The arguments from the most recent call to maybeExecute
+ * - `lastResult`: The result from the most recent successful function execution
+ * - `settleCount`: Number of function executions that have completed (either successfully or with errors)
+ * - `status`: Current execution status ('disabled' | 'idle' | 'pending' | 'executing' | 'settled')
+ * - `successCount`: Number of function executions that have completed successfully
+ *
+ * @example
+ * ```ts
+ * // Default behavior - no reactive state subscriptions
+ * const debouncer = injectAsyncDebouncer(
+ *   async (query: string) => {
+ *     const response = await fetch(`/api/search?q=${query}`);
+ *     return response.json();
+ *   },
+ *   { wait: 500 }
+ * );
+ *
+ * // Opt-in to track isExecuting changes (optimized for loading states)
+ * const debouncer = injectAsyncDebouncer(
+ *   async (query: string) => fetchSearchResults(query),
+ *   { wait: 500 },
+ *   (state) => ({ isExecuting: state.isExecuting, isPending: state.isPending })
+ * );
+ *
+ * // In an event handler
+ * const handleChange = async (e: Event) => {
+ *   const target = e.target as HTMLInputElement;
+ *   const result = await debouncer.maybeExecute(target.value);
+ *   console.log('Search results:', result);
+ * };
+ *
+ * // Access the selected state
+ * const { isExecuting, errorCount } = debouncer.state();
+ * ```
+ */
+export function injectAsyncDebouncer<
+  TFn extends AnyAsyncFunction,
+  TSelected = {},
+>(
+  fn: TFn,
+  options: AsyncDebouncerOptions<TFn>,
+  selector: (state: AsyncDebouncerState<TFn>) => TSelected = () =>
+    ({}) as TSelected,
+): AngularAsyncDebouncer<TFn, TSelected> {
+  const mergedOptions = {
+    ...injectPacerOptions().asyncDebouncer,
+    ...options,
+  } as AsyncDebouncerOptions<TFn>
+
+  const debouncer = new AsyncDebouncer<TFn>(fn, mergedOptions)
+  const state = injectStore(debouncer.store, selector)
+
+  return {
+    ...debouncer,
+    state,
+  } as AngularAsyncDebouncer<TFn, TSelected>
+}

package/src/async-queuer/index.ts

@@ -0,0 +1,4 @@
+export * from '@tanstack/pacer/async-queuer'
+
+export * from './injectAsyncQueuedSignal'
+export * from './injectAsyncQueuer'

package/src/async-queuer/injectAsyncQueuedSignal.ts

@@ -0,0 +1,82 @@
+import { computed } from '@angular/core'
+import { injectAsyncQueuer } from './injectAsyncQueuer'
+import type { AngularAsyncQueuer } from './injectAsyncQueuer'
+import type {
+  AsyncQueuerOptions,
+  AsyncQueuerState,
+} from '@tanstack/pacer/async-queuer'
+
+export type AsyncQueuedSignal<
+  TValue,
+  TSelected = {},
+> = (() => Array<TValue>) & {
+  /**
+   * Add an item to the queue.
+   */
+  readonly addItem: AngularAsyncQueuer<TValue, TSelected>['addItem']
+  /**
+   * The queuer instance with additional control methods and state signals.
+   */
+  readonly queuer: AngularAsyncQueuer<TValue, TSelected>
+}
+
+/**
+ * An Angular function that creates an async queuer with managed state, combining Angular's signals with async queuing functionality.
+ * This function provides both the current queue state and queue control methods.
+ *
+ * The queue state is automatically updated whenever items are added, removed, or processed in the queue.
+ * All queue operations are reflected in the state array returned by the function.
+ *
+ * The function returns a callable object:
+ * - `queued()`: Get the current queue items as an array
+ * - `queued.addItem(...)`: Add an item to the queue
+ * - `queued.queue`: The queuer instance with additional control methods
+ *
+ * @example
+ * ```ts
+ * // Default behavior - track items
+ * const queued = injectAsyncQueuedSignal(
+ *   async (item) => {
+ *     const response = await fetch('/api/process', {
+ *       method: 'POST',
+ *       body: JSON.stringify(item)
+ *     });
+ *     return response.json();
+ *   },
+ *   { concurrency: 2, wait: 1000 }
+ * );
+ *
+ * // Add items
+ * queued.addItem(data1);
+ *
+ * // Access items
+ * console.log(queued()); // [data1, ...]
+ *
+ * // Control the queue
+ * queued.queuer.start();
+ * queued.queuer.stop();
+ * ```
+ */
+export function injectAsyncQueuedSignal<
+  TValue,
+  TSelected extends Pick<AsyncQueuerState<TValue>, 'items'> = Pick<
+    AsyncQueuerState<TValue>,
+    'items'
+  >,
+>(
+  fn: (value: TValue) => Promise<any>,
+  options: AsyncQueuerOptions<TValue> = {},
+  selector: (state: AsyncQueuerState<TValue>) => TSelected = (state) =>
+    ({ items: state.items }) as TSelected,
+): AsyncQueuedSignal<TValue, TSelected> {
+  const queuer = injectAsyncQueuer(fn, options, selector)
+
+  const items = computed(() => queuer.state().items as Array<TValue>)
+
+  const queued = Object.assign(items, {
+    addItem: queuer.addItem.bind(queuer),
+    queuer,
+  }) as AsyncQueuedSignal<TValue, TSelected>
+
+  return queued
+}

package/src/async-queuer/injectAsyncQueuer.ts

@@ -0,0 +1,87 @@
+import { injectStore } from '@tanstack/angular-store'
+import { AsyncQueuer } from '@tanstack/pacer/async-queuer'
+import { injectPacerOptions } from '../provider/pacer-context'
+import type { Signal } from '@angular/core'
+import type { Store } from '@tanstack/store'
+import type {
+  AsyncQueuerOptions,
+  AsyncQueuerState,
+} from '@tanstack/pacer/async-queuer'
+
+export interface AngularAsyncQueuer<TValue, TSelected = {}> extends Omit<
+  AsyncQueuer<TValue>,
+  'store'
+> {
+  /**
+   * Reactive state signal that will be updated when the async queuer state changes
+   *
+   * Use this instead of `queuer.store.state`
+   */
+  readonly state: Signal<Readonly<TSelected>>
+  /**
+   * @deprecated Use `queuer.state` instead of `queuer.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<AsyncQueuerState<TValue>>>
+}
+
+/**
+ * An Angular function that creates and manages an AsyncQueuer instance.
+ *
+ * This is a lower-level function that provides direct access to the AsyncQueuer's functionality.
+ * This allows you to integrate it with any state management solution you prefer.
+ *
+ * The AsyncQueuer processes items asynchronously with support for concurrent execution,
+ * promise-based processing, 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.
+ *
+ * @example
+ * ```ts
+ * // Default behavior - no reactive state subscriptions
+ * const queuer = injectAsyncQueuer(
+ *   async (item: Data) => {
+ *     const response = await fetch('/api/process', {
+ *       method: 'POST',
+ *       body: JSON.stringify(item)
+ *     });
+ *     return response.json();
+ *   },
+ *   { concurrency: 2, wait: 1000 }
+ * );
+ *
+ * // Add items
+ * queuer.addItem(data1);
+ * queuer.addItem(data2);
+ *
+ * // Access the selected state
+ * const { items, isExecuting } = queuer.state();
+ * ```
+ */
+export function injectAsyncQueuer<TValue, TSelected = {}>(
+  fn: (value: TValue) => Promise<any>,
+  options: AsyncQueuerOptions<TValue> = {},
+  selector: (state: AsyncQueuerState<TValue>) => TSelected = () =>
+    ({}) as TSelected,
+): AngularAsyncQueuer<TValue, TSelected> {
+  const mergedOptions = {
+    ...injectPacerOptions().asyncQueuer,
+    ...options,
+  } as AsyncQueuerOptions<TValue>
+
+  const queuer = new AsyncQueuer<TValue>(fn, mergedOptions)
+  const state = injectStore(queuer.store, selector)
+
+  return {
+    ...queuer,
+    state,
+  } as AngularAsyncQueuer<TValue, TSelected>
+}

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

@@ -0,0 +1,4 @@
+export * from '@tanstack/pacer/async-rate-limiter'
+
+export * from './injectAsyncRateLimitedCallback'
+export * from './injectAsyncRateLimiter'

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

@@ -0,0 +1,52 @@
+import { injectAsyncRateLimiter } from './injectAsyncRateLimiter'
+import type { AsyncRateLimiterOptions } from '@tanstack/pacer/async-rate-limiter'
+import type { AnyAsyncFunction } from '@tanstack/pacer/types'
+
+/**
+ * An Angular function that creates an async rate-limited version of a callback function.
+ * This function is essentially a wrapper around `injectAsyncRateLimiter` that provides
+ * a simplified API for basic async rate limiting needs.
+ *
+ * This function provides a simpler API compared to `injectAsyncRateLimiter`, making it ideal for basic
+ * async rate limiting needs. However, it does not expose the underlying AsyncRateLimiter instance.
+ *
+ * For advanced usage requiring features like:
+ * - Manual cancellation/reset
+ * - Access to execution counts
+ * - Error handling callbacks
+ * - Retry support
+ *
+ * Consider using the `injectAsyncRateLimiter` function instead.
+ *
+ * @example
+ * ```ts
+ * // Rate limit API calls
+ * const makeApiCall = injectAsyncRateLimitedCallback(
+ *   async (data: ApiData) => {
+ *     const response = await fetch('/api/endpoint', {
+ *       method: 'POST',
+ *       body: JSON.stringify(data)
+ *     });
+ *     return response.json();
+ *   },
+ *   {
+ *     limit: 5,
+ *     window: 60000,
+ *     windowType: 'sliding',
+ *   }
+ * );
+ *
+ * // Use in event handler
+ * const result = await makeApiCall(apiData);
+ * ```
+ */
+export function injectAsyncRateLimitedCallback<TFn extends AnyAsyncFunction>(
+  fn: TFn,
+  options: AsyncRateLimiterOptions<TFn>,
+): (...args: Parameters<TFn>) => Promise<Awaited<ReturnType<TFn>> | undefined> {
+  const rateLimiter = injectAsyncRateLimiter(fn, options)
+  return async (...args: Parameters<TFn>) => {
+    const result = await rateLimiter.maybeExecute(...args)
+    return result !== undefined ? await result : undefined
+  }
+}

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

@@ -0,0 +1,87 @@
+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 { AnyAsyncFunction } from '@tanstack/pacer/types'
+import type {
+  AsyncRateLimiterOptions,
+  AsyncRateLimiterState,
+} from '@tanstack/pacer/async-rate-limiter'
+
+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.
+ *
+ * @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: AsyncRateLimiterOptions<TFn>,
+  selector: (state: AsyncRateLimiterState<TFn>) => TSelected = () =>
+    ({}) as TSelected,
+): AngularAsyncRateLimiter<TFn, TSelected> {
+  const mergedOptions = {
+    ...injectPacerOptions().asyncRateLimiter,
+    ...options,
+  } as AsyncRateLimiterOptions<TFn>
+
+  const rateLimiter = new AsyncRateLimiter<TFn>(fn, mergedOptions)
+  const state = injectStore(rateLimiter.store, selector)
+
+  return {
+    ...rateLimiter,
+    state,
+  } as AngularAsyncRateLimiter<TFn, TSelected>
+}

package/src/async-retryer/index.ts

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

package/src/async-throttler/index.ts

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

package/src/async-throttler/injectAsyncThrottledCallback.ts

@@ -0,0 +1,50 @@
+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

@@ -0,0 +1,92 @@
+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 { AnyAsyncFunction } from '@tanstack/pacer/types'
+import type {
+  AsyncThrottlerOptions,
+  AsyncThrottlerState,
+} from '@tanstack/pacer/async-throttler'
+
+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.
+ *
+ * @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: AsyncThrottlerOptions<TFn>,
+  selector: (state: AsyncThrottlerState<TFn>) => TSelected = () =>
+    ({}) as TSelected,
+): AngularAsyncThrottler<TFn, TSelected> {
+  const mergedOptions = {
+    ...injectPacerOptions().asyncThrottler,
+    ...options,
+  } as AsyncThrottlerOptions<TFn>
+
+  const throttler = new AsyncThrottler<TFn>(fn, mergedOptions)
+  const state = injectStore(throttler.store, selector)
+
+  return {
+    ...throttler,
+    state,
+  } as AngularAsyncThrottler<TFn, TSelected>
+}

package/src/batcher/index.ts

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

package/src/batcher/injectBatchedCallback.ts

@@ -0,0 +1,46 @@
+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)
+}