@tanstack/angular-pacer 0.23.1 → 0.25.0

package/src/throttler/injectThrottledSignal.ts

@@ -1,95 +0,0 @@
-import { signal } from '@angular/core'
-import { injectThrottler } from './injectThrottler'
-import type { AngularThrottler } from './injectThrottler'
-import type {
-  ThrottlerOptions,
-  ThrottlerState,
-} from '@tanstack/pacer/throttler'
-
-type Setter<T> = (value: T | ((prev: T) => T)) => void
-
-export interface ThrottledSignal<TValue, TSelected = {}> {
-  (): TValue
-  set: Setter<TValue>
-  throttler: AngularThrottler<Setter<TValue>, TSelected>
-}
-
-/**
- * An Angular function that creates a throttled state signal, combining Angular's signal with throttling functionality.
- * This function provides both the current throttled value and methods to update it.
- *
- * The state value is updated at most once within the specified wait time.
- * This is useful for handling frequent state updates that should be rate-limited, like scroll positions
- * or mouse movements.
- *
- * The function returns a callable object:
- * - `throttled()`: Get the current throttled value
- * - `throttled.set(...)`: Set or update the throttled value (throttled via maybeExecute)
- * - `throttled.throttler`: The throttler instance with additional control methods and state signals
- *
- * ## State Management and Selector
- *
- * The function uses TanStack Store for reactive state management via the underlying throttler instance.
- * The `selector` parameter allows you to specify which throttler 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.
- *
- * Available throttler state properties:
- * - `canLeadingExecute`: Whether the throttler can execute on the leading edge
- * - `canTrailingExecute`: Whether the throttler can execute on the trailing edge
- * - `executionCount`: Number of function executions that have been completed
- * - `isPending`: Whether the throttler is waiting for the timeout to trigger execution
- * - `lastArgs`: The arguments from the most recent call to maybeExecute
- * - `lastExecutionTime`: Timestamp of the last execution
- * - `nextExecutionTime`: Timestamp of the next allowed execution
- * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
- *
- * @example
- * ```ts
- * const throttledScrollY = injectThrottledSignal(0, { wait: 100 })
- *
- * // Get value
- * console.log(throttledScrollY())
- *
- * // Set/update value (throttled)
- * throttledScrollY.set(window.scrollY)
- *
- * // Access throttler
- * console.log(throttledScrollY.throttler.state().isPending)
- * ```
- */
-export function injectThrottledSignal<TValue, TSelected = {}>(
-  value: TValue,
-  initialOptions: ThrottlerOptions<Setter<TValue>>,
-  selector?: (state: ThrottlerState<Setter<TValue>>) => TSelected,
-): ThrottledSignal<TValue, TSelected> {
-  const throttledValue = signal<TValue>(value)
-
-  const throttler = injectThrottler(
-    (newValue: TValue | ((prev: TValue) => TValue)) => {
-      if (typeof newValue === 'function') {
-        throttledValue.update(newValue as (prev: TValue) => TValue)
-      } else {
-        throttledValue.set(newValue)
-      }
-    },
-    initialOptions,
-    selector,
-  )
-
-  const set: Setter<TValue> = (
-    newValue: TValue | ((prev: TValue) => TValue),
-  ) => {
-    throttler.maybeExecute(newValue)
-  }
-
-  const throttled = Object.assign(() => throttledValue(), {
-    set,
-    throttler,
-  }) as ThrottledSignal<TValue, TSelected>
-
-  return throttled
-}

package/src/throttler/injectThrottledValue.ts

@@ -1,124 +0,0 @@
-import { effect } from '@angular/core'
-import { injectThrottledSignal } from './injectThrottledSignal'
-import type { ThrottledSignal } from './injectThrottledSignal'
-import type { Signal } from '@angular/core'
-import type {
-  ThrottlerOptions,
-  ThrottlerState,
-} from '@tanstack/pacer/throttler'
-
-type Setter<T> = (value: T | ((prev: T) => T)) => void
-
-/**
- * An Angular function that creates a throttled value that updates at most once within a specified time window.
- * Unlike injectThrottledSignal, this function automatically tracks changes to the input signal
- * and updates the throttled value accordingly.
- *
- * The throttled value will update at most once within the specified wait time, regardless of
- * how frequently the input value changes.
- *
- * This is useful for deriving throttled values from signals that change frequently,
- * like scroll positions or mouse coordinates, where you want to limit how often downstream effects
- * or calculations occur.
- *
- * The function returns a throttled signal object containing:
- * - A Signal that provides the current throttled value
- * - The throttler instance with control methods
- *
- * ## State Management and Selector
- *
- * The function uses TanStack Store for reactive state management via the underlying throttler instance.
- * The `selector` parameter allows you to specify which throttler 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.
- *
- * Available throttler state properties:
- * - `canLeadingExecute`: Whether the throttler can execute on the leading edge
- * - `canTrailingExecute`: Whether the throttler can execute on the trailing edge
- * - `executionCount`: Number of function executions that have been completed
- * - `isPending`: Whether the throttler is waiting for the timeout to trigger execution
- * - `lastArgs`: The arguments from the most recent call to maybeExecute
- * - `lastExecutionTime`: Timestamp of the last execution
- * - `nextExecutionTime`: Timestamp of the next allowed execution
- * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
- *
- * @example
- * ```ts
- * // Default behavior - no reactive state subscriptions
- * const scrollY = signal(0)
- * const throttledScrollY = injectThrottledValue(scrollY, {
- *   wait: 100, // Update at most once per 100ms
- * })
- *
- * // Opt-in to reactive updates when pending state changes
- * const throttledScrollYWithState = injectThrottledValue(
- *   scrollY,
- *   { wait: 100 },
- *   (state) => ({ isPending: state.isPending }),
- * )
- *
- * // Read the throttled signal value
- * effect(() => {
- *   updateUI(throttledScrollY())
- * })
- *
- * // Access throttler state via the returned object's state() signal
- * console.log('Is pending:', throttledScrollYWithState.state().isPending)
- *
- * // Control the throttler
- * throttledScrollY.cancel() // Cancel any pending updates
- * ```
- */
-export function injectThrottledValue<TValue, TSelected = {}>(
-  value: Signal<TValue>,
-  initialOptions: ThrottlerOptions<Setter<TValue>>,
-  selector?: (state: ThrottlerState<Setter<TValue>>) => TSelected,
-): ThrottledSignal<TValue, TSelected>
-export function injectThrottledValue<TValue, TSelected = {}>(
-  value: Signal<TValue>,
-  initialValue: TValue,
-  initialOptions: ThrottlerOptions<Setter<TValue>>,
-  selector?: (state: ThrottlerState<Setter<TValue>>) => TSelected,
-): ThrottledSignal<TValue, TSelected>
-export function injectThrottledValue<TValue, TSelected = {}>(
-  value: Signal<TValue>,
-  initialValueOrOptions: TValue | ThrottlerOptions<Setter<TValue>>,
-  initialOptionsOrSelector?:
-    | ThrottlerOptions<Setter<TValue>>
-    | ((state: ThrottlerState<Setter<TValue>>) => TSelected),
-  maybeSelector?: (state: ThrottlerState<Setter<TValue>>) => TSelected,
-): ThrottledSignal<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 ThrottlerOptions<Setter<TValue>>)
-    : (initialValueOrOptions as ThrottlerOptions<Setter<TValue>>)
-  const selector = hasInitialValue
-    ? maybeSelector
-    : (initialOptionsOrSelector as
-        | ((state: ThrottlerState<Setter<TValue>>) => TSelected)
-        | undefined)
-
-  const throttledValue = injectThrottledSignal(
-    initialValue,
-    initialOptions,
-    selector,
-  )
-
-  effect(() => {
-    const latest = value()
-    throttledValue.set(latest)
-  })
-
-  return throttledValue
-}

package/src/throttler/injectThrottler.ts

@@ -1,137 +0,0 @@
-import { DestroyRef, inject } from '@angular/core'
-import { injectSelector } from '@tanstack/angular-store'
-import { Throttler } from '@tanstack/pacer/throttler'
-import { injectPacerOptions } from '../provider/pacer-context'
-import type { Signal } from '@angular/core'
-import type { Store } from '@tanstack/angular-store'
-import type { AnyFunction } from '@tanstack/pacer/types'
-import type {
-  ThrottlerOptions,
-  ThrottlerState,
-} from '@tanstack/pacer/throttler'
-
-export interface AngularThrottlerOptions<
-  TFn extends AnyFunction,
-  TSelected = {},
-> extends ThrottlerOptions<TFn> {
-  /**
-   * Optional callback invoked when the component is destroyed. Receives the throttler instance.
-   * When provided, replaces the default cleanup (cancel); use it to call flush(), cancel(), add logging, etc.
-   */
-  onUnmount?: (throttler: AngularThrottler<TFn, TSelected>) => void
-}
-
-export interface AngularThrottler<
-  TFn extends AnyFunction,
-  TSelected = {},
-> extends Omit<Throttler<TFn>, 'store'> {
-  /**
-   * Reactive state signal that will be updated when the 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<ThrottlerState<TFn>>>
-}
-
-/**
- * An Angular function that creates and manages a Throttler instance.
- *
- * This is a lower-level function that provides direct access to the Throttler's functionality.
- * This allows you to integrate it with any state management solution you prefer.
- *
- * This function provides throttling functionality to limit how often a function can be called,
- * ensuring it executes at most once within a specified time window.
- *
- * The throttler will execute the function immediately (if leading is enabled) and then
- * prevent further executions until the wait period has elapsed.
- *
- * ## 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 throttler can execute on the leading edge
- * - `canTrailingExecute`: Whether the throttler can execute on the trailing edge
- * - `executionCount`: Number of function executions that have been completed
- * - `isPending`: Whether the throttler is waiting for the timeout to trigger execution
- * - `lastArgs`: The arguments from the most recent call to maybeExecute
- * - `lastExecutionTime`: Timestamp of the last execution
- * - `nextExecutionTime`: Timestamp of the next allowed execution
- * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
- *
- * ## Cleanup on Destroy
- *
- * By default, the function cancels any pending execution when the component is destroyed.
- * Use the `onUnmount` option to customize this. For example, to flush pending work instead:
- *
- * ```ts
- * const throttler = injectThrottler(fn, {
- *   wait: 100,
- *   onUnmount: (t) => t.flush()
- * });
- * ```
- *
- * @example
- * ```ts
- * // Default behavior - no reactive state subscriptions
- * const throttler = injectThrottler(
- *   (scrollY: number) => updateScrollPosition(scrollY),
- *   { wait: 100 }
- * );
- *
- * // Opt-in to track isPending changes (optimized for loading states)
- * const throttler = injectThrottler(
- *   (scrollY: number) => updateScrollPosition(scrollY),
- *   { wait: 100 },
- *   (state) => ({ isPending: state.isPending })
- * );
- *
- * // In an event handler
- * window.addEventListener('scroll', () => {
- *   throttler.maybeExecute(window.scrollY);
- * });
- *
- * // Access the selected state (will be empty object {} unless selector provided)
- * const { isPending } = throttler.state();
- * ```
- */
-export function injectThrottler<TFn extends AnyFunction, TSelected = {}>(
-  fn: TFn,
-  options: AngularThrottlerOptions<TFn, TSelected>,
-  selector: (state: ThrottlerState<TFn>) => TSelected = () => ({}) as TSelected,
-): AngularThrottler<TFn, TSelected> {
-  const mergedOptions = {
-    ...injectPacerOptions().throttler,
-    ...options,
-  } as AngularThrottlerOptions<TFn, TSelected>
-
-  const throttler = new Throttler<TFn>(fn, mergedOptions)
-  const state = injectSelector(throttler.store, selector)
-
-  const result = {
-    ...throttler,
-    state,
-  } as AngularThrottler<TFn, TSelected>
-
-  const destroyRef = inject(DestroyRef, { optional: true })
-  destroyRef?.onDestroy(() => {
-    if (mergedOptions.onUnmount) {
-      mergedOptions.onUnmount(result)
-    } else {
-      throttler.cancel()
-    }
-  })
-
-  return result
-}

package/src/types/index.ts

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

package/src/utils/index.ts

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