@tanstack/angular-pacer 0.23.1 → 0.25.0

package/src/queuer/injectQueuedValue.ts

@@ -1,101 +0,0 @@
-import { effect, linkedSignal, signal } from '@angular/core'
-import { injectQueuedSignal } from './injectQueuedSignal'
-import type { QueuedSignal } from './injectQueuedSignal'
-import type { Signal } from '@angular/core'
-import type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
-
-/**
- * An Angular function that creates a queued value that processes state changes in order with an optional delay.
- * This function uses injectQueuedSignal internally to manage a queue of state changes and apply them sequentially.
- *
- * The queued value will process changes in the order they are received, with optional delays between
- * processing each change. This is useful for handling state updates that need to be processed
- * in a specific order, like animations or sequential UI updates.
- *
- * The function returns a tuple containing:
- * - A Signal that provides the current queued value
- * - The queuer instance with control methods
- *
- * @example
- * ```ts
- * const initialValue = signal('initial')
- * const queued = injectQueuedValue(initialValue, {
- *   wait: 500,
- *   started: true,
- * })
- *
- * // Add changes to the queue
- * queued.addItem('new value')
- * ```
- */
-export function injectQueuedValue<
-  TValue,
-  TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<
-    QueuerState<TValue>,
-    'items'
-  >,
->(
-  value: Signal<TValue>,
-  options?: QueuerOptions<TValue>,
-  selector?: (state: QueuerState<TValue>) => TSelected,
-): QueuedSignal<TValue, TSelected>
-export function injectQueuedValue<
-  TValue,
-  TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<
-    QueuerState<TValue>,
-    'items'
-  >,
->(
-  value: Signal<TValue>,
-  initialValue: TValue,
-  options?: QueuerOptions<TValue>,
-  selector?: (state: QueuerState<TValue>) => TSelected,
-): QueuedSignal<TValue, TSelected>
-export function injectQueuedValue<
-  TValue,
-  TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<
-    QueuerState<TValue>,
-    'items'
-  >,
->(
-  value: Signal<TValue>,
-  initialValueOrOptions?: TValue | QueuerOptions<TValue>,
-  initialOptionsOrSelector?:
-    | QueuerOptions<TValue>
-    | ((state: QueuerState<TValue>) => TSelected),
-  maybeSelector?: (state: QueuerState<TValue>) => TSelected,
-): QueuedSignal<TValue, TSelected> {
-  const hasSelector = typeof initialOptionsOrSelector === 'function'
-  const hasInitialValue =
-    (initialOptionsOrSelector !== undefined && !hasSelector) ||
-    maybeSelector !== undefined
-
-  const initialValue = hasInitialValue
-    ? (initialValueOrOptions as TValue)
-    : value()
-  const initialOptions = hasInitialValue
-    ? (initialOptionsOrSelector as QueuerOptions<TValue>)
-    : (initialValueOrOptions as QueuerOptions<TValue>)
-  const selector = hasInitialValue
-    ? maybeSelector
-    : (initialOptionsOrSelector as
-        | ((state: QueuerState<TValue>) => TSelected)
-        | undefined)
-
-  const linkedValue = linkedSignal(() => value())
-  const queuedValue = signal<TValue>(initialValue)
-
-  const queued = injectQueuedSignal(
-    (item) => {
-      queuedValue.set(item)
-    },
-    initialOptions,
-    selector,
-  )
-
-  effect(() => {
-    queued.addItem(linkedValue())
-  })
-
-  return queued
-}

package/src/queuer/injectQueuer.ts

@@ -1,118 +0,0 @@
-import { DestroyRef, inject } from '@angular/core'
-import { injectSelector } 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/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'
-> {
-  /**
-   * Reactive state signal that will be updated when the 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<QueuerState<TValue>>>
-}
-
-/**
- * An Angular function that creates and manages a Queuer instance.
- *
- * This is a lower-level function that provides direct access to the Queuer's functionality.
- * This allows you to integrate it with any state management solution you prefer.
- *
- * The Queuer processes items synchronously in order, with optional delays between processing each item.
- * The queuer includes an internal tick mechanism that can be started and stopped, making it useful as a scheduler.
- *
- * ## 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 queue = injectQueuer(
- *   (item) => console.log('Processing:', item),
- *   { started: true, wait: 1000 }
- * );
- *
- * // Opt-in to track queue contents changes
- * const queue = injectQueuer(
- *   (item) => console.log('Processing:', item),
- *   { started: true, wait: 1000 },
- *   (state) => ({ items: state.items, size: state.size })
- * );
- *
- * // Add items
- * queue.addItem('task1');
- *
- * // 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: AngularQueuerOptions<TValue, TSelected> = {},
-  selector: (state: QueuerState<TValue>) => TSelected = () => ({}) as TSelected,
-): AngularQueuer<TValue, TSelected> {
-  const mergedOptions = {
-    ...injectPacerOptions().queuer,
-    ...options,
-  } as AngularQueuerOptions<TValue, TSelected>
-
-  const queuer = new Queuer<TValue>(fn, mergedOptions)
-  const state = injectSelector(queuer.store, selector)
-
-  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/index.ts

@@ -1,6 +0,0 @@
-export * from '@tanstack/pacer/rate-limiter'
-
-export * from './injectRateLimitedCallback'
-export * from './injectRateLimitedSignal'
-export * from './injectRateLimitedValue'
-export * from './injectRateLimiter'

package/src/rate-limiter/injectRateLimitedCallback.ts

@@ -1,45 +0,0 @@
-import { injectRateLimiter } from './injectRateLimiter'
-import type { RateLimiterOptions } from '@tanstack/pacer/rate-limiter'
-import type { AnyFunction } from '@tanstack/pacer/types'
-
-/**
- * An Angular function that creates a rate-limited version of a callback function.
- * This function is essentially a wrapper around `injectRateLimiter` that provides
- * a simplified API for basic rate limiting needs.
- *
- * Rate limiting is a simple "hard limit" approach - it allows all calls until the limit
- * is reached, then blocks subsequent calls until the window resets. Unlike throttling
- * or debouncing, it does not attempt to space out or intelligently collapse calls.
- *
- * This function provides a simpler API compared to `injectRateLimiter`, making it ideal for basic
- * rate limiting needs. However, it does not expose the underlying RateLimiter instance.
- *
- * For advanced usage requiring features like:
- * - Manual cancellation/reset
- * - Access to execution counts
- * - State tracking
- *
- * Consider using the `injectRateLimiter` function instead.
- *
- * @example
- * ```ts
- * // Rate limit API calls to maximum 5 calls per minute
- * const makeApiCall = injectRateLimitedCallback(
- *   (data: ApiData) => {
- *     return fetch('/api/endpoint', { method: 'POST', body: JSON.stringify(data) });
- *   },
- *   {
- *     limit: 5,
- *     window: 60000, // 1 minute
- *     windowType: 'sliding',
- *   }
- * );
- * ```
- */
-export function injectRateLimitedCallback<TFn extends AnyFunction>(
-  fn: TFn,
-  options: RateLimiterOptions<TFn>,
-): (...args: Parameters<TFn>) => boolean {
-  const rateLimiter = injectRateLimiter(fn, options)
-  return (...args: Parameters<TFn>) => rateLimiter.maybeExecute(...args)
-}

package/src/rate-limiter/injectRateLimitedSignal.ts

@@ -1,88 +0,0 @@
-import { signal } from '@angular/core'
-import { injectRateLimiter } from './injectRateLimiter'
-import type { AngularRateLimiter } from './injectRateLimiter'
-import type {
-  RateLimiterOptions,
-  RateLimiterState,
-} from '@tanstack/pacer/rate-limiter'
-
-type Setter<T> = (value: T | ((prev: T) => T)) => void
-
-export interface RateLimitedSignal<TValue, TSelected = {}> {
-  (): TValue
-  set: Setter<TValue>
-  rateLimiter: AngularRateLimiter<Setter<TValue>, TSelected>
-}
-
-/**
- * An Angular function that creates a rate-limited state signal, combining Angular's signal with rate limiting functionality.
- * This function provides both the current rate-limited value and methods to update it.
- *
- * Rate limiting is a simple "hard limit" approach - it allows all updates until the limit is reached, then blocks
- * subsequent updates until the window resets. Unlike throttling or debouncing, it does not attempt to space out
- * or intelligently collapse updates.
- *
- * The function returns a callable object:
- * - `rateLimited()`: Get the current rate-limited value
- * - `rateLimited.set(...)`: Set or update the rate-limited value (rate-limited via maybeExecute)
- * - `rateLimited.rateLimiter`: The rate limiter instance with additional control methods and state signals
- *
- * ## State Management and Selector
- *
- * The function uses TanStack Store for reactive state management via the underlying rate limiter instance.
- * The `selector` parameter allows you to specify which rate limiter 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.
- *
- * @example
- * ```ts
- * // Default behavior - no reactive state subscriptions
- * const rateLimited = injectRateLimitedSignal(0, {
- *   limit: 5,
- *   window: 60000,
- *   windowType: 'sliding'
- * });
- *
- * // Opt-in to reactive updates when limit state changes
- * const rateLimited = injectRateLimitedSignal(
- *   0,
- *   { limit: 5, window: 60000 },
- *   (state) => ({ rejectionCount: state.rejectionCount })
- * );
- * ```
- */
-export function injectRateLimitedSignal<TValue, TSelected = {}>(
-  value: TValue,
-  initialOptions: RateLimiterOptions<Setter<TValue>>,
-  selector?: (state: RateLimiterState) => TSelected,
-): RateLimitedSignal<TValue, TSelected> {
-  const rateLimitedValue = signal<TValue>(value)
-
-  const rateLimiter = injectRateLimiter(
-    (newValue: TValue | ((prev: TValue) => TValue)) => {
-      if (typeof newValue === 'function') {
-        rateLimitedValue.update(newValue as (prev: TValue) => TValue)
-      } else {
-        rateLimitedValue.set(newValue)
-      }
-    },
-    initialOptions,
-    selector,
-  )
-
-  const set: Setter<TValue> = (
-    newValue: TValue | ((prev: TValue) => TValue),
-  ) => {
-    rateLimiter.maybeExecute(newValue)
-  }
-
-  const rateLimited = Object.assign(() => rateLimitedValue(), {
-    set,
-    rateLimiter,
-  }) as RateLimitedSignal<TValue, TSelected>
-
-  return rateLimited
-}

package/src/rate-limiter/injectRateLimitedValue.ts

@@ -1,99 +0,0 @@
-import { effect } from '@angular/core'
-import { injectRateLimitedSignal } from './injectRateLimitedSignal'
-import type { RateLimitedSignal } from './injectRateLimitedSignal'
-import type { Signal } from '@angular/core'
-import type {
-  RateLimiterOptions,
-  RateLimiterState,
-} from '@tanstack/pacer/rate-limiter'
-
-type Setter<T> = (value: T | ((prev: T) => T)) => void
-
-/**
- * An Angular function that creates a rate-limited value that updates at most a certain number of times within a time window.
- * Unlike injectRateLimitedSignal, this function automatically tracks changes to the input signal
- * and updates the rate-limited value accordingly.
- *
- * The rate-limited value will update according to the configured rate limit, blocking updates
- * once the limit is reached until the window resets.
- *
- * The function returns a rate-limited signal object containing:
- * - A Signal that provides the current rate-limited value
- * - The rate limiter instance with control methods
- *
- * ## State Management and Selector
- *
- * The function uses TanStack Store for reactive state management via the underlying rate limiter instance.
- * The `selector` parameter allows you to specify which rate limiter 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.
- *
- * @example
- * ```ts
- * // Default behavior - no reactive state subscriptions
- * const value = signal(0)
- * const rateLimited = injectRateLimitedValue(value, {
- *   limit: 5,
- *   window: 60000,
- *   windowType: 'sliding',
- * })
- *
- * // rateLimited() will update at most 5 times per 60 seconds
- * effect(() => {
- *   updateUI(rateLimited())
- * })
- * ```
- */
-export function injectRateLimitedValue<TValue, TSelected = {}>(
-  value: Signal<TValue>,
-  initialOptions: RateLimiterOptions<Setter<TValue>>,
-  selector?: (state: RateLimiterState) => TSelected,
-): RateLimitedSignal<TValue, TSelected>
-export function injectRateLimitedValue<TValue, TSelected = {}>(
-  value: Signal<TValue>,
-  initialValue: TValue,
-  initialOptions: RateLimiterOptions<Setter<TValue>>,
-  selector?: (state: RateLimiterState) => TSelected,
-): RateLimitedSignal<TValue, TSelected>
-export function injectRateLimitedValue<TValue, TSelected = {}>(
-  value: Signal<TValue>,
-  initialValueOrOptions: TValue | RateLimiterOptions<Setter<TValue>>,
-  initialOptionsOrSelector?:
-    | RateLimiterOptions<Setter<TValue>>
-    | ((state: RateLimiterState) => TSelected),
-  maybeSelector?: (state: RateLimiterState) => TSelected,
-): RateLimitedSignal<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 RateLimiterOptions<Setter<TValue>>)
-    : (initialValueOrOptions as RateLimiterOptions<Setter<TValue>>)
-  const selector = hasInitialValue
-    ? maybeSelector
-    : (initialOptionsOrSelector as
-        | ((state: RateLimiterState) => TSelected)
-        | undefined)
-
-  const rateLimited = injectRateLimitedSignal(
-    initialValue,
-    initialOptions,
-    selector,
-  )
-
-  effect(() => {
-    const latest = value()
-    rateLimited.set(latest)
-  })
-
-  return rateLimited
-}

package/src/rate-limiter/injectRateLimiter.ts

@@ -1,140 +0,0 @@
-import { DestroyRef, inject } from '@angular/core'
-import { injectSelector } 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/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 = {},
-> extends Omit<RateLimiter<TFn>, 'store'> {
-  /**
-   * Reactive state signal that will be updated when the 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<RateLimiterState>>
-}
-
-/**
- * An Angular function that creates and manages a RateLimiter instance.
- *
- * This is a lower-level function that provides direct access to the RateLimiter's functionality.
- * This allows you to integrate it with any state management solution you prefer.
- *
- * Rate limiting is a simple "hard limit" approach that allows executions until a maximum count is reached within
- * a time window, then blocks all subsequent calls until the window resets. Unlike throttling or debouncing,
- * it does not attempt to space out or collapse executions intelligently.
- *
- * The rate limiter supports two types of windows:
- * - 'fixed': A strict window that resets after the window period. All executions within the window count
- *   towards the limit, and the window resets completely after the period.
- * - 'sliding': A rolling window that allows executions as old ones expire. This provides a more
- *   consistent rate of execution over time.
- *
- * For smoother execution patterns:
- * - Use throttling when you want consistent spacing between executions (e.g. UI updates)
- * - Use debouncing when you want to collapse rapid-fire events (e.g. search input)
- * - Use rate limiting only when you need to enforce hard limits (e.g. API rate limits)
- *
- * ## 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:
- * - `executionCount`: Number of function executions that have been completed
- * - `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
- * const rateLimiter = injectRateLimiter(apiCall, {
- *   limit: 5,
- *   window: 60000,
- *   windowType: 'sliding',
- * });
- *
- * // Opt-in to track execution count changes
- * const rateLimiter = injectRateLimiter(
- *   apiCall,
- *   {
- *     limit: 5,
- *     window: 60000,
- *     windowType: 'sliding',
- *   },
- *   (state) => ({ executionCount: state.executionCount })
- * );
- *
- * // Monitor rate limit status
- * const handleClick = () => {
- *   const remaining = rateLimiter.getRemainingInWindow();
- *   if (remaining > 0) {
- *     rateLimiter.maybeExecute(data);
- *   } else {
- *     showRateLimitWarning();
- *   }
- * };
- *
- * // Access the selected state (will be empty object {} unless selector provided)
- * const { executionCount, rejectionCount } = rateLimiter.state();
- * ```
- */
-export function injectRateLimiter<TFn extends AnyFunction, TSelected = {}>(
-  fn: TFn,
-  options: AngularRateLimiterOptions<TFn, TSelected>,
-  selector: (state: RateLimiterState) => TSelected = () => ({}) as TSelected,
-): AngularRateLimiter<TFn, TSelected> {
-  const mergedOptions = {
-    ...injectPacerOptions().rateLimiter,
-    ...options,
-  } as AngularRateLimiterOptions<TFn, TSelected>
-
-  const rateLimiter = new RateLimiter<TFn>(fn, mergedOptions)
-  const state = injectSelector(rateLimiter.store, selector)
-
-  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/index.ts

@@ -1,6 +0,0 @@
-export * from '@tanstack/pacer/throttler'
-
-export * from './injectThrottledCallback'
-export * from './injectThrottledSignal'
-export * from './injectThrottledValue'
-export * from './injectThrottler'

package/src/throttler/injectThrottledCallback.ts

@@ -1,45 +0,0 @@
-import { injectThrottler } from './injectThrottler'
-import type { ThrottlerOptions } from '@tanstack/pacer/throttler'
-import type { AnyFunction } from '@tanstack/pacer/types'
-
-/**
- * An Angular function that creates a throttled version of a callback function.
- * This function is essentially a wrapper around `injectThrottler` that provides
- * a simplified API for basic throttling needs.
- *
- * The throttled function will execute at most once within the specified wait time.
- * If called multiple times within the wait period, only the first call (if leading is enabled)
- * or the last call (if trailing is enabled) will execute.
- *
- * This function provides a simpler API compared to `injectThrottler`, making it ideal for basic
- * throttling needs. However, it does not expose the underlying Throttler instance.
- *
- * For advanced usage requiring features like:
- * - Manual cancellation
- * - Access to execution counts
- * - State tracking
- *
- * Consider using the `injectThrottler` function instead.
- *
- * @example
- * ```ts
- * // Throttle a scroll handler
- * const handleScroll = injectThrottledCallback((scrollY: number) => {
- *   updateScrollPosition(scrollY);
- * }, {
- *   wait: 100 // Execute at most once per 100ms
- * });
- *
- * // Use in an event listener
- * window.addEventListener('scroll', () => {
- *   handleScroll(window.scrollY);
- * });
- * ```
- */
-export function injectThrottledCallback<TFn extends AnyFunction>(
-  fn: TFn,
-  options: ThrottlerOptions<TFn>,
-): (...args: Parameters<TFn>) => void {
-  const throttler = injectThrottler(fn, options)
-  return (...args: Parameters<TFn>) => throttler.maybeExecute(...args)
-}