@tanstack/angular-pacer 0.23.1 → 0.25.0

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
-}

package/src/debouncer/injectDebouncedValue.ts

@@ -1,126 +0,0 @@
-import { effect } from '@angular/core'
-import { injectDebouncedSignal } from './injectDebouncedSignal'
-import type { DebouncedSignal } from './injectDebouncedSignal'
-import type { Signal } from '@angular/core'
-import type {
-  DebouncerOptions,
-  DebouncerState,
-} from '@tanstack/pacer/debouncer'
-
-type Setter<T> = (value: T | ((prev: T) => T)) => void
-
-/**
- * An Angular function that creates a debounced value that updates only after a specified delay.
- * Unlike injectDebouncedSignal, this function automatically tracks changes to the input signal
- * and updates the debounced value accordingly.
- *
- * The debounced value will only update after the specified wait time has elapsed since
- * the last change to the input value. If the input value changes again before the wait
- * time expires, the timer resets and starts waiting again.
- *
- * This is useful for deriving debounced values from signals that change frequently,
- * like search queries or form inputs, where you want to limit how often downstream effects
- * or calculations occur.
- *
- * The function returns a tuple containing:
- * - A Signal that provides the current debounced value
- * - The debouncer instance with control methods
- *
- * ## 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
- * // Default behavior - no reactive state subscriptions
- * const searchQuery = signal('')
- * const debounced = injectDebouncedValue(searchQuery, {
- *   wait: 500, // Wait 500ms after last change
- * })
- *
- * // Opt-in to reactive updates when pending state changes (optimized for loading indicators)
- * const debouncedWithPending = injectDebouncedValue(
- *   searchQuery,
- *   { wait: 500 },
- *   (state) => ({ isPending: state.isPending }),
- * )
- *
- * // Debounced value will update 500ms after searchQuery stops changing
- * effect(() => {
- *   fetchSearchResults(debounced())
- * })
- *
- * // Access selected debouncer state via signals (only if you provided a selector)
- * effect(() => {
- *   console.log('Is pending:', debouncedWithPending.state().isPending)
- * })
- *
- * // Control the debouncer
- * debounced.cancel() // Cancel any pending updates
- * ```
- */
-export function injectDebouncedValue<TValue, TSelected = {}>(
-  value: Signal<TValue>,
-  initialOptions: DebouncerOptions<Setter<TValue>>,
-  selector?: (state: DebouncerState<Setter<TValue>>) => TSelected,
-): DebouncedSignal<TValue, TSelected>
-export function injectDebouncedValue<TValue, TSelected = {}>(
-  value: Signal<TValue>,
-  initialValue: TValue,
-  initialOptions: DebouncerOptions<Setter<TValue>>,
-  selector?: (state: DebouncerState<Setter<TValue>>) => TSelected,
-): DebouncedSignal<TValue, TSelected>
-export function injectDebouncedValue<TValue, TSelected = {}>(
-  value: Signal<TValue>,
-  initialValueOrOptions: TValue | DebouncerOptions<Setter<TValue>>,
-  initialOptionsOrSelector?:
-    | DebouncerOptions<Setter<TValue>>
-    | ((state: DebouncerState<Setter<TValue>>) => TSelected),
-  maybeSelector?: (state: DebouncerState<Setter<TValue>>) => TSelected,
-): DebouncedSignal<TValue, TSelected> {
-  const hasSelector = typeof initialOptionsOrSelector === 'function'
-
-  const hasInitialValue =
-    (initialOptionsOrSelector !== undefined && !hasSelector) ||
-    maybeSelector !== undefined
-
-  const initialValue = hasInitialValue
-    ? (initialValueOrOptions as TValue)
-    : (undefined as unknown as TValue)
-  const initialOptions = hasInitialValue
-    ? (initialOptionsOrSelector as DebouncerOptions<Setter<TValue>>)
-    : (initialValueOrOptions as DebouncerOptions<Setter<TValue>>)
-  const selector = hasInitialValue
-    ? maybeSelector
-    : (initialOptionsOrSelector as
-        | ((state: DebouncerState<Setter<TValue>>) => TSelected)
-        | undefined)
-
-  const debounced = injectDebouncedSignal(
-    initialValue,
-    initialOptions,
-    selector,
-  )
-
-  effect(() => {
-    const latest = value()
-    debounced.set(latest)
-  })
-
-  return debounced
-}

package/src/debouncer/injectDebouncer.ts

@@ -1,137 +0,0 @@
-import { DestroyRef, inject } from '@angular/core'
-import { injectSelector } 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/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 = {},
-> extends Omit<Debouncer<TFn>, 'store'> {
-  /**
-   * Reactive state signal that will be updated when the 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<DebouncerState<TFn>>>
-}
-
-/**
- * An Angular function that creates and manages a Debouncer instance.
- *
- * This is a lower-level function that provides direct access to the Debouncer's functionality.
- * This allows you to integrate it with any state management solution you prefer.
- *
- * This function provides debouncing functionality to limit how often a function can be called,
- * waiting for a specified delay before executing the latest call. This is useful for handling
- * frequent events like window resizing, scroll events, or real-time search inputs.
- *
- * 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
- * - `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')
- *
- * ## 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
- * const debouncer = injectDebouncer(
- *   (query: string) => fetchSearchResults(query),
- *   { wait: 500 }
- * );
- *
- * // Opt-in to track isPending changes (optimized for loading states)
- * const debouncer = injectDebouncer(
- *   (query: string) => fetchSearchResults(query),
- *   { wait: 500 },
- *   (state) => ({ isPending: state.isPending })
- * );
- *
- * // In an event handler
- * const handleChange = (e: Event) => {
- *   const target = e.target as HTMLInputElement
- *   debouncer.maybeExecute(target.value);
- * };
- *
- * // Access the selected state (will be empty object {} unless selector provided)
- * const { isPending } = debouncer.state();
- * ```
- */
-export function injectDebouncer<TFn extends AnyFunction, TSelected = {}>(
-  fn: TFn,
-  options: AngularDebouncerOptions<TFn, TSelected>,
-  selector: (state: DebouncerState<TFn>) => TSelected = () => ({}) as TSelected,
-): AngularDebouncer<TFn, TSelected> {
-  const mergedOptions = {
-    ...injectPacerOptions().debouncer,
-    ...options,
-  } as AngularDebouncerOptions<TFn, TSelected>
-
-  const debouncer = new Debouncer<TFn>(fn, mergedOptions)
-  const state = injectSelector(debouncer.store, selector)
-
-  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/index.ts

@@ -1,40 +0,0 @@
-export * from '@tanstack/pacer'
-
-export * from './provider/pacer-provider'
-
-export * from './async-batcher/injectAsyncBatchedCallback'
-export * from './async-batcher/injectAsyncBatcher'
-
-export * from './async-debouncer/injectAsyncDebouncedCallback'
-export * from './async-debouncer/injectAsyncDebouncer'
-
-export * from './async-queuer/injectAsyncQueuedSignal'
-export * from './async-queuer/injectAsyncQueuer'
-
-export * from './async-rate-limiter/injectAsyncRateLimitedCallback'
-export * from './async-rate-limiter/injectAsyncRateLimiter'
-
-export * from './async-throttler/injectAsyncThrottledCallback'
-export * from './async-throttler/injectAsyncThrottler'
-
-export * from './batcher/injectBatchedCallback'
-export * from './batcher/injectBatcher'
-
-export * from './debouncer/injectDebouncedCallback'
-export * from './debouncer/injectDebouncedSignal'
-export * from './debouncer/injectDebouncedValue'
-export * from './debouncer/injectDebouncer'
-
-export * from './queuer/injectQueuedSignal'
-export * from './queuer/injectQueuedValue'
-export * from './queuer/injectQueuer'
-
-export * from './rate-limiter/injectRateLimitedCallback'
-export * from './rate-limiter/injectRateLimitedSignal'
-export * from './rate-limiter/injectRateLimitedValue'
-export * from './rate-limiter/injectRateLimiter'
-
-export * from './throttler/injectThrottledCallback'
-export * from './throttler/injectThrottledSignal'
-export * from './throttler/injectThrottledValue'
-export * from './throttler/injectThrottler'

package/src/provider/index.ts

@@ -1,2 +0,0 @@
-export * from './pacer-context'
-export * from './pacer-provider'

package/src/provider/pacer-context.ts

@@ -1,46 +0,0 @@
-import { InjectionToken, inject } from '@angular/core'
-import type {
-  AnyAsyncFunction,
-  AnyFunction,
-  AsyncBatcherOptions,
-  AsyncDebouncerOptions,
-  AsyncQueuerOptions,
-  AsyncRateLimiterOptions,
-  AsyncThrottlerOptions,
-  BatcherOptions,
-  DebouncerOptions,
-  QueuerOptions,
-  RateLimiterOptions,
-  ThrottlerOptions,
-} from '@tanstack/pacer'
-
-export interface PacerProviderOptions {
-  asyncBatcher?: Partial<AsyncBatcherOptions<any>>
-  asyncDebouncer?: Partial<AsyncDebouncerOptions<AnyAsyncFunction>>
-  asyncQueuer?: Partial<AsyncQueuerOptions<any>>
-  asyncRateLimiter?: Partial<AsyncRateLimiterOptions<AnyAsyncFunction>>
-  asyncThrottler?: Partial<AsyncThrottlerOptions<AnyAsyncFunction>>
-  batcher?: Partial<BatcherOptions<any>>
-  debouncer?: Partial<DebouncerOptions<AnyFunction>>
-  queuer?: Partial<QueuerOptions<any>>
-  rateLimiter?: Partial<RateLimiterOptions<AnyFunction>>
-  throttler?: Partial<ThrottlerOptions<AnyFunction>>
-}
-
-const DEFAULT_OPTIONS: PacerProviderOptions = {}
-
-export const PACER_OPTIONS = new InjectionToken<PacerProviderOptions>(
-  'PACER_OPTIONS',
-  {
-    providedIn: 'root',
-    factory: () => DEFAULT_OPTIONS,
-  },
-)
-
-export function injectPacerOptions(): PacerProviderOptions {
-  try {
-    return inject(PACER_OPTIONS, { optional: true }) ?? DEFAULT_OPTIONS
-  } catch {
-    return DEFAULT_OPTIONS
-  }
-}

package/src/provider/pacer-provider.ts

@@ -1,38 +0,0 @@
-import { PACER_OPTIONS } from './pacer-context'
-import type { Provider } from '@angular/core'
-import type { PacerProviderOptions } from './pacer-context'
-
-/**
- * Provides default options for all Pacer utilities in the Angular application.
- * Use this function when configuring your Angular application to set default options
- * that will be used by all Pacer utilities throughout your app.
- *
- * @example
- * ```ts
- * // In your app.config.ts (standalone)
- * export const appConfig: ApplicationConfig = {
- *   providers: [
- *     providePacerOptions({
- *       debouncer: { wait: 300 },
- *       throttler: { wait: 100 },
- *     }),
- *   ],
- * };
- *
- * // Or in NgModule (module-based)
- * @NgModule({
- *   providers: [
- *     providePacerOptions({
- *       debouncer: { wait: 300 },
- *     }),
- *   ],
- * })
- * export class AppModule {}
- * ```
- */
-export function providePacerOptions(options: PacerProviderOptions): Provider {
-  return {
-    provide: PACER_OPTIONS,
-    useValue: options,
-  }
-}

package/src/queuer/index.ts

@@ -1,5 +0,0 @@
-export * from '@tanstack/pacer/queuer'
-
-export * from './injectQueuedSignal'
-export * from './injectQueuedValue'
-export * from './injectQueuer'

package/src/queuer/injectQueuedSignal.ts

@@ -1,65 +0,0 @@
-import { computed } from '@angular/core'
-import { injectQueuer } from './injectQueuer'
-import type { AngularQueuer } from './injectQueuer'
-import type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
-
-export interface QueuedSignal<TValue, TSelected = {}> {
-  (): Array<TValue>
-  addItem: AngularQueuer<TValue, TSelected>['addItem']
-  queuer: AngularQueuer<TValue, TSelected>
-}
-
-/**
- * An Angular function that creates a queuer with managed state, combining Angular's signals with 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 reordered 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 = injectQueuedSignal(
- *   (item) => console.log('Processing:', item),
- *   { started: true, wait: 1000 }
- * );
- *
- * // Add items
- * queued.addItem('task1');
- *
- * // Access items
- * console.log(queued()); // ['task1']
- *
- * // Control the queue
- * queued.queuer.start();
- * queued.queuer.stop();
- * ```
- */
-export function injectQueuedSignal<
-  TValue,
-  TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<
-    QueuerState<TValue>,
-    'items'
-  >,
->(
-  fn: (item: TValue) => void,
-  options: QueuerOptions<TValue> = {},
-  selector: (state: QueuerState<TValue>) => TSelected = (state) =>
-    ({ items: state.items }) as TSelected,
-): QueuedSignal<TValue, TSelected> {
-  const queuer = injectQueuer(fn, options, selector)
-
-  const items = computed(() => queuer.state().items as Array<TValue>)
-
-  const queued = Object.assign(items, {
-    addItem: queuer.addItem.bind(queuer),
-    queuer,
-  }) as QueuedSignal<TValue, TSelected>
-
-  return queued
-}