@tanstack/angular-pacer 0.20.0

package/src/batcher/injectBatcher.ts

@@ -0,0 +1,79 @@
+import { injectStore } 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/store'
+import type { BatcherOptions, BatcherState } from '@tanstack/pacer/batcher'
+
+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.
+ *
+ * @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: BatcherOptions<TValue> = {},
+  selector: (state: BatcherState<TValue>) => TSelected = () =>
+    ({}) as TSelected,
+): AngularBatcher<TValue, TSelected> {
+  const mergedOptions = {
+    ...injectPacerOptions().batcher,
+    ...options,
+  } as BatcherOptions<TValue>
+
+  const batcher = new Batcher<TValue>(fn, mergedOptions)
+  const state = injectStore(batcher.store, selector)
+
+  return {
+    ...batcher,
+    state,
+  } as AngularBatcher<TValue, TSelected>
+}

package/src/debouncer/index.ts

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

package/src/debouncer/injectDebouncedCallback.ts

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

@@ -0,0 +1,101 @@
+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 type DebouncedSignal<TValue, TSelected = {}> = ((
+  ...args: []
+) => TValue) & {
+  /**
+   * Set or update the debounced value. This calls `debouncer.maybeExecute(...)`.
+   */
+  readonly set: Setter<TValue>
+  /**
+   * The debouncer instance with additional control methods and state signals.
+   */
+  readonly 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

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

@@ -0,0 +1,102 @@
+import { injectStore } 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/store'
+import type { AnyFunction } from '@tanstack/pacer/types'
+import type {
+  DebouncerOptions,
+  DebouncerState,
+} from '@tanstack/pacer/debouncer'
+
+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')
+ *
+ * @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: DebouncerOptions<TFn>,
+  selector: (state: DebouncerState<TFn>) => TSelected = () => ({}) as TSelected,
+): AngularDebouncer<TFn, TSelected> {
+  const mergedOptions = {
+    ...injectPacerOptions().debouncer,
+    ...options,
+  } as DebouncerOptions<TFn>
+
+  const debouncer = new Debouncer<TFn>(fn, mergedOptions)
+  const state = injectStore(debouncer.store, selector)
+
+  return {
+    ...debouncer,
+    state,
+  } as AngularDebouncer<TFn, TSelected>
+}

package/src/index.ts

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

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

package/src/provider/pacer-context.ts

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

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

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

package/src/queuer/injectQueuedSignal.ts

@@ -0,0 +1,70 @@
+import { computed } from '@angular/core'
+import { injectQueuer } from './injectQueuer'
+import type { AngularQueuer } from './injectQueuer'
+import type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
+
+export type QueuedSignal<TValue, TSelected = {}> = (() => Array<TValue>) & {
+  /**
+   * Add an item to the queue.
+   */
+  readonly addItem: AngularQueuer<TValue, TSelected>['addItem']
+  /**
+   * The queuer instance with additional control methods and state signals.
+   */
+  readonly 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
+}