feat: add solid pacer provider and createQueuedSignal hook

.changeset/add-solid-queued-hooks.md

@@ -0,0 +1,8 @@
+---
+'@tanstack/solid-pacer': minor
+---
+
+Add new Solid hooks for queue management and provider
+
+- Add `createQueuedSignal` - Solid equivalent of `useQueuedState` with signal-based queue item tracking
+- Add `PacerProvider` - Context provider for setting default pacer options in Solid apps

docs/config.json

@@ -540,6 +540,10 @@
             {
               "label": "createAsyncQueuer",
               "to": "framework/solid/reference/functions/createAsyncQueuer"
+            },
+            {
+              "label": "createQueuedSignal",
+              "to": "framework/solid/reference/functions/createQueuedSignal"
             }
           ]
         }
@@ -939,6 +943,10 @@
             {
               "label": "createAsyncQueuer",
               "to": "framework/solid/examples/createAsyncQueuer"
+            },
+            {
+              "label": "createQueuedSignal",
+              "to": "framework/solid/examples/createQueuedSignal"
             }
           ]
         }

docs/framework/solid/reference/functions/PacerProvider.md

@@ -0,0 +1,22 @@
+---
+id: PacerProvider
+title: PacerProvider
+---
+
+# Function: PacerProvider()
+
+```ts
+function PacerProvider(props): Element;
+```
+
+Defined in: [solid-pacer/src/provider/PacerProvider.tsx:44](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/provider/PacerProvider.tsx#L44)
+
+## Parameters
+
+### props
+
+[`PacerProviderProps`](../../interfaces/PacerProviderProps.md)
+
+## Returns
+
+`Element`

docs/framework/solid/reference/functions/createAsyncBatcher.md

@@ -8,11 +8,11 @@ title: createAsyncBatcher
 ```ts
 function createAsyncBatcher<TValue, TSelected>(
    fn, 
-   initialOptions, 
+   options, 
 selector): SolidAsyncBatcher<TValue, TSelected>;
 ```
 
-Defined in: [async-batcher/createAsyncBatcher.ts:128](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/async-batcher/createAsyncBatcher.ts#L128)
+Defined in: [solid-pacer/src/async-batcher/createAsyncBatcher.ts:129](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/async-batcher/createAsyncBatcher.ts#L129)
 
 Creates a Solid-compatible AsyncBatcher instance for managing asynchronous batches of items, exposing Solid signals for all stateful properties.
 
@@ -132,7 +132,7 @@ const { items, isExecuting } = asyncBatcher.state();
 
 (`items`) => `Promise`\<`any`\>
 
-### initialOptions
+### options
 
 `AsyncBatcherOptions`\<`TValue`\> = `{}`
 

docs/framework/solid/reference/functions/createAsyncDebouncer.md

@@ -8,11 +8,11 @@ title: createAsyncDebouncer
 ```ts
 function createAsyncDebouncer<TFn, TSelected>(
    fn, 
-   initialOptions, 
+   options, 
 selector): SolidAsyncDebouncer<TFn, TSelected>;
 ```
 
-Defined in: [async-debouncer/createAsyncDebouncer.ts:118](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/async-debouncer/createAsyncDebouncer.ts#L118)
+Defined in: [solid-pacer/src/async-debouncer/createAsyncDebouncer.ts:119](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/async-debouncer/createAsyncDebouncer.ts#L119)
 
 A low-level Solid hook that creates an `AsyncDebouncer` instance to delay execution of an async function.
 
@@ -76,7 +76,7 @@ Available state properties:
 
 `TFn`
 
-### initialOptions
+### options
 
 `AsyncDebouncerOptions`\<`TFn`\>
 

docs/framework/solid/reference/functions/createAsyncQueuer.md

@@ -8,11 +8,11 @@ title: createAsyncQueuer
 ```ts
 function createAsyncQueuer<TValue, TSelected>(
    fn, 
-   initialOptions, 
+   options, 
 selector): SolidAsyncQueuer<TValue, TSelected>;
 ```
 
-Defined in: [async-queuer/createAsyncQueuer.ts:120](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/async-queuer/createAsyncQueuer.ts#L120)
+Defined in: [solid-pacer/src/async-queuer/createAsyncQueuer.ts:121](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/async-queuer/createAsyncQueuer.ts#L121)
 
 Creates a Solid-compatible AsyncQueuer instance for managing an asynchronous queue of items, exposing Solid signals for all stateful properties.
 
@@ -124,7 +124,7 @@ const { pendingItems, activeItems } = asyncQueuer.state();
 
 (`value`) => `Promise`\<`any`\>
 
-### initialOptions
+### options
 
 `AsyncQueuerOptions`\<`TValue`\> = `{}`
 

docs/framework/solid/reference/functions/createAsyncRateLimiter.md

@@ -8,11 +8,11 @@ title: createAsyncRateLimiter
 ```ts
 function createAsyncRateLimiter<TFn, TSelected>(
    fn, 
-   initialOptions, 
+   options, 
 selector): SolidAsyncRateLimiter<TFn, TSelected>;
 ```
 
-Defined in: [async-rate-limiter/createAsyncRateLimiter.ts:129](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/async-rate-limiter/createAsyncRateLimiter.ts#L129)
+Defined in: [solid-pacer/src/async-rate-limiter/createAsyncRateLimiter.ts:130](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/async-rate-limiter/createAsyncRateLimiter.ts#L130)
 
 A low-level Solid hook that creates an `AsyncRateLimiter` instance to limit how many times an async function can execute within a time window.
 
@@ -87,7 +87,7 @@ Available state properties:
 
 `TFn`
 
-### initialOptions
+### options
 
 `AsyncRateLimiterOptions`\<`TFn`\>
 

docs/framework/solid/reference/functions/createAsyncThrottler.md

@@ -8,11 +8,11 @@ title: createAsyncThrottler
 ```ts
 function createAsyncThrottler<TFn, TSelected>(
    fn, 
-   initialOptions, 
+   options, 
 selector): SolidAsyncThrottler<TFn, TSelected>;
 ```
 
-Defined in: [async-throttler/createAsyncThrottler.ts:117](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/async-throttler/createAsyncThrottler.ts#L117)
+Defined in: [solid-pacer/src/async-throttler/createAsyncThrottler.ts:118](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/async-throttler/createAsyncThrottler.ts#L118)
 
 A low-level Solid hook that creates an `AsyncThrottler` instance to limit how often an async function can execute.
 
@@ -76,7 +76,7 @@ Available state properties:
 
 `TFn`
 
-### initialOptions
+### options
 
 `AsyncThrottlerOptions`\<`TFn`\>
 

docs/framework/solid/reference/functions/createBatcher.md

@@ -8,11 +8,11 @@ title: createBatcher
 ```ts
 function createBatcher<TValue, TSelected>(
    fn, 
-   initialOptions, 
+   options, 
 selector): SolidBatcher<TValue, TSelected>;
 ```
 
-Defined in: [batcher/createBatcher.ts:100](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/batcher/createBatcher.ts#L100)
+Defined in: [solid-pacer/src/batcher/createBatcher.ts:101](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/batcher/createBatcher.ts#L101)
 
 Creates a Solid-compatible Batcher instance for managing batches of items, exposing Solid signals for all stateful properties.
 
@@ -107,7 +107,7 @@ const { items, isRunning } = batcher.state();
 
 (`items`) => `void`
 
-### initialOptions
+### options
 
 `BatcherOptions`\<`TValue`\> = `{}`
 

docs/framework/solid/reference/functions/createDebouncedSignal.md

@@ -12,7 +12,7 @@ function createDebouncedSignal<TValue, TSelected>(
    selector?): [Accessor<TValue>, Setter<TValue>, SolidDebouncer<Setter<TValue>, TSelected>];
 ```
 
-Defined in: [debouncer/createDebouncedSignal.ts:81](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/debouncer/createDebouncedSignal.ts#L81)
+Defined in: [solid-pacer/src/debouncer/createDebouncedSignal.ts:81](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/debouncer/createDebouncedSignal.ts#L81)
 
 A Solid hook that creates a debounced state value, combining Solid's createSignal with debouncing functionality.
 This hook provides both the current debounced value and methods to update it.

docs/framework/solid/reference/functions/createDebouncedValue.md

@@ -12,7 +12,7 @@ function createDebouncedValue<TValue, TSelected>(
    selector?): [Accessor<TValue>, SolidDebouncer<Setter<TValue>, TSelected>];
 ```
 
-Defined in: [debouncer/createDebouncedValue.ts:72](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/debouncer/createDebouncedValue.ts#L72)
+Defined in: [solid-pacer/src/debouncer/createDebouncedValue.ts:72](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/debouncer/createDebouncedValue.ts#L72)
 
 A Solid hook that creates a debounced value that updates only after a specified delay.
 Unlike createDebouncedSignal, this hook automatically tracks changes to the input value

docs/framework/solid/reference/functions/createDebouncer.md

@@ -8,11 +8,11 @@ title: createDebouncer
 ```ts
 function createDebouncer<TFn, TSelected>(
    fn, 
-   initialOptions, 
+   options, 
 selector): SolidDebouncer<TFn, TSelected>;
 ```
 
-Defined in: [debouncer/createDebouncer.ts:103](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/debouncer/createDebouncer.ts#L103)
+Defined in: [solid-pacer/src/debouncer/createDebouncer.ts:104](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/debouncer/createDebouncer.ts#L104)
 
 A Solid hook that creates and manages a Debouncer instance.
 
@@ -63,7 +63,7 @@ Available state properties:
 
 `TFn`
 
-### initialOptions
+### options
 
 `DebouncerOptions`\<`TFn`\>
 

docs/framework/solid/reference/functions/createQueuedSignal.md

@@ -0,0 +1,157 @@
+---
+id: createQueuedSignal
+title: createQueuedSignal
+---
+
+# Function: createQueuedSignal()
+
+```ts
+function createQueuedSignal<TValue, TSelected>(
+   fn, 
+   options, 
+   selector): [() => TValue[], (item, position?, runOnItemsChange?) => boolean, SolidQueuer<TValue, TSelected>];
+```
+
+Defined in: [solid-pacer/src/queuer/createQueuedSignal.ts:119](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/queuer/createQueuedSignal.ts#L119)
+
+A Solid primitive that creates a queuer with managed state, combining Solid's signals with queuing functionality.
+This primitive provides both the current queue state and queue control methods.
+
+The queue state is automatically updated whenever items are added, removed, or reordered in the queue.
+All queue operations are reflected in the state array returned by the primitive.
+
+The queue can be started and stopped to automatically process items at a specified interval,
+making it useful as a scheduler. When started, it will process one item per tick, with an
+optional wait time between ticks.
+
+The primitive returns a tuple containing:
+- The current queue state as an array
+- The queue instance with methods for queue manipulation
+
+## State Management and Selector
+
+The primitive uses Solid's reactive state management via the underlying queuer instance.
+The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,
+optimizing performance by preventing unnecessary re-renders 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. This prevents unnecessary re-renders and gives you
+full control over when your component updates. Only when you provide a selector will the
+component re-render when the selected state values change.
+
+Available queuer state properties:
+- `executionCount`: Number of items that have been processed by the queuer
+- `expirationCount`: Number of items that have been removed due to expiration
+- `isEmpty`: Whether the queuer has no items to process
+- `isFull`: Whether the queuer has reached its maximum capacity
+- `isIdle`: Whether the queuer is not currently processing any items
+- `isRunning`: Whether the queuer is active and will process items automatically
+- `items`: Array of items currently waiting to be processed
+- `itemTimestamps`: Timestamps when items were added for expiration tracking
+- `pendingTick`: Whether the queuer has a pending timeout for processing the next item
+- `rejectionCount`: Number of items that have been rejected from being added
+- `size`: Number of items currently in the queue
+- `status`: Current processing status ('idle' | 'running' | 'stopped')
+
+## Type Parameters
+
+### TValue
+
+`TValue`
+
+### TSelected
+
+`TSelected` *extends* `Pick`\<`QueuerState`\<`TValue`\>, `"items"`\> = `Pick`\<`QueuerState`\<`TValue`\>, `"items"`\>
+
+## Parameters
+
+### fn
+
+(`item`) => `void`
+
+### options
+
+`QueuerOptions`\<`TValue`\> = `{}`
+
+### selector
+
+(`state`) => `TSelected`
+
+## Returns
+
+\[() => `TValue`[], (`item`, `position?`, `runOnItemsChange?`) => `boolean`, [`SolidQueuer`](../../interfaces/SolidQueuer.md)\<`TValue`, `TSelected`\>\]
+
+## Example
+
+```tsx
+// Default behavior - no reactive state subscriptions
+const [items, addItem, queue] = createQueuedSignal(
+  (item) => console.log('Processing:', item),
+  {
+    initialItems: ['item1', 'item2'],
+    started: true,
+    wait: 1000,
+    getPriority: (item) => item.priority
+  }
+);
+
+// Opt-in to re-render when queue contents change (optimized for displaying queue items)
+const [items, addItem, queue] = createQueuedSignal(
+  (item) => console.log('Processing:', item),
+  { started: true, wait: 1000 },
+  (state) => ({
+    items: state.items,
+    size: state.size,
+    isEmpty: state.isEmpty
+  })
+);
+
+// Opt-in to re-render when processing state changes (optimized for loading indicators)
+const [items, addItem, queue] = createQueuedSignal(
+  (item) => console.log('Processing:', item),
+  { started: true, wait: 1000 },
+  (state) => ({
+    isRunning: state.isRunning,
+    isIdle: state.isIdle,
+    status: state.status,
+    pendingTick: state.pendingTick
+  })
+);
+
+// Opt-in to re-render when execution metrics change (optimized for stats display)
+const [items, addItem, queue] = createQueuedSignal(
+  (item) => console.log('Processing:', item),
+  { started: true, wait: 1000 },
+  (state) => ({
+    executionCount: state.executionCount,
+    expirationCount: state.expirationCount,
+    rejectionCount: state.rejectionCount
+  })
+);
+
+// Add items to queue
+const handleAdd = (item) => {
+  addItem(item);
+};
+
+// Start automatic processing
+const startProcessing = () => {
+  queue.start();
+};
+
+// Stop automatic processing
+const stopProcessing = () => {
+  queue.stop();
+};
+
+// Manual processing still available
+const handleProcess = () => {
+  const nextItem = queue.getNextItem();
+  if (nextItem) {
+    processItem(nextItem);
+  }
+};
+
+// Access the selected queuer state (will be empty object {} unless selector provided)
+const { size, isRunning, executionCount } = queue.state;
+```