@tanstack/solid-pacer 0.5.0 → 0.7.0

package/src/async-queuer/createAsyncQueuer.ts

@@ -9,27 +9,30 @@ export interface SolidAsyncQueuer<TValue>
     AsyncQueuer<TValue>,
     | '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<TValue>>
   /**
    * Signal version of `getAllItems`
    */
-  allItems: Accessor<Array<() => Promise<TValue>>>
+  allItems: Accessor<Array<TValue>>
   /**
-   * Signal version of `getExecutionCount`
+   * Signal version of `getErrorCount`
    */
-  executionCount: Accessor<number>
+  errorCount: Accessor<number>
   /**
    * Signal version of `getIsEmpty`
    */
@@ -49,48 +52,69 @@ export interface SolidAsyncQueuer<TValue>
   /**
    * Signal version of `getPeek`
    */
-  peek: Accessor<(() => Promise<TValue>) | undefined>
+  peek: Accessor<TValue | undefined>
   /**
    * Signal version of `getPendingItems`
    */
-  pendingItems: Accessor<Array<() => Promise<TValue>>>
+  pendingItems: Accessor<Array<TValue>>
   /**
    * 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.
+ * Creates a Solid-compatible AsyncQueuer instance for managing an asynchronous queue of items, exposing Solid signals for all stateful properties.
  *
- * 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 queueing via `getPriority` or item `priority` property
+ * - Configurable concurrency limit
+ * - FIFO (First In First Out) or LIFO (Last In First Out) queue behavior
+ * - Pause/resume processing
+ * - Task cancellation
+ * - Item expiration
+ * - Lifecycle callbacks for success, error, settled, items change, etc.
+ * - All stateful properties (active items, pending items, counts, etc.) are exposed as Solid signals for reactivity
  *
- * 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 the concurrency limit allows.
  *
- * 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
+ * Example usage:
  * ```tsx
  * // Basic async queuer for API requests
- * const asyncQueuer = createAsyncQueuer({
+ * const asyncQueuer = createAsyncQueuer(async (item) => {
+ *   // process item
+ *   return await fetchData(item);
+ * }, {
  *   initialItems: [],
  *   concurrency: 2,
  *   maxSize: 100,
  *   started: false,
+ *   onSuccess: (result) => {
+ *     console.log('Item processed:', result);
+ *   },
+ *   onError: (error) => {
+ *     console.error('Processing failed:', error);
+ *   }
  * });
  *
  * // Add items to queue
@@ -99,23 +123,22 @@ 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);
- * });
+ * // Use Solid signals in your UI
+ * const pending = asyncQueuer.pendingItems();
  * ```
  */
 export function createAsyncQueuer<TValue>(
+  fn: (value: TValue) => Promise<any>,
   initialOptions: AsyncQueuerOptions<TValue> = {},
 ): SolidAsyncQueuer<TValue> {
-  const asyncQueuer = new AsyncQueuer<TValue>(initialOptions)
+  const asyncQueuer = new AsyncQueuer<TValue>(fn, 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 +147,34 @@ 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<TValue>>(
     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>(
+  const [activeItems, setActiveItems] = createSignal<Array<TValue>>(
+    asyncQueuer.getActiveItems(),
+  )
+  const [pendingItems, setPendingItems] = createSignal<Array<TValue>>(
+    asyncQueuer.getPendingItems(),
+  )
+  const [peek, setPeek] = createSignal<TValue | 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 +191,17 @@ export function createAsyncQueuer<TValue>(
   return {
     ...bindInstanceMethods(asyncQueuer),
     activeItems,
-    executionCount,
+    allItems,
+    errorCount,
     isEmpty,
     isFull,
     isIdle,
     isRunning,
-    allItems,
     peek,
     pendingItems,
     rejectionCount,
+    settledCount,
     size,
+    successCount,
   } as SolidAsyncQueuer<TValue>
 }

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/batcher/createBatcher.ts

@@ -0,0 +1,152 @@
+import { Batcher } from '@tanstack/pacer/batcher'
+import { createSignal } from 'solid-js'
+import { bindInstanceMethods } from '@tanstack/pacer/utils'
+import type { Accessor } from 'solid-js'
+import type { BatcherOptions } from '@tanstack/pacer/batcher'
+
+export interface SolidBatcher<TValue>
+  extends Omit<
+    Batcher<TValue>,
+    | 'getAllItems'
+    | 'getBatchExecutionCount'
+    | 'getIsEmpty'
+    | 'getIsRunning'
+    | 'getItemExecutionCount'
+    | 'getSize'
+  > {
+  /**
+   * Signal version of `getAllItems`
+   */
+  allItems: Accessor<Array<TValue>>
+  /**
+   * Signal version of `getBatchExecutionCount`
+   */
+  batchExecutionCount: Accessor<number>
+  /**
+   * Signal version of `getIsEmpty`
+   */
+  isEmpty: Accessor<boolean>
+  /**
+   * Signal version of `getIsRunning`
+   */
+  isRunning: Accessor<boolean>
+  /**
+   * Signal version of `getItemExecutionCount`
+   */
+  itemExecutionCount: Accessor<number>
+  /**
+   * Signal version of `getSize`
+   */
+  size: Accessor<number>
+}
+
+/**
+ * Creates a Solid-compatible Batcher instance for managing batches of items, exposing Solid signals for all stateful properties.
+ *
+ * Features:
+ * - Batch processing of items using the provided `fn` function
+ * - Configurable batch size and wait time
+ * - Custom batch processing logic via getShouldExecute
+ * - Event callbacks for monitoring batch operations
+ * - All stateful properties (items, counts, etc.) are exposed as Solid signals for reactivity
+ *
+ * The batcher collects items and processes them in batches based on:
+ * - Maximum batch size
+ * - Time-based batching (process after X milliseconds)
+ * - Custom batch processing logic via getShouldExecute
+ *
+ * Example usage:
+ * ```tsx
+ * const batcher = createBatcher(
+ *   (items) => {
+ *     // Process batch of items
+ *     console.log('Processing batch:', items);
+ *   },
+ *   {
+ *     maxSize: 5,
+ *     wait: 2000,
+ *     onExecute: (batcher) => console.log('Batch executed'),
+ *     getShouldExecute: (items) => items.length >= 3
+ *   }
+ * );
+ *
+ * // Add items to batch
+ * batcher.addItem('task1');
+ * batcher.addItem('task2');
+ *
+ * // Control the batcher
+ * batcher.stop();  // Pause processing
+ * batcher.start(); // Resume processing
+ *
+ * // Access batcher state via signals
+ * console.log('Items:', batcher.allItems());
+ * console.log('Size:', batcher.size());
+ * console.log('Is empty:', batcher.isEmpty());
+ * console.log('Is running:', batcher.isRunning());
+ * console.log('Batch count:', batcher.batchExecutionCount());
+ * console.log('Item count:', batcher.itemExecutionCount());
+ * ```
+ */
+export function createBatcher<TValue>(
+  fn: (items: Array<TValue>) => void,
+  initialOptions: BatcherOptions<TValue> = {},
+): SolidBatcher<TValue> {
+  const batcher = bindInstanceMethods(new Batcher<TValue>(fn, initialOptions))
+
+  const [allItems, setAllItems] = createSignal<Array<TValue>>(
+    batcher.getAllItems(),
+  )
+  const [batchExecutionCount, setBatchExecutionCount] = createSignal(
+    batcher.getBatchExecutionCount(),
+  )
+  const [itemExecutionCount, setItemExecutionCount] = createSignal(
+    batcher.getItemExecutionCount(),
+  )
+  const [isEmpty, setIsEmpty] = createSignal(batcher.getIsEmpty())
+  const [isRunning, setIsRunning] = createSignal(batcher.getIsRunning())
+  const [size, setSize] = createSignal(batcher.getSize())
+
+  function setOptions(newOptions: Partial<BatcherOptions<TValue>>) {
+    batcher.setOptions({
+      ...newOptions,
+      onItemsChange: (batcher) => {
+        setAllItems(batcher.getAllItems())
+        setBatchExecutionCount(batcher.getBatchExecutionCount())
+        setItemExecutionCount(batcher.getItemExecutionCount())
+        setIsEmpty(batcher.getIsEmpty())
+        setSize(batcher.getSize())
+
+        const onItemsChange =
+          newOptions.onItemsChange ?? initialOptions.onItemsChange
+        onItemsChange?.(batcher)
+      },
+      onExecute: (batcher) => {
+        setBatchExecutionCount(batcher.getBatchExecutionCount())
+        setItemExecutionCount(batcher.getItemExecutionCount())
+
+        const onExecute = newOptions.onExecute ?? initialOptions.onExecute
+        onExecute?.(batcher)
+      },
+      onIsRunningChange: (batcher) => {
+        setIsRunning(batcher.getIsRunning())
+
+        const onIsRunningChange =
+          newOptions.onIsRunningChange ?? initialOptions.onIsRunningChange
+        onIsRunningChange?.(batcher)
+      },
+    })
+  }
+
+  setOptions(initialOptions)
+
+  return {
+    ...batcher,
+    allItems,
+    batchExecutionCount,
+    isEmpty,
+    isRunning,
+    itemExecutionCount,
+    size,
+    setOptions,
+  } as SolidBatcher<TValue>
+}

package/src/batcher/index.ts

@@ -0,0 +1,3 @@
+export * from '@tanstack/pacer/batcher'
+
+export * from './createBatcher'

package/src/index.ts

@@ -17,6 +17,9 @@ export * from './async-rate-limiter/createAsyncRateLimiter'
 // async-throttler
 export * from './async-throttler/createAsyncThrottler'
 
+// batcher
+export * from './batcher/createBatcher'
+
 // debouncer
 export * from './debouncer/createDebouncedSignal'
 export * from './debouncer/createDebouncedValue'

package/src/queuer/createQueuer.ts

@@ -55,33 +55,39 @@ export interface SolidQueuer<TValue>
 }
 
 /**
- * A Solid hook that creates and manages a Queuer instance.
+ * Creates a Solid-compatible Queuer instance for managing a synchronous queue of items, exposing Solid signals for all stateful properties.
  *
- * This is a lower-level hook that provides direct access to the Queuer's functionality without
- * any built-in state management. This allows you to integrate it with any state management solution
- * you prefer (createSignal, Redux, Zustand, etc.) by utilizing the onItemsChange callback.
+ * Features:
+ * - Synchronous processing of items using the provided `fn` function
+ * - FIFO (First In First Out) or LIFO (Last In First Out) queue behavior
+ * - Priority queueing via `getPriority` or item `priority` property
+ * - Item expiration and removal of stale items
+ * - Configurable wait time between processing items
+ * - Pause/resume processing
+ * - Callbacks for queue state changes, execution, rejection, and expiration
+ * - All stateful properties (items, counts, etc.) are exposed as Solid signals for reactivity
  *
- * For a hook with built-in state management, see createQueuerSignal.
+ * The queue processes items synchronously in order, with optional delays between each item. When started, it will process one item per tick, with an optional wait time between ticks. You can pause and resume processing with `stop()` and `start()`.
  *
- * The Queuer extends the base Queue to add processing capabilities. Items are processed
- * 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.
- * When started, it will process one item per tick, with an optional wait time between ticks.
+ * By default, the queue uses FIFO behavior, but you can configure LIFO or double-ended queueing by specifying the position when adding or removing items.
  *
- * By default uses FIFO (First In First Out) behavior, but can be configured for LIFO
- * (Last In First Out) by specifying 'front' position when adding items.
- *
- * @example
+ * Example usage:
  * ```tsx
- * // Example with custom state management and scheduling
+ * // Example with Solid signals and scheduling
  * const [items, setItems] = createSignal([]);
  *
- * const queue = createQueuer({
- *   started: true, // Start processing immediately
- *   wait: 1000,    // Process one item every second
- *   onItemsChange: (queue) => setItems(queue.getAllItems()),
- *   getPriority: (item) => item.priority // Process higher priority items first
- * });
+ * const queue = createQueuer(
+ *   (item) => {
+ *     // process item synchronously
+ *     console.log('Processing', item);
+ *   },
+ *   {
+ *     started: true, // Start processing immediately
+ *     wait: 1000,    // Process one item every second
+ *     onItemsChange: (queue) => setItems(queue.getAllItems()),
+ *     getPriority: (item) => item.priority // Process higher priority items first
+ *   }
+ * );
  *
  * // Add items to process - they'll be handled automatically
  * queue.addItem('task1');
@@ -100,9 +106,10 @@ export interface SolidQueuer<TValue>
  * ```
  */
 export function createQueuer<TValue>(
+  fn: (item: TValue) => void,
   initialOptions: QueuerOptions<TValue> = {},
 ): SolidQueuer<TValue> {
-  const queuer = bindInstanceMethods(new Queuer<TValue>(initialOptions))
+  const queuer = bindInstanceMethods(new Queuer<TValue>(fn, initialOptions))
 
   const [allItems, setAllItems] = createSignal<Array<TValue>>(
     queuer.getAllItems(),

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());