import { SolidPacerOptions } from "../types/index.js"; import { Accessor, JSX } from "solid-js"; import { Store } from "@tanstack/solid-store"; import { Batcher, BatcherOptions, BatcherState } from "@tanstack/pacer/batcher"; //#region src/batcher/createBatcher.d.ts export interface SolidBatcherOptions extends BatcherOptions { /** * Optional callback invoked when the owning component unmounts. Receives the batcher instance. * When provided, replaces the default cleanup (cancel); use it to call flush(), reset(), cancel(), add logging, etc. */ onUnmount?: (batcher: SolidBatcher) => void; } export interface SolidBatcher extends Omit, 'store'> { options: Batcher['options'] & SolidBatcherOptions; setOptions: (options: Partial>) => void; /** * A Solid component that allows you to subscribe to the batcher state. * * This is useful for tracking specific parts of the batcher state * deep in your component tree without needing to pass a selector to the hook. * * @example * ({ size: state.size, isPending: state.isPending })}> * {(state) => ( *
Batch: {state().size} items, {state().isPending ? 'Pending' : 'Idle'}
* )} *
*/ Subscribe: (props: { selector: (state: BatcherState) => TSelected; children: ((state: Accessor) => JSX.Element) | JSX.Element; }) => JSX.Element; /** * Reactive state that will be updated when the batcher state changes * * Use this instead of `batcher.store.state` */ readonly state: Accessor>; /** * @deprecated Use `batcher.state` instead of `batcher.store.state` if you want to read reactive state. * The state on the store object is not reactive, as it has not been wrapped in a `useSelector` hook internally. * Although, you can make the state reactive by using the `useSelector` in your own usage. */ readonly store: Store>>; } /** * 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 * * ## State Management and Selector * * The hook uses TanStack Store for reactive state management. You can subscribe to state changes * in two ways: * * **1. Using `batcher.Subscribe` component (Recommended for component tree subscriptions)** * * Use the `Subscribe` component to subscribe to state changes deep in your component tree without * needing to pass a selector to the hook. This is ideal when you want to subscribe to state * in child components. * * **2. Using the `selector` parameter (For hook-level subscriptions)** * * The `selector` parameter allows you to specify which state changes will trigger reactive updates * at the hook level, optimizing performance by preventing unnecessary updates when irrelevant * state changes occur. * * **By default, there will be no reactive state subscriptions** and you must opt-in to state * tracking by providing a selector function or using the `Subscribe` component. This prevents unnecessary * updates and gives you full control over when your component tracks state changes. * * Available state properties: * - `executionCount`: Number of batch executions that have been completed * - `items`: Array of items currently queued for batching * - `totalItemsProcessed`: Total number of individual items that have been processed across all batches * * ## Unmount behavior * * By default, the primitive cancels any pending batch when the owning component unmounts. * Use the `onUnmount` option to customize this. For example, to flush pending work instead: * * ```tsx * const batcher = createBatcher(fn, { * maxSize: 10, * wait: 2000, * onUnmount: (b) => b.flush() * }); * ``` * * Example usage: * ```tsx * // Default behavior - no reactive state subscriptions * 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 * } * ); * * // Opt-in to track items or isPending changes (optimized for UI updates) * const batcher = createBatcher( * (items) => console.log('Processing batch:', items), * { maxSize: 5, wait: 2000 }, * (state) => ({ items: state.items, isPending: state.isPending }) * ); * * // Opt-in to track execution metrics changes (optimized for tracking progress) * const batcher = createBatcher( * (items) => console.log('Processing batch:', items), * { maxSize: 5, wait: 2000 }, * (state) => ({ * executionCount: state.executionCount, * totalItemsProcessed: state.totalItemsProcessed * }) * ); * * // Add items to batch * batcher.addItem('task1'); * batcher.addItem('task2'); * * // Control the batcher * batcher.cancel(); // Cancel the pending timer; queued items are retained * batcher.flush(); // Process queued items immediately * * // Access the selected state (will be empty object {} unless selector provided) * const { items, isPending } = batcher.state(); * ``` */ export declare function createBatcher(fn: (items: Array) => void, options?: SolidPacerOptions>, selector?: (state: BatcherState) => TSelected): SolidBatcher; //#endregion