@tanstack/pacer 0.15.4 → 0.16.1

package/src/async-throttler.ts

@@ -1,6 +1,8 @@
 import { Store } from '@tanstack/store'
-import { createKey, parseFunctionOrValue } from './utils'
+import { AsyncRetryer } from './async-retryer'
+import { parseFunctionOrValue } from './utils'
 import { emitChange, pacerEventClient } from './event-client'
+import type { AsyncRetryerOptions } from './async-retryer'
 import type { AnyAsyncFunction, OptionalKeys } from './types'
 
 export interface AsyncThrottlerState<TFn extends AnyAsyncFunction> {
@@ -72,6 +74,10 @@ function getDefaultAsyncThrottlerState<
  * Options for configuring an async throttled function
  */
 export interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {
+  /**
+   * Options for configuring the underlying async retryer
+   */
+  asyncRetryerOptions?: AsyncRetryerOptions<TFn>
   /**
    * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.
    * Can be a boolean or a function that returns a boolean.
@@ -98,7 +104,7 @@ export interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {
    * This can be used alongside throwOnError - the handler will be called before any error is thrown.
    */
   onError?: (
-    error: unknown,
+    error: Error,
     args: Parameters<TFn>,
     asyncThrottler: AsyncThrottler<TFn>,
   ) => void
@@ -136,12 +142,27 @@ export interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {
   wait: number | ((throttler: AsyncThrottler<TFn>) => number)
 }
 
+/**
+ * Utility function for sharing common `AsyncThrottlerOptions` options between different `AsyncThrottler` instances.
+ */
+export function asyncThrottlerOptions<
+  TFn extends AnyAsyncFunction = AnyAsyncFunction,
+  TOptions extends Partial<AsyncThrottlerOptions<TFn>> = Partial<
+    AsyncThrottlerOptions<TFn>
+  >,
+>(options: TOptions): TOptions {
+  return options
+}
+
 type AsyncThrottlerOptionsWithOptionalCallbacks = OptionalKeys<
   AsyncThrottlerOptions<any>,
   'initialState' | 'onError' | 'onSettled' | 'onSuccess'
 >
 
 const defaultOptions: AsyncThrottlerOptionsWithOptionalCallbacks = {
+  asyncRetryerOptions: {
+    maxAttempts: 1,
+  },
   enabled: true,
   leading: true,
   trailing: true,
@@ -151,14 +172,24 @@ const defaultOptions: AsyncThrottlerOptionsWithOptionalCallbacks = {
 /**
  * A class that creates an async throttled function.
  *
+ * Async vs Sync Versions:
+ * The async version provides advanced features over the sync Throttler:
+ * - Returns promises that can be awaited for throttled function results
+ * - Built-in retry support via AsyncRetryer integration
+ * - Abort support to cancel in-flight executions
+ * - Cancel support to prevent pending executions from starting
+ * - Comprehensive error handling with onError callbacks and throwOnError control
+ * - Detailed execution tracking (success/error/settle counts)
+ * - Waits for ongoing executions to complete before scheduling the next one
+ *
+ * The sync Throttler is lighter weight and simpler when you don't need async features,
+ * return values, or execution control.
+ *
+ * What is Throttling?
  * Throttling limits how often a function can be executed, allowing only one execution within a specified time window.
  * Unlike debouncing which resets the delay timer on each call, throttling ensures the function executes at a
  * regular interval regardless of how often it's called.
  *
- * Unlike the non-async Throttler, this async version supports returning values from the throttled function,
- * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call
- * instead of setting the result on a state variable from within the throttled function.
- *
  * This is useful for rate-limiting API calls, handling scroll/resize events, or any scenario where you want to
  * ensure a maximum execution frequency.
  *
@@ -200,9 +231,9 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
   readonly store: Store<Readonly<AsyncThrottlerState<TFn>>> = new Store<
     AsyncThrottlerState<TFn>
   >(getDefaultAsyncThrottlerState<TFn>())
-  key: string
+  key: string | undefined
   options: AsyncThrottlerOptions<TFn>
-  #abortController: AbortController | null = null
+  asyncRetryers = new Map<number, AsyncRetryer<TFn>>()
   #timeoutId: NodeJS.Timeout | null = null
   #resolvePreviousPromise:
     | ((value?: ReturnType<TFn> | undefined) => void)
@@ -212,13 +243,14 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
     public fn: TFn,
     initialOptions: AsyncThrottlerOptions<TFn>,
   ) {
-    this.key = createKey(initialOptions.key)
+    this.key = initialOptions.key
     this.options = {
       ...defaultOptions,
       ...initialOptions,
       throwOnError: initialOptions.throwOnError ?? !initialOptions.onError,
     }
     this.#setState(this.options.initialState ?? {})
+
     pacerEventClient.on('d-AsyncThrottler', (event) => {
       if (event.payload.key !== this.key) return
       this.#setState(event.payload.store.state as AsyncThrottlerState<TFn>)
@@ -301,88 +333,119 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
     ...args: Parameters<TFn>
   ): Promise<ReturnType<TFn> | undefined> => {
     if (!this.#getEnabled()) return undefined
-    const now = Date.now()
-    const timeSinceLastExecution = now - this.store.state.lastExecutionTime
-    const wait = this.#getWait()
-    // Store the most recent arguments for potential trailing execution
+
+    this.#resolvePreviousPromiseInternal()
+
     this.#setState({
-      lastArgs: args,
       maybeExecuteCount: this.store.state.maybeExecuteCount + 1,
+      lastArgs: args, // store the arguments for potential trailing execution
     })
 
-    this.#resolvePreviousPromiseInternal()
+    const wait = this.#getWait()
+    const thisMaybeExecuteNumber = this.store.state.maybeExecuteCount
 
-    // Handle leading execution
-    if (this.options.leading && timeSinceLastExecution >= wait) {
-      await this.#execute(...args)
-      return this.store.state.lastResult
-    } else {
+    // Wait for the wait period for the previous execution to complete if it's still running
+    for (
+      let maxNumIterations = wait / 10;
+      this.store.state.isExecuting && maxNumIterations > 0;
+      maxNumIterations--
+    ) {
+      await new Promise((resolve) => setTimeout(resolve, 10))
+      if (this.store.state.maybeExecuteCount !== thisMaybeExecuteNumber) {
+        // cancel the current maybeExecute loop because a new maybeExecute call was made
+        return this.store.state.lastResult
+      }
+    }
+
+    const now = Date.now()
+    const timeSinceLastExecution = now - this.store.state.lastExecutionTime
+
+    if (
+      this.options.leading &&
+      !this.store.state.isPending &&
+      timeSinceLastExecution >= wait
+    ) {
+      await this.#execute(...args) // Leading EXECUTE!
+    } else if (this.options.trailing) {
+      // replace old pending execution with a new one
+      this.cancel()
+      this.#setState({
+        isPending: true,
+      })
+
+      // Set up new trailing execution
       return new Promise((resolve, reject) => {
         this.#resolvePreviousPromise = resolve
-        // Clear any existing timeout to ensure we use the latest arguments
-        this.#clearTimeout()
-
-        // Set up trailing execution if enabled
-        if (this.options.trailing) {
-          const _timeSinceLastExecution = this.store.state.lastExecutionTime
-            ? now - this.store.state.lastExecutionTime
-            : 0
-          const timeoutDuration = wait - _timeSinceLastExecution
-          this.#setState({ isPending: true })
-          this.#timeoutId = setTimeout(async () => {
-            if (this.store.state.lastArgs !== undefined) {
-              try {
-                await this.#execute(...this.store.state.lastArgs) // EXECUTE!
-              } catch (error) {
-                reject(error)
-              }
+
+        const newTimeSinceLastExecution = this.store.state.lastExecutionTime
+          ? now - this.store.state.lastExecutionTime
+          : 0
+        const timeoutDuration = Math.max(0, wait - newTimeSinceLastExecution)
+
+        this.#timeoutId = setTimeout(async () => {
+          this.#clearTimeout()
+          if (this.store.state.lastArgs !== undefined) {
+            try {
+              await this.#execute(...this.store.state.lastArgs) // Trailing EXECUTE!
+            } catch (error) {
+              reject(error)
             }
-            this.#resolvePreviousPromise = null
-            resolve(this.store.state.lastResult)
-          }, timeoutDuration)
-        }
+          }
+          this.#resolvePreviousPromise = null
+          resolve(this.store.state.lastResult)
+        }, timeoutDuration)
       })
     }
+    return this.store.state.lastResult
   }
 
   #execute = async (
     ...args: Parameters<TFn>
   ): Promise<ReturnType<TFn> | undefined> => {
-    if (!this.#getEnabled() || this.store.state.isExecuting) return undefined
-    this.#abortController = new AbortController()
+    if (!this.#getEnabled()) return undefined
+
+    const currentMaybeExecute = this.store.state.maybeExecuteCount
+
     try {
       this.#setState({ isExecuting: true })
-      const result = await this.fn(...args) // EXECUTE!
+      const currentAsyncRetryer = new AsyncRetryer(this.fn, {
+        ...this.options.asyncRetryerOptions,
+        key: `${this.key}-retryer-${currentMaybeExecute}`,
+      })
+      this.asyncRetryers.set(currentMaybeExecute, currentAsyncRetryer)
+      const result = await currentAsyncRetryer.execute(...args) // EXECUTE!
       this.#setState({
         lastResult: result,
         successCount: this.store.state.successCount + 1,
       })
-      this.options.onSuccess?.(result, args, this)
+      this.options.onSuccess?.(result as ReturnType<TFn>, args, this)
     } catch (error) {
       this.#setState({
         errorCount: this.store.state.errorCount + 1,
       })
-      this.options.onError?.(error, args, this)
+      this.options.onError?.(error as Error, args, this)
       if (this.options.throwOnError) {
         throw error
       }
     } finally {
+      this.asyncRetryers.delete(currentMaybeExecute) // dispose retryer
       const lastExecutionTime = Date.now()
-      const nextExecutionTime = lastExecutionTime + this.#getWait()
+      const wait = this.#getWait()
+      const nextExecutionTime = lastExecutionTime + wait
       this.#setState({
         isExecuting: false,
-        isPending: false,
+        isPending: !!this.#timeoutId,
         settleCount: this.store.state.settleCount + 1,
         lastExecutionTime,
         nextExecutionTime,
       })
-      this.#abortController = null
       this.options.onSettled?.(args, this)
       setTimeout(() => {
         if (!this.store.state.isPending) {
+          // clear nextExecutionTime if there is no pending execution
           this.#setState({ nextExecutionTime: undefined })
         }
-      }, this.#getWait())
+      }, wait)
     }
     return this.store.state.lastResult
   }
@@ -392,12 +455,21 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
    */
   flush = async (): Promise<ReturnType<TFn> | undefined> => {
     if (this.store.state.isPending && this.store.state.lastArgs) {
-      this.#abortExecution() // abort any current execution
-      this.#clearTimeout() // clear any existing timeout
+      // Store the pending promise resolver before clearing timeout
+      const resolvePromise = this.#resolvePreviousPromise
+
+      // Clear timeout and state without resolving the promise
+      this.#clearTimeout()
+      this.#setState({
+        isPending: false,
+      })
+
       const result = await this.#execute(...this.store.state.lastArgs)
 
-      // Resolve any pending promise from maybeExecute
-      this.#resolvePreviousPromiseInternal()
+      // Resolve the pending promise with the result
+      if (resolvePromise) {
+        resolvePromise(result)
+      }
 
       return result
     }
@@ -418,7 +490,51 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
     }
   }
 
-  #cancelPendingExecution = (): void => {
+  /**
+   * Returns the AbortSignal for a specific execution.
+   * If no maybeExecuteCount is provided, returns the signal for the most recent execution.
+   * Returns null if no execution is found or not currently executing.
+   *
+   * @param maybeExecuteCount - Optional specific execution to get signal for
+   * @example
+   * ```typescript
+   * const throttler = new AsyncThrottler(
+   *   async (data: string) => {
+   *     const signal = throttler.getAbortSignal()
+   *     if (signal) {
+   *       const response = await fetch('/api/save', {
+   *         method: 'POST',
+   *         body: data,
+   *         signal
+   *       })
+   *       return response.json()
+   *     }
+   *   },
+   *   { wait: 1000 }
+   * )
+   * ```
+   */
+  getAbortSignal(maybeExecuteCount?: number): AbortSignal | null {
+    const count = maybeExecuteCount ?? this.store.state.maybeExecuteCount
+    const retryer = this.asyncRetryers.get(count)
+    return retryer?.getAbortSignal() ?? null
+  }
+
+  /**
+   * Aborts all ongoing executions with the internal abort controllers.
+   * Does NOT cancel any pending execution that have not started yet.
+   */
+  abort = (): void => {
+    this.asyncRetryers.forEach((retryer) => retryer.abort())
+    this.asyncRetryers.clear()
+    this.#setState({ isExecuting: false })
+  }
+
+  /**
+   * Cancels any pending execution that have not started yet.
+   * Does NOT abort any execution already in progress.
+   */
+  cancel = (): void => {
     this.#clearTimeout()
     if (this.#resolvePreviousPromise) {
       this.#resolvePreviousPromiseInternal()
@@ -426,31 +542,15 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
     }
     this.#setState({
       isPending: false,
-      isExecuting: false,
-      lastArgs: undefined,
     })
   }
 
-  #abortExecution = (): void => {
-    if (this.#abortController) {
-      this.#abortController.abort()
-      this.#abortController = null
-    }
-  }
-
-  /**
-   * Cancels any pending execution or aborts any execution in progress
-   */
-  cancel = (): void => {
-    this.#cancelPendingExecution()
-    this.#abortExecution()
-  }
-
   /**
    * Resets the debouncer state to its default values
    */
   reset = (): void => {
     this.#setState(getDefaultAsyncThrottlerState<TFn>())
+    this.asyncRetryers.forEach((retryer) => retryer.reset())
   }
 }
 
@@ -459,9 +559,30 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
  * The throttled function will execute at most once per wait period, even if called multiple times.
  * If called while executing, it will wait until execution completes before scheduling the next call.
  *
- * Unlike the non-async Throttler, this async version supports returning values from the throttled function,
- * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call
- * instead of setting the result on a state variable from within the throttled function.
+ * Async vs Sync Versions:
+ * The async version provides advanced features over the sync throttle function:
+ * - Returns promises that can be awaited for throttled function results
+ * - Built-in retry support via AsyncRetryer integration
+ * - Abort support to cancel in-flight executions
+ * - Cancel support to prevent pending executions from starting
+ * - Comprehensive error handling with onError callbacks and throwOnError control
+ * - Detailed execution tracking (success/error/settle counts)
+ * - Waits for ongoing executions to complete before scheduling the next one
+ *
+ * The sync throttle function is lighter weight and simpler when you don't need async features,
+ * return values, or execution control.
+ *
+ * What is Throttling?
+ * Throttling limits how often a function can be executed, allowing only one execution within a specified time window.
+ * Unlike debouncing which resets the delay timer on each call, throttling ensures the function executes at a
+ * regular interval regardless of how often it's called.
+ *
+ * Configuration Options:
+ * - `wait`: Time window in milliseconds during which the function can only execute once (required)
+ * - `leading`: Execute immediately when called (default: true)
+ * - `trailing`: Execute on the trailing edge of the wait period (default: true)
+ * - `enabled`: Whether the throttler is enabled (default: true)
+ * - `asyncRetryerOptions`: Configure retry behavior for executions
  *
  * Error Handling:
  * - If an `onError` handler is provided, it will be called with the error and throttler instance

package/src/batcher.ts

@@ -1,5 +1,5 @@
 import { Store } from '@tanstack/store'
-import { createKey, parseFunctionOrValue } from './utils'
+import { parseFunctionOrValue } from './utils'
 import { emitChange, pacerEventClient } from './event-client'
 import type { OptionalKeys } from './types'
 
@@ -107,6 +107,7 @@ const defaultOptions: BatcherOptionsWithOptionalCallbacks<any> = {
  * A class that collects items and processes them in batches.
  *
  * Batching is a technique for grouping multiple operations together to be processed as a single unit.
+ * This synchronous version is lighter weight and often all you need - upgrade to AsyncBatcher when you need promises, retry support, abort/cancel capabilities, or advanced error handling.
  *
  * The Batcher provides a flexible way to implement batching with configurable:
  * - Maximum batch size (number of items per batch)
@@ -145,7 +146,7 @@ export class Batcher<TValue> {
   readonly store: Store<Readonly<BatcherState<TValue>>> = new Store(
     getDefaultBatcherState<TValue>(),
   )
-  key: string
+  key: string | undefined
   options: BatcherOptionsWithOptionalCallbacks<TValue>
   #timeoutId: NodeJS.Timeout | null = null
 
@@ -153,7 +154,7 @@ export class Batcher<TValue> {
     public fn: (items: Array<TValue>) => void,
     initialOptions: BatcherOptions<TValue>,
   ) {
-    this.key = createKey(initialOptions.key)
+    this.key = initialOptions.key
     this.options = {
       ...defaultOptions,
       ...initialOptions,
@@ -275,6 +276,15 @@ export class Batcher<TValue> {
     this.#setState({ items: [], isPending: false })
   }
 
+  /**
+   * Cancels any pending execution that was scheduled.
+   * Does NOT clear out the items.
+   */
+  cancel = (): void => {
+    this.#clearTimeout()
+    this.#setState({ isPending: false })
+  }
+
   /**
    * Resets the batcher state to its default values
    */
@@ -285,7 +295,9 @@ export class Batcher<TValue> {
 }
 
 /**
- * Creates a batcher that processes items in batches
+ * Creates a batcher that processes items in batches.
+ *
+ * This synchronous version is lighter weight and often all you need - upgrade to asyncBatch when you need promises, retry support, abort/cancel capabilities, or advanced error handling.
  *
  * @example
  * ```ts

package/src/debouncer.ts

@@ -1,5 +1,5 @@
 import { Store } from '@tanstack/store'
-import { createKey, parseFunctionOrValue } from './utils'
+import { parseFunctionOrValue } from './utils'
 import { emitChange, pacerEventClient } from './event-client'
 import type { AnyFunction } from './types'
 
@@ -85,6 +85,18 @@ export interface DebouncerOptions<TFn extends AnyFunction> {
   wait: number | ((debouncer: Debouncer<TFn>) => number)
 }
 
+/**
+ * Utility function for sharing common `DebouncerOptions` options between different `Debouncer` instances.
+ */
+export function debouncerOptions<
+  TFn extends AnyFunction = AnyFunction,
+  TOptions extends Partial<DebouncerOptions<TFn>> = Partial<
+    DebouncerOptions<TFn>
+  >,
+>(options: TOptions): TOptions {
+  return options
+}
+
 const defaultOptions: Omit<
   Required<DebouncerOptions<any>>,
   'initialState' | 'onExecute' | 'key'
@@ -101,6 +113,7 @@ const defaultOptions: Omit<
  * Debouncing ensures that a function is only executed after a certain amount of time has passed
  * since its last invocation. This is useful for handling frequent events like window resizing,
  * scroll events, or input changes where you want to limit the rate of execution.
+ * This synchronous version is lighter weight and often all you need - upgrade to AsyncDebouncer when you need promises, retry support, abort/cancel capabilities, or advanced error handling.
  *
  * The debounced function can be configured to execute either at the start of the delay period
  * (leading edge) or at the end (trailing edge, default). Each new call during the wait period
@@ -130,7 +143,7 @@ export class Debouncer<TFn extends AnyFunction> {
   readonly store: Store<Readonly<DebouncerState<TFn>>> = new Store(
     getDefaultDebouncerState<TFn>(),
   )
-  key: string
+  key: string | undefined
   options: DebouncerOptions<TFn>
   #timeoutId: NodeJS.Timeout | undefined
 
@@ -138,7 +151,7 @@ export class Debouncer<TFn extends AnyFunction> {
     public fn: TFn,
     initialOptions: DebouncerOptions<TFn>,
   ) {
-    this.key = createKey(initialOptions.key)
+    this.key = initialOptions.key
     this.options = {
       ...defaultOptions,
       ...initialOptions,
@@ -285,8 +298,7 @@ export class Debouncer<TFn extends AnyFunction> {
  * Creates a debounced function that delays invoking the provided function until after a specified wait time.
  * Multiple calls during the wait period will cancel previous pending invocations and reset the timer.
  *
- * This the the simple function wrapper implementation pulled from the Debouncer class. If you need
- * more control over the debouncing behavior, use the Debouncer class directly.
+ * This synchronous version is lighter weight and often all you need - upgrade to asyncDebounce when you need promises, retry support, abort/cancel capabilities, or advanced error handling.
  *
  * If leading option is true, the function will execute immediately on the first call, then wait the delay
  * before allowing another execution.

package/src/event-client.ts

@@ -3,6 +3,7 @@ import type { AsyncBatcher } from './async-batcher'
 import type { AsyncDebouncer } from './async-debouncer'
 import type { AsyncQueuer } from './async-queuer'
 import type { AsyncRateLimiter } from './async-rate-limiter'
+import type { AsyncRetryer } from './async-retryer'
 import type { AsyncThrottler } from './async-throttler'
 import type { Debouncer } from './debouncer'
 import type { Batcher } from './batcher'
@@ -15,6 +16,7 @@ export interface PacerEventMap {
   'pacer:d-AsyncDebouncer': AsyncDebouncer<any>
   'pacer:d-AsyncQueuer': AsyncQueuer<any>
   'pacer:d-AsyncRateLimiter': AsyncRateLimiter<any>
+  'pacer:d-AsyncRetryer': AsyncRetryer<any>
   'pacer:d-AsyncThrottler': AsyncThrottler<any>
   'pacer:d-Batcher': Batcher<any>
   'pacer:d-Debouncer': Debouncer<any>
@@ -25,6 +27,7 @@ export interface PacerEventMap {
   'pacer:AsyncDebouncer': AsyncDebouncer<any>
   'pacer:AsyncQueuer': AsyncQueuer<any>
   'pacer:AsyncRateLimiter': AsyncRateLimiter<any>
+  'pacer:AsyncRetryer': AsyncRetryer<any>
   'pacer:AsyncThrottler': AsyncThrottler<any>
   'pacer:Batcher': Batcher<any>
   'pacer:Debouncer': Debouncer<any>
@@ -57,7 +60,9 @@ export const emitChange = <
   event: TSuffix,
   payload: PacerEventMap[`pacer:${TSuffix}`],
 ) => {
-  pacerEventClient.emit(event, payload)
+  if (payload.key) {
+    pacerEventClient.emit(event, payload)
+  }
 }
 
 export const pacerEventClient = new PacerEventClient()

package/src/index.ts

@@ -2,6 +2,7 @@ export * from './async-batcher'
 export * from './async-debouncer'
 export * from './async-queuer'
 export * from './async-rate-limiter'
+export * from './async-retryer'
 export * from './async-throttler'
 export * from './batcher'
 export * from './debouncer'
@@ -10,5 +11,6 @@ export * from './rate-limiter'
 export * from './throttler'
 export * from './types'
 export * from './utils'
+
 export { pacerEventClient } from './event-client'
 export type { PacerEventMap, PacerEventName } from './event-client'

package/src/queuer.ts

@@ -1,5 +1,5 @@
 import { Store } from '@tanstack/store'
-import { createKey, parseFunctionOrValue } from './utils'
+import { parseFunctionOrValue } from './utils'
 import { emitChange, pacerEventClient } from './event-client'
 
 export interface QueuerState<TValue> {
@@ -151,6 +151,18 @@ export interface QueuerOptions<TValue> {
   wait?: number | ((queuer: Queuer<TValue>) => number)
 }
 
+/**
+ * Utility function for sharing common `QueuerOptions` options between different `Queuer` instances.
+ */
+export function queuerOptions<
+  TValue = any,
+  TOptions extends Partial<QueuerOptions<TValue>> = Partial<
+    QueuerOptions<TValue>
+  >,
+>(options: TOptions): TOptions {
+  return options
+}
+
 const defaultOptions: Omit<
   Required<QueuerOptions<any>>,
   | 'initialState'
@@ -183,6 +195,8 @@ export type QueuePosition = 'front' | 'back'
 /**
  * A flexible queue that processes items with configurable wait times, expiration, and priority.
  *
+ * This synchronous version is lighter weight and often all you need - upgrade to AsyncQueuer when you need promises, retry support, abort capabilities, concurrent execution, or advanced error handling.
+ *
  * Features:
  * - Automatic or manual processing of items
  * - FIFO (First In First Out), LIFO (Last In First Out), or double-ended queue behavior
@@ -256,7 +270,7 @@ export class Queuer<TValue> {
   readonly store: Store<Readonly<QueuerState<TValue>>> = new Store(
     getDefaultQueuerState<TValue>(),
   )
-  key: string
+  key: string | undefined
   options: QueuerOptions<TValue>
   #timeoutId: NodeJS.Timeout | null = null
 
@@ -264,7 +278,7 @@ export class Queuer<TValue> {
     public fn: (item: TValue) => void,
     initialOptions: QueuerOptions<TValue> = {},
   ) {
-    this.key = createKey(initialOptions.key)
+    this.key = initialOptions.key
     this.options = {
       ...defaultOptions,
       ...initialOptions,
@@ -287,6 +301,7 @@ export class Queuer<TValue> {
         this.addItem(item, this.options.addItemsTo ?? 'back', isLast)
       }
     }
+
     pacerEventClient.on('d-Queuer', (event) => {
       if (event.payload.key !== this.key) return
       this.#setState(event.payload.store.state)
@@ -681,9 +696,7 @@ export class Queuer<TValue> {
  * Creates a queue that processes items immediately upon addition.
  * Items are processed sequentially in FIFO order by default.
  *
- * This is a simplified wrapper around the Queuer class that only exposes the
- * `addItem` method. The queue is always isRunning and will process items as they are added.
- * For more control over queue processing, use the Queuer class directly.
+ * This synchronous version is lighter weight and often all you need - upgrade to asyncQueue when you need promises, retry support, abort capabilities, concurrent execution, or advanced error handling.
  *
  * State Management:
  * - Uses TanStack Store for reactive state management