@tanstack/solid-pacer 0.6.0 → 0.7.0

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