@tanstack/solid-pacer 0.5.0 → 0.6.0

package/src/async-queuer/createAsyncQueuer.ts

@@ -2,34 +2,40 @@ import { AsyncQueuer } from '@tanstack/pacer/async-queuer'
 import { createSignal } from 'solid-js'
 import { bindInstanceMethods } from '@tanstack/pacer/utils'
 import type { Accessor } from 'solid-js'
-import type { AsyncQueuerOptions } from '@tanstack/pacer/async-queuer'
+import type {
+  AsyncQueuerFn,
+  AsyncQueuerOptions,
+} from '@tanstack/pacer/async-queuer'
 
-export interface SolidAsyncQueuer<TValue>
+export interface SolidAsyncQueuer<TFn extends AsyncQueuerFn>
   extends Omit<
-    AsyncQueuer<TValue>,
+    AsyncQueuer<TFn>,
     | 'getActiveItems'
     | 'getAllItems'
-    | 'getExecutionCount'
+    | 'getErrorCount'
     | 'getIsEmpty'
     | 'getIsFull'
     | 'getIsIdle'
     | 'getIsRunning'
     | 'getPeek'
     | 'getPendingItems'
+    | 'getRejectionCount'
+    | 'getSettledCount'
     | 'getSize'
+    | 'getSuccessCount'
   > {
   /**
    * Signal version of `getActiveItems`
    */
-  activeItems: Accessor<Array<() => Promise<TValue>>>
+  activeItems: Accessor<Array<TFn>>
   /**
    * Signal version of `getAllItems`
    */
-  allItems: Accessor<Array<() => Promise<TValue>>>
+  allItems: Accessor<Array<TFn>>
   /**
-   * Signal version of `getExecutionCount`
+   * Signal version of `getErrorCount`
    */
-  executionCount: Accessor<number>
+  errorCount: Accessor<number>
   /**
    * Signal version of `getIsEmpty`
    */
@@ -49,39 +55,50 @@ export interface SolidAsyncQueuer<TValue>
   /**
    * Signal version of `getPeek`
    */
-  peek: Accessor<(() => Promise<TValue>) | undefined>
+  peek: Accessor<TFn | undefined>
   /**
    * Signal version of `getPendingItems`
    */
-  pendingItems: Accessor<Array<() => Promise<TValue>>>
+  pendingItems: Accessor<Array<TFn>>
   /**
    * Signal version of `getRejectionCount`
    */
   rejectionCount: Accessor<number>
+  /**
+   * Signal version of `getSettledCount`
+   */
+  settledCount: Accessor<number>
   /**
    * Signal version of `getSize`
    */
   size: Accessor<number>
+  /**
+   * Signal version of `getSuccessCount`
+   */
+  successCount: Accessor<number>
 }
 
 /**
- * A lower-level React hook that creates an `AsyncQueuer` instance for managing an async queue of items.
+ * A lower-level Solid hook that creates an `AsyncQueuer` instance for managing an async queue of items.
  *
- * This hook provides a flexible, state-management agnostic way to handle queued async operations.
- * It returns a queuer instance with methods to add items, control queue execution, and monitor queue state.
+ * Features:
+ * - Priority queue support via getPriority option
+ * - Configurable concurrency limit
+ * - Task success/error/completion callbacks
+ * - FIFO (First In First Out) or LIFO (Last In First Out) queue behavior
+ * - Pause/resume task processing
+ * - Task cancellation
+ * - Item expiration to clear stale items from the queue
  *
- * The queue can be configured with:
- * - Maximum concurrent operations
- * - Maximum queue size
- * - Processing function for queue items
- * - Various lifecycle callbacks
+ * Tasks are processed concurrently up to the configured concurrency limit. When a task completes,
+ * the next pending task is processed if below the concurrency limit.
  *
- * The hook returns an object containing methods to:
- * - Add/remove items from the queue
- * - Start/stop queue processing
- * - Get queue status and items
- * - Register event handlers
- * - Control execution throttling
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and queuer instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncQueuer instance
  *
  * @example
  * ```tsx
@@ -91,6 +108,12 @@ export interface SolidAsyncQueuer<TValue>
  *   concurrency: 2,
  *   maxSize: 100,
  *   started: false,
+ *   onSuccess: (result) => {
+ *     console.log('Item processed:', result);
+ *   },
+ *   onError: (error) => {
+ *     console.error('Processing failed:', error);
+ *   }
  * });
  *
  * // Add items to queue
@@ -98,24 +121,19 @@ export interface SolidAsyncQueuer<TValue>
  *
  * // Start processing
  * asyncQueuer.start();
- *
- * // Handle results
- * asyncQueuer.onSuccess((result) => {
- *   console.log('Item processed:', result);
- * });
- *
- * asyncQueuer.onError((error) => {
- *   console.error('Processing failed:', error);
- * });
  * ```
  */
-export function createAsyncQueuer<TValue>(
-  initialOptions: AsyncQueuerOptions<TValue> = {},
-): SolidAsyncQueuer<TValue> {
-  const asyncQueuer = new AsyncQueuer<TValue>(initialOptions)
+export function createAsyncQueuer<TFn extends AsyncQueuerFn>(
+  initialOptions: AsyncQueuerOptions<TFn> = {},
+): SolidAsyncQueuer<TFn> {
+  const asyncQueuer = new AsyncQueuer<TFn>(initialOptions)
 
-  const [executionCount, setExecutionCount] = createSignal(
-    asyncQueuer.getExecutionCount(),
+  const [successCount, setSuccessCount] = createSignal(
+    asyncQueuer.getSuccessCount(),
+  )
+  const [errorCount, setErrorCount] = createSignal(asyncQueuer.getErrorCount())
+  const [settledCount, setSettledCount] = createSignal(
+    asyncQueuer.getSettledCount(),
   )
   const [rejectionCount, setRejectionCount] = createSignal(
     asyncQueuer.getRejectionCount(),
@@ -124,31 +142,32 @@ export function createAsyncQueuer<TValue>(
   const [isFull, setIsFull] = createSignal(asyncQueuer.getIsFull())
   const [isIdle, setIsIdle] = createSignal(asyncQueuer.getIsIdle())
   const [isRunning, setIsRunning] = createSignal(asyncQueuer.getIsRunning())
-  const [allItems, setAllItems] = createSignal<Array<() => Promise<TValue>>>(
+  const [allItems, setAllItems] = createSignal<Array<TFn>>(
     asyncQueuer.getAllItems(),
   )
-  const [activeItems, setActiveItems] = createSignal<
-    Array<() => Promise<TValue>>
-  >(asyncQueuer.getActiveItems())
-  const [pendingItems, setPendingItems] = createSignal<
-    Array<() => Promise<TValue>>
-  >(asyncQueuer.getPendingItems())
-  const [peek, setPeek] = createSignal<(() => Promise<TValue>) | undefined>(
-    asyncQueuer.getPeek(),
+  const [activeItems, setActiveItems] = createSignal<Array<TFn>>(
+    asyncQueuer.getActiveItems(),
+  )
+  const [pendingItems, setPendingItems] = createSignal<Array<TFn>>(
+    asyncQueuer.getPendingItems(),
   )
+  const [peek, setPeek] = createSignal<TFn | undefined>(asyncQueuer.getPeek())
   const [size, setSize] = createSignal(asyncQueuer.getSize())
 
   asyncQueuer.setOptions({
     onItemsChange: (queuer) => {
-      setExecutionCount(queuer.getExecutionCount())
+      setActiveItems(queuer.getActiveItems())
+      setAllItems(queuer.getAllItems())
+      setErrorCount(queuer.getErrorCount())
       setIsEmpty(queuer.getIsEmpty())
       setIsFull(queuer.getIsFull())
       setIsIdle(queuer.getIsIdle())
-      setAllItems(queuer.getAllItems())
-      setActiveItems(queuer.getActiveItems())
-      setPendingItems(queuer.getPendingItems())
       setPeek(() => queuer.getPeek())
+      setPendingItems(queuer.getPendingItems())
+      setRejectionCount(queuer.getRejectionCount())
+      setSettledCount(queuer.getSettledCount())
       setSize(queuer.getSize())
+      setSuccessCount(queuer.getSuccessCount())
       initialOptions.onItemsChange?.(queuer)
     },
     onIsRunningChange: (queuer) => {
@@ -165,15 +184,17 @@ export function createAsyncQueuer<TValue>(
   return {
     ...bindInstanceMethods(asyncQueuer),
     activeItems,
-    executionCount,
+    allItems,
+    errorCount,
     isEmpty,
     isFull,
     isIdle,
     isRunning,
-    allItems,
     peek,
     pendingItems,
     rejectionCount,
+    settledCount,
     size,
-  } as SolidAsyncQueuer<TValue>
+    successCount,
+  } as SolidAsyncQueuer<TFn>
 }

package/src/async-rate-limiter/createAsyncRateLimiter.ts

@@ -29,13 +29,9 @@ export interface SolidAsyncRateLimiter<TFn extends AnyAsyncFunction>
  * This hook is designed to be flexible and state-management agnostic - it simply returns a rate limiter instance that
  * you can integrate with any state management solution (createSignal, etc).
  *
- * Rate limiting allows an async function to execute up to a specified limit within a time window,
- * then blocks subsequent calls until the window passes. This is useful for respecting API rate limits,
- * managing resource constraints, or controlling bursts of async operations.
- *
- * Unlike the non-async RateLimiter, this async version supports returning values from the rate-limited 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 rate-limited function.
+ * Rate limiting is a simple approach that allows a function to execute up to a limit within a time window,
+ * then blocks all subsequent calls until the window passes. This can lead to "bursty" behavior where
+ * all executions happen immediately, followed by a complete block.
  *
  * The rate limiter supports two types of windows:
  * - 'fixed': A strict window that resets after the window period. All executions within the window count
@@ -43,6 +39,25 @@ export interface SolidAsyncRateLimiter<TFn extends AnyAsyncFunction>
  * - 'sliding': A rolling window that allows executions as old ones expire. This provides a more
  *   consistent rate of execution over time.
  *
+ * Unlike the non-async RateLimiter, this async version supports returning values from the rate-limited 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 rate-limited function.
+ *
+ * For smoother execution patterns, consider using:
+ * - Throttling: Ensures consistent spacing between executions (e.g. max once per 200ms)
+ * - Debouncing: Waits for a pause in calls before executing (e.g. after 500ms of no calls)
+ *
+ * Rate limiting is best used for hard API limits or resource constraints. For UI updates or
+ * smoothing out frequent events, throttling or debouncing usually provide better user experience.
+ *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and rate limiter instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncRateLimiter instance
+ * - Rate limit rejections (when limit is exceeded) are handled separately from execution errors via the `onReject` handler
+ *
  * @example
  * ```tsx
  * // Basic API call rate limiting with return value

package/src/async-throttler/createAsyncThrottler.ts

@@ -37,6 +37,17 @@ export interface SolidAsyncThrottler<TFn extends AnyAsyncFunction>
  * regardless of how many times it is called. This is useful for rate-limiting expensive API calls,
  * database operations, or other async tasks.
  *
+ * 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.
+ *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and throttler instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncThrottler instance
+ *
  * @example
  * ```tsx
  * // Basic API call throttling
@@ -58,12 +69,14 @@ export interface SolidAsyncThrottler<TFn extends AnyAsyncFunction>
  *   {
  *     wait: 2000,
  *     leading: true,   // Execute immediately on first call
- *     trailing: false  // Skip trailing edge updates
+ *     trailing: false, // Skip trailing edge updates
+ *     onError: (error) => {
+ *       console.error('API call failed:', error);
+ *     }
  *   }
  * );
  * ```
  */
-
 export function createAsyncThrottler<TFn extends AnyAsyncFunction>(
   fn: TFn,
   initialOptions: AsyncThrottlerOptions<TFn>,

package/src/rate-limiter/createRateLimiter.ts

@@ -46,17 +46,11 @@ export interface SolidRateLimiter<TFn extends AnyFunction>
  * const rateLimiter = createRateLimiter(apiCall, {
  *   limit: 5,
  *   window: 60000,
- *   windowType: 'sliding'
- * });
- *
- * // Monitor rate limit status
- * const handleClick = () => {
- *   if (rateLimiter.remainingInWindow() > 0) {
- *     rateLimiter.maybeExecute(data);
- *   } else {
- *     showRateLimitWarning();
+ *   windowType: 'sliding',
+ *   onReject: (rateLimiter) => {
+ *     console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
  *   }
- * };
+ * });
  *
  * // Access rate limiter state via signals
  * console.log('Executions:', rateLimiter.executionCount());