@tanstack/solid-pacer 0.15.3 → 0.16.0

package/src/debouncer/createDebouncer.ts

@@ -1,6 +1,7 @@
 import { Debouncer } from '@tanstack/pacer/debouncer'
 import { createEffect, onCleanup } from 'solid-js'
 import { useStore } from '@tanstack/solid-store'
+import { useDefaultPacerOptions } from '../provider/PacerProvider'
 import type { Store } from '@tanstack/solid-store'
 import type { Accessor } from 'solid-js'
 import type { AnyFunction } from '@tanstack/pacer/types'
@@ -102,10 +103,15 @@ export interface SolidDebouncer<TFn extends AnyFunction, TSelected = {}>
  */
 export function createDebouncer<TFn extends AnyFunction, TSelected = {}>(
   fn: TFn,
-  initialOptions: DebouncerOptions<TFn>,
+  options: DebouncerOptions<TFn>,
   selector: (state: DebouncerState<TFn>) => TSelected = () => ({}) as TSelected,
 ): SolidDebouncer<TFn, TSelected> {
-  const asyncDebouncer = new Debouncer<TFn>(fn, initialOptions)
+  const mergedOptions = {
+    ...useDefaultPacerOptions().debouncer,
+    ...options,
+  } as DebouncerOptions<TFn>
+
+  const asyncDebouncer = new Debouncer<TFn>(fn, mergedOptions)
 
   const state = useStore(asyncDebouncer.store, selector)
 

package/src/index.ts

@@ -1,6 +1,9 @@
 // re-export everything from the core pacer package
 export * from '@tanstack/pacer'
 
+// provider
+export * from './provider/PacerProvider'
+
 /**
  * Export every hook individually - DON'T export from barrel files
  */
@@ -30,6 +33,7 @@ export * from './debouncer/createDebouncer'
 
 // queuer
 export * from './queuer/createQueuer'
+export * from './queuer/createQueuedSignal'
 
 // rate-limiter
 export * from './rate-limiter/createRateLimiter'

package/src/provider/PacerProvider.tsx

@@ -0,0 +1,63 @@
+import { createContext, useContext } from 'solid-js'
+import type { JSX } from 'solid-js'
+import type {
+  AnyAsyncFunction,
+  AnyFunction,
+  AsyncBatcherOptions,
+  AsyncDebouncerOptions,
+  AsyncQueuerOptions,
+  AsyncRateLimiterOptions,
+  AsyncThrottlerOptions,
+  BatcherOptions,
+  DebouncerOptions,
+  QueuerOptions,
+  RateLimiterOptions,
+  ThrottlerOptions,
+} from '@tanstack/pacer'
+
+export interface PacerProviderOptions {
+  asyncBatcher?: Partial<AsyncBatcherOptions<any>>
+  asyncDebouncer?: Partial<AsyncDebouncerOptions<AnyAsyncFunction>>
+  asyncQueuer?: Partial<AsyncQueuerOptions<any>>
+  asyncRateLimiter?: Partial<AsyncRateLimiterOptions<AnyAsyncFunction>>
+  asyncThrottler?: Partial<AsyncThrottlerOptions<AnyAsyncFunction>>
+  batcher?: Partial<BatcherOptions<any>>
+  debouncer?: Partial<DebouncerOptions<AnyFunction>>
+  queuer?: Partial<QueuerOptions<any>>
+  rateLimiter?: Partial<RateLimiterOptions<AnyFunction>>
+  throttler?: Partial<ThrottlerOptions<AnyFunction>>
+}
+
+interface PacerContextValue {
+  defaultOptions: PacerProviderOptions
+}
+
+const PacerContext = createContext<PacerContextValue | null>(null)
+
+export interface PacerProviderProps {
+  children: JSX.Element
+  defaultOptions?: PacerProviderOptions
+}
+
+const DEFAULT_OPTIONS: PacerProviderOptions = {}
+
+export function PacerProvider(props: PacerProviderProps) {
+  const contextValue: PacerContextValue = {
+    defaultOptions: props.defaultOptions ?? DEFAULT_OPTIONS,
+  }
+
+  return (
+    <PacerContext.Provider value={contextValue}>
+      {props.children}
+    </PacerContext.Provider>
+  )
+}
+
+export function usePacerContext() {
+  return useContext(PacerContext)
+}
+
+export function useDefaultPacerOptions() {
+  const context = useContext(PacerContext)
+  return context?.defaultOptions ?? {}
+}

package/src/queuer/createQueuedSignal.ts

@@ -0,0 +1,138 @@
+import { createQueuer } from './createQueuer'
+import type { SolidQueuer } from './createQueuer'
+import type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
+
+/**
+ * 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')
+ *
+ * @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;
+ * ```
+ */
+export function createQueuedSignal<
+  TValue,
+  TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<
+    QueuerState<TValue>,
+    'items'
+  >,
+>(
+  fn: (item: TValue) => void,
+  options: QueuerOptions<TValue> = {},
+  selector: (state: QueuerState<TValue>) => TSelected = (state) =>
+    ({ items: state.items }) as TSelected,
+): [
+  () => Array<TValue>,
+  SolidQueuer<TValue, TSelected>['addItem'],
+  SolidQueuer<TValue, TSelected>,
+] {
+  const queue = createQueuer(fn, options, selector)
+
+  return [() => queue.state().items, queue.addItem, queue]
+}

package/src/queuer/createQueuer.ts

@@ -1,5 +1,6 @@
 import { Queuer } from '@tanstack/pacer/queuer'
 import { useStore } from '@tanstack/solid-store'
+import { useDefaultPacerOptions } from '../provider/PacerProvider'
 import type { Store } from '@tanstack/solid-store'
 import type { Accessor } from 'solid-js'
 import type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
@@ -100,10 +101,15 @@ export interface SolidQueuer<TValue, TSelected = {}>
  */
 export function createQueuer<TValue, TSelected = {}>(
   fn: (item: TValue) => void,
-  initialOptions: QueuerOptions<TValue> = {},
+  options: QueuerOptions<TValue> = {},
   selector: (state: QueuerState<TValue>) => TSelected = () => ({}) as TSelected,
 ): SolidQueuer<TValue, TSelected> {
-  const queuer = new Queuer(fn, initialOptions)
+  const mergedOptions = {
+    ...useDefaultPacerOptions().queuer,
+    ...options,
+  } as QueuerOptions<TValue>
+
+  const queuer = new Queuer(fn, mergedOptions)
 
   const state = useStore(queuer.store, selector)
 

package/src/queuer/index.ts

@@ -1,3 +1,4 @@
 export * from '@tanstack/pacer/queuer'
 
 export * from './createQueuer'
+export * from './createQueuedSignal'

package/src/rate-limiter/createRateLimitedValue.ts

@@ -46,13 +46,9 @@ import type {
  * the reactive system track the selected state values.
  *
  * Available rate limiter state properties:
- * - `callsInWindow`: Number of calls made in the current window
- * - `remainingInWindow`: Number of calls remaining in the current window
- * - `windowStart`: Unix timestamp when the current window started
- * - `nextWindowStart`: Unix timestamp when the next window will start
- * - `msUntilNextWindow`: Milliseconds until the next window starts
- * - `isAtLimit`: Whether the call limit for the current window has been reached
- * - `status`: Current status ('disabled' | 'idle' | 'at-limit')
+ * - `executionCount`: Number of function executions that have been completed
+ * - `executionTimes`: Array of timestamps when executions occurred for rate limiting calculations
+ * - `rejectionCount`: Number of function executions that have been rejected due to rate limiting
  *
  * @example
  * ```tsx
@@ -63,21 +59,39 @@ import type {
  *   windowType: 'sliding'
  * });
  *
- * // Opt-in to reactive updates when limit state changes (optimized for UI feedback)
+ * // Opt-in to reactive updates when execution count changes (optimized for tracking successful updates)
  * const [rateLimitedValue, rateLimiter] = createRateLimitedValue(
  *   rawValue,
- *   { limit: 5, window: 60000 },
- *   (state) => ({ isAtLimit: state.isAtLimit, remainingInWindow: state.remainingInWindow })
+ *   { limit: 5, window: 60000, windowType: 'sliding' },
+ *   (state) => ({ executionCount: state.executionCount })
  * );
  *
- * // Use the rate-limited value
- * console.log(rateLimitedValue()); // Access the current rate-limited value
+ * // Opt-in to reactive updates when rejection count changes (optimized for tracking rate limit violations)
+ * const [rateLimitedValue, rateLimiter] = createRateLimitedValue(
+ *   rawValue,
+ *   { limit: 5, window: 60000, windowType: 'sliding' },
+ *   (state) => ({ rejectionCount: state.rejectionCount })
+ * );
  *
- * // Access rate limiter state via signals
- * console.log('Is at limit:', rateLimiter.state().isAtLimit);
+ * // Opt-in to reactive updates when execution times change (optimized for window calculations)
+ * const [rateLimitedValue, rateLimiter] = createRateLimitedValue(
+ *   rawValue,
+ *   { limit: 5, window: 60000, windowType: 'sliding' },
+ *   (state) => ({ executionTimes: state.executionTimes })
+ * );
+ *
+ * // With rejection callback and fixed window
+ * const [rateLimitedValue, rateLimiter] = createRateLimitedValue(rawValue, {
+ *   limit: 3,
+ *   window: 5000,
+ *   windowType: 'fixed',
+ *   onReject: (rateLimiter) => {
+ *     console.log(`Update rejected. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
+ *   }
+ * });
  *
- * // Control the rate limiter
- * rateLimiter.reset(); // Reset the rate limit window
+ * // Access the selected rate limiter state (will be empty object {} unless selector provided)
+ * const { executionCount, rejectionCount } = rateLimiter.state;
  * ```
  */
 export function createRateLimitedValue<TValue, TSelected = {}>(

package/src/rate-limiter/createRateLimiter.ts

@@ -1,5 +1,6 @@
 import { RateLimiter } from '@tanstack/pacer/rate-limiter'
 import { useStore } from '@tanstack/solid-store'
+import { useDefaultPacerOptions } from '../provider/PacerProvider'
 import type { Store } from '@tanstack/solid-store'
 import type { Accessor } from 'solid-js'
 import type { AnyFunction } from '@tanstack/pacer/types'
@@ -101,10 +102,15 @@ export interface SolidRateLimiter<TFn extends AnyFunction, TSelected = {}>
  */
 export function createRateLimiter<TFn extends AnyFunction, TSelected = {}>(
   fn: TFn,
-  initialOptions: RateLimiterOptions<TFn>,
+  options: RateLimiterOptions<TFn>,
   selector: (state: RateLimiterState) => TSelected = () => ({}) as TSelected,
 ): SolidRateLimiter<TFn, TSelected> {
-  const rateLimiter = new RateLimiter<TFn>(fn, initialOptions)
+  const mergedOptions = {
+    ...useDefaultPacerOptions().rateLimiter,
+    ...options,
+  } as RateLimiterOptions<TFn>
+
+  const rateLimiter = new RateLimiter<TFn>(fn, mergedOptions)
 
   const state = useStore(rateLimiter.store, selector)
 

package/src/throttler/createThrottler.ts

@@ -1,6 +1,7 @@
 import { Throttler } from '@tanstack/pacer/throttler'
 import { createEffect, onCleanup } from 'solid-js'
 import { useStore } from '@tanstack/solid-store'
+import { useDefaultPacerOptions } from '../provider/PacerProvider'
 import type { Store } from '@tanstack/solid-store'
 import type { Accessor } from 'solid-js'
 import type { AnyFunction } from '@tanstack/pacer/types'
@@ -98,10 +99,15 @@ export interface SolidThrottler<TFn extends AnyFunction, TSelected = {}>
  */
 export function createThrottler<TFn extends AnyFunction, TSelected = {}>(
   fn: TFn,
-  initialOptions: ThrottlerOptions<TFn>,
+  options: ThrottlerOptions<TFn>,
   selector: (state: ThrottlerState<TFn>) => TSelected = () => ({}) as TSelected,
 ): SolidThrottler<TFn, TSelected> {
-  const asyncThrottler = new Throttler<TFn>(fn, initialOptions)
+  const mergedOptions = {
+    ...useDefaultPacerOptions().throttler,
+    ...options,
+  } as ThrottlerOptions<TFn>
+
+  const asyncThrottler = new Throttler<TFn>(fn, mergedOptions)
 
   const state = useStore(asyncThrottler.store, selector)