@tanstack/solid-pacer 0.6.0 → 0.8.0

package/src/async-queuer/createAsyncQueuer.ts

@@ -2,36 +2,33 @@ 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 {
-  AsyncQueuerFn,
-  AsyncQueuerOptions,
-} from '@tanstack/pacer/async-queuer'
+import type { AsyncQueuerOptions } from '@tanstack/pacer/async-queuer'
 
-export interface SolidAsyncQueuer<TFn extends AsyncQueuerFn>
+export interface SolidAsyncQueuer<TValue>
   extends Omit<
-    AsyncQueuer<TFn>,
-    | 'getActiveItems'
-    | 'getAllItems'
+    AsyncQueuer<TValue>,
     | 'getErrorCount'
     | 'getIsEmpty'
     | 'getIsFull'
     | 'getIsIdle'
     | 'getIsRunning'
-    | 'getPeek'
-    | 'getPendingItems'
     | 'getRejectionCount'
     | 'getSettledCount'
     | 'getSize'
     | 'getSuccessCount'
+    | 'peekActiveItems'
+    | 'peekAllItems'
+    | 'peekNextItem'
+    | 'peekPendingItems'
   > {
   /**
-   * Signal version of `getActiveItems`
+   * Signal version of `peekActiveItems`
    */
-  activeItems: Accessor<Array<TFn>>
+  activeItems: Accessor<Array<TValue>>
   /**
-   * Signal version of `getAllItems`
+   * Signal version of `peekAllItems`
    */
-  allItems: Accessor<Array<TFn>>
+  allItems: Accessor<Array<TValue>>
   /**
    * Signal version of `getErrorCount`
    */
@@ -53,13 +50,13 @@ export interface SolidAsyncQueuer<TFn extends AsyncQueuerFn>
    */
   isRunning: Accessor<boolean>
   /**
-   * Signal version of `getPeek`
+   * Signal version of `peekNextItem`
    */
-  peek: Accessor<TFn | undefined>
+  nextItem: Accessor<TValue | undefined>
   /**
-   * Signal version of `getPendingItems`
+   * Signal version of `peekPendingItems`
    */
-  pendingItems: Accessor<Array<TFn>>
+  pendingItems: Accessor<Array<TValue>>
   /**
    * Signal version of `getRejectionCount`
    */
@@ -79,31 +76,35 @@ export interface SolidAsyncQueuer<TFn extends AsyncQueuerFn>
 }
 
 /**
- * A lower-level Solid 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.
  *
  * Features:
- * - Priority queue support via getPriority option
+ * - Priority queueing via `getPriority` or item `priority` property
  * - 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
+ * - Pause/resume processing
  * - Task cancellation
- * - Item expiration to clear stale items from the queue
+ * - 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
  *
  * 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 next pending task is processed if the concurrency limit allows.
  *
  * 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
+ * - 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,
@@ -121,12 +122,16 @@ export interface SolidAsyncQueuer<TFn extends AsyncQueuerFn>
  *
  * // Start processing
  * asyncQueuer.start();
+ *
+ * // Use Solid signals in your UI
+ * const pending = asyncQueuer.pendingItems();
  * ```
  */
-export function createAsyncQueuer<TFn extends AsyncQueuerFn>(
-  initialOptions: AsyncQueuerOptions<TFn> = {},
-): SolidAsyncQueuer<TFn> {
-  const asyncQueuer = new AsyncQueuer<TFn>(initialOptions)
+export function createAsyncQueuer<TValue>(
+  fn: (value: TValue) => Promise<any>,
+  initialOptions: AsyncQueuerOptions<TValue> = {},
+): SolidAsyncQueuer<TValue> {
+  const asyncQueuer = new AsyncQueuer<TValue>(fn, initialOptions)
 
   const [successCount, setSuccessCount] = createSignal(
     asyncQueuer.getSuccessCount(),
@@ -142,28 +147,30 @@ export function createAsyncQueuer<TFn extends AsyncQueuerFn>(
   const [isFull, setIsFull] = createSignal(asyncQueuer.getIsFull())
   const [isIdle, setIsIdle] = createSignal(asyncQueuer.getIsIdle())
   const [isRunning, setIsRunning] = createSignal(asyncQueuer.getIsRunning())
-  const [allItems, setAllItems] = createSignal<Array<TFn>>(
-    asyncQueuer.getAllItems(),
+  const [allItems, setAllItems] = createSignal<Array<TValue>>(
+    asyncQueuer.peekAllItems(),
+  )
+  const [activeItems, setActiveItems] = createSignal<Array<TValue>>(
+    asyncQueuer.peekActiveItems(),
   )
-  const [activeItems, setActiveItems] = createSignal<Array<TFn>>(
-    asyncQueuer.getActiveItems(),
+  const [pendingItems, setPendingItems] = createSignal<Array<TValue>>(
+    asyncQueuer.peekPendingItems(),
   )
-  const [pendingItems, setPendingItems] = createSignal<Array<TFn>>(
-    asyncQueuer.getPendingItems(),
+  const [nextItem, setNextItem] = createSignal<TValue | undefined>(
+    asyncQueuer.peekNextItem(),
   )
-  const [peek, setPeek] = createSignal<TFn | undefined>(asyncQueuer.getPeek())
   const [size, setSize] = createSignal(asyncQueuer.getSize())
 
   asyncQueuer.setOptions({
     onItemsChange: (queuer) => {
-      setActiveItems(queuer.getActiveItems())
-      setAllItems(queuer.getAllItems())
+      setActiveItems(queuer.peekActiveItems())
+      setAllItems(queuer.peekAllItems())
       setErrorCount(queuer.getErrorCount())
       setIsEmpty(queuer.getIsEmpty())
       setIsFull(queuer.getIsFull())
       setIsIdle(queuer.getIsIdle())
-      setPeek(() => queuer.getPeek())
-      setPendingItems(queuer.getPendingItems())
+      setNextItem(() => queuer.peekNextItem())
+      setPendingItems(queuer.peekPendingItems())
       setRejectionCount(queuer.getRejectionCount())
       setSettledCount(queuer.getSettledCount())
       setSize(queuer.getSize())
@@ -190,11 +197,11 @@ export function createAsyncQueuer<TFn extends AsyncQueuerFn>(
     isFull,
     isIdle,
     isRunning,
-    peek,
+    nextItem,
     pendingItems,
     rejectionCount,
     settledCount,
     size,
     successCount,
-  } as SolidAsyncQueuer<TFn>
+  } as SolidAsyncQueuer<TValue>
 }

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>,
+    | 'peekAllItems'
+    | 'getBatchExecutionCount'
+    | 'getIsEmpty'
+    | 'getIsRunning'
+    | 'getItemExecutionCount'
+    | 'getSize'
+  > {
+  /**
+   * Signal version of `peekAllItems`
+   */
+  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.peekAllItems(),
+  )
+  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.peekAllItems())
+        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

@@ -7,17 +7,17 @@ import type { QueuerOptions } from '@tanstack/pacer/queuer'
 export interface SolidQueuer<TValue>
   extends Omit<
     Queuer<TValue>,
-    | 'getAllItems'
     | 'getExecutionCount'
     | 'getIsEmpty'
     | 'getIsFull'
     | 'getIsIdle'
     | 'getIsRunning'
-    | 'getPeek'
     | 'getSize'
+    | 'peekAllItems'
+    | 'peekNextItem'
   > {
   /**
-   * Signal version of `getAllItems`
+   * Signal version of `peekAllItems`
    */
   allItems: Accessor<Array<TValue>>
   /**
@@ -41,9 +41,9 @@ export interface SolidQueuer<TValue>
    */
   isRunning: Accessor<boolean>
   /**
-   * Signal version of `getPeek`
+   * Signal version of `peekNextItem`
    */
-  peek: Accessor<TValue | undefined>
+  nextItem: Accessor<TValue | undefined>
   /**
    * Signal version of `getRejectionCount`
    */
@@ -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.peekAllItems()),
+ *     getPriority: (item) => item.priority // Process higher priority items first
+ *   }
+ * );
  *
  * // Add items to process - they'll be handled automatically
  * queue.addItem('task1');
@@ -96,16 +102,17 @@ export interface SolidQueuer<TValue>
  * console.log('Size:', queue.size());
  * console.log('Is empty:', queue.isEmpty());
  * console.log('Is running:', queue.isRunning());
- * console.log('Next item:', queue.peek());
+ * console.log('Next item:', queue.nextItem());
  * ```
  */
 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(),
+    queuer.peekAllItems(),
   )
   const [executionCount, setExecutionCount] = createSignal(
     queuer.getExecutionCount(),
@@ -117,19 +124,21 @@ export function createQueuer<TValue>(
   const [isFull, setIsFull] = createSignal(queuer.getIsFull())
   const [isIdle, setIsIdle] = createSignal(queuer.getIsIdle())
   const [isRunning, setIsRunning] = createSignal(queuer.getIsRunning())
-  const [peek, setPeek] = createSignal<TValue | undefined>(queuer.getPeek())
+  const [nextItem, setNextItem] = createSignal<TValue | undefined>(
+    queuer.peekNextItem(),
+  )
   const [size, setSize] = createSignal(queuer.getSize())
 
   function setOptions(newOptions: Partial<QueuerOptions<TValue>>) {
     queuer.setOptions({
       ...newOptions,
       onItemsChange: (queuer) => {
-        setAllItems(queuer.getAllItems())
+        setAllItems(queuer.peekAllItems())
         setExecutionCount(queuer.getExecutionCount())
         setIsEmpty(queuer.getIsEmpty())
         setIsFull(queuer.getIsFull())
         setIsIdle(queuer.getIsIdle())
-        setPeek(() => queuer.getPeek())
+        setNextItem(() => queuer.peekNextItem())
         setSize(queuer.getSize())
 
         const onItemsChange =
@@ -163,7 +172,7 @@ export function createQueuer<TValue>(
     isFull,
     isIdle,
     isRunning,
-    peek,
+    nextItem,
     rejectionCount,
     size,
     setOptions,