@tanstack/solid-pacer 0.17.0 → 0.18.1

package/src/queuer/createQueuer.ts

@@ -2,13 +2,30 @@ 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 { Accessor, JSX } from 'solid-js'
 import type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
 
 export interface SolidQueuer<TValue, TSelected = {}> extends Omit<
   Queuer<TValue>,
   'store'
 > {
+  /**
+   * A Solid component that allows you to subscribe to the queuer state.
+   *
+   * This is useful for tracking specific parts of the queuer state
+   * deep in your component tree without needing to pass a selector to the hook.
+   *
+   * @example
+   * <queuer.Subscribe selector={(state) => ({ size: state.size, isRunning: state.isRunning })}>
+   *   {(state) => (
+   *     <div>Queue: {state().size} items, {state().isRunning ? 'Processing' : 'Idle'}</div>
+   *   )}
+   * </queuer.Subscribe>
+   */
+  Subscribe: <TSelected>(props: {
+    selector: (state: QueuerState<TValue>) => TSelected
+    children: ((state: Accessor<TSelected>) => JSX.Element) | JSX.Element
+  }) => JSX.Element
   /**
    * Reactive state that will be updated when the queuer state changes
    *
@@ -42,14 +59,24 @@ export interface SolidQueuer<TValue, TSelected = {}> extends Omit<
  *
  * ## State Management and Selector
  *
- * The hook uses TanStack Store for reactive state management. The `selector` parameter allows you
- * to specify which state changes will trigger a re-render, optimizing performance by preventing
- * unnecessary re-renders when irrelevant state changes occur.
+ * The hook uses TanStack Store for reactive state management. You can subscribe to state changes
+ * in two ways:
+ *
+ * **1. Using `queuer.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. 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.
+ * 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 items that have been processed
@@ -72,14 +99,14 @@ export interface SolidQueuer<TValue, TSelected = {}> extends Omit<
  *   }
  * );
  *
- * // Opt-in to re-render when items or isRunning changes (optimized for UI updates)
+ * // Opt-in to track items or isRunning changes (optimized for UI updates)
  * const queue = createQueuer(
  *   (item) => console.log('Processing', item),
  *   { started: true, wait: 1000 },
  *   (state) => ({ items: state.items, isRunning: state.isRunning })
  * );
  *
- * // Opt-in to re-render when execution metrics change (optimized for tracking progress)
+ * // Opt-in to track execution metrics changes (optimized for tracking progress)
  * const queue = createQueuer(
  *   (item) => console.log('Processing', item),
  *   { started: true, wait: 1000 },
@@ -111,7 +138,21 @@ export function createQueuer<TValue, TSelected = {}>(
     ...options,
   } as QueuerOptions<TValue>
 
-  const queuer = new Queuer(fn, mergedOptions)
+  const queuer = new Queuer(fn, mergedOptions) as unknown as SolidQueuer<
+    TValue,
+    TSelected
+  >
+
+  queuer.Subscribe = function Subscribe<TSelected>(props: {
+    selector: (state: QueuerState<TValue>) => TSelected
+    children: ((state: Accessor<TSelected>) => JSX.Element) | JSX.Element
+  }) {
+    const selected = useStore(queuer.store, props.selector)
+
+    return typeof props.children === 'function'
+      ? props.children(selected)
+      : props.children
+  }
 
   const state = useStore(queuer.store, selector)
 

package/src/rate-limiter/createRateLimiter.ts

@@ -2,7 +2,7 @@ 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 { Accessor, JSX } from 'solid-js'
 import type { AnyFunction } from '@tanstack/pacer/types'
 import type {
   RateLimiterOptions,
@@ -13,6 +13,23 @@ export interface SolidRateLimiter<
   TFn extends AnyFunction,
   TSelected = {},
 > extends Omit<RateLimiter<TFn>, 'store'> {
+  /**
+   * A Solid component that allows you to subscribe to the rate limiter state.
+   *
+   * This is useful for tracking specific parts of the rate limiter state
+   * deep in your component tree without needing to pass a selector to the hook.
+   *
+   * @example
+   * <rateLimiter.Subscribe selector={(state) => ({ rejectionCount: state.rejectionCount })}>
+   *   {(state) => (
+   *     <div>Rejections: {state().rejectionCount}</div>
+   *   )}
+   * </rateLimiter.Subscribe>
+   */
+  Subscribe: <TSelected>(props: {
+    selector: (state: RateLimiterState) => TSelected
+    children: ((state: Accessor<TSelected>) => JSX.Element) | JSX.Element
+  }) => JSX.Element
   /**
    * Reactive state that will be updated when the rate limiter state changes
    *
@@ -50,14 +67,24 @@ export interface SolidRateLimiter<
  *
  * ## State Management and Selector
  *
- * The hook uses TanStack Store for reactive state management. The `selector` parameter allows you
- * to specify which state changes will trigger a re-render, optimizing performance by preventing
- * unnecessary re-renders when irrelevant state changes occur.
+ * The hook uses TanStack Store for reactive state management. You can subscribe to state changes
+ * in two ways:
+ *
+ * **1. Using `rateLimiter.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. 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.
+ * 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 function executions that have been completed
@@ -73,33 +100,74 @@ export interface SolidRateLimiter<
  *   limit: 5,
  *   window: 60000,
  *   windowType: 'sliding',
- *   onReject: (rateLimiter) => {
- *     console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
- *   }
  * });
  *
- * // Opt-in to re-render when rate limit state changes (optimized for UI feedback)
+ * // Subscribe to state changes deep in component tree using Subscribe component
+ * <rateLimiter.Subscribe selector={(state) => ({ rejectionCount: state.rejectionCount })}>
+ *   {(state) => (
+ *     <div>Rejections: {state().rejectionCount}</div>
+ *   )}
+ * </rateLimiter.Subscribe>
+ *
+ * // Opt-in to track execution count changes at hook level (optimized for tracking successful executions)
  * const rateLimiter = createRateLimiter(
  *   apiCall,
- *   { limit: 5, window: 60000 },
- *   (state) => ({
- *     remainingInWindow: state.remainingInWindow,
- *     rejectionCount: state.rejectionCount
- *   })
+ *   {
+ *     limit: 5,
+ *     window: 60000,
+ *     windowType: 'sliding',
+ *   },
+ *   (state) => ({ executionCount: state.executionCount })
  * );
  *
- * // Opt-in to re-render when execution metrics change (optimized for tracking progress)
+ * // Opt-in to track rejection count changes (optimized for tracking rate limit violations)
  * const rateLimiter = createRateLimiter(
  *   apiCall,
- *   { limit: 5, window: 60000 },
+ *   {
+ *     limit: 5,
+ *     window: 60000,
+ *     windowType: 'sliding',
+ *   },
+ *   (state) => ({ rejectionCount: state.rejectionCount })
+ * );
+ *
+ * // Opt-in to track execution times changes (optimized for window calculations)
+ * const rateLimiter = createRateLimiter(
+ *   apiCall,
+ *   {
+ *     limit: 5,
+ *     window: 60000,
+ *     windowType: 'sliding',
+ *   },
+ *   (state) => ({ executionTimes: state.executionTimes })
+ * );
+ *
+ * // Multiple state properties - track when any of these change
+ * const rateLimiter = createRateLimiter(
+ *   apiCall,
+ *   {
+ *     limit: 5,
+ *     window: 60000,
+ *     windowType: 'sliding',
+ *   },
  *   (state) => ({
  *     executionCount: state.executionCount,
- *     nextWindowTime: state.nextWindowTime
+ *     rejectionCount: state.rejectionCount
  *   })
  * );
  *
+ * // Monitor rate limit status
+ * const handleClick = () => {
+ *   const remaining = rateLimiter.getRemainingInWindow();
+ *   if (remaining > 0) {
+ *     rateLimiter.maybeExecute(data);
+ *   } else {
+ *     showRateLimitWarning();
+ *   }
+ * };
+ *
  * // Access the selected state (will be empty object {} unless selector provided)
- * const { remainingInWindow, rejectionCount } = rateLimiter.state();
+ * const { executionCount, rejectionCount } = rateLimiter.state();
  * ```
  */
 export function createRateLimiter<TFn extends AnyFunction, TSelected = {}>(
@@ -112,7 +180,21 @@ export function createRateLimiter<TFn extends AnyFunction, TSelected = {}>(
     ...options,
   } as RateLimiterOptions<TFn>
 
-  const rateLimiter = new RateLimiter<TFn>(fn, mergedOptions)
+  const rateLimiter = new RateLimiter<TFn>(
+    fn,
+    mergedOptions,
+  ) as unknown as SolidRateLimiter<TFn, TSelected>
+
+  rateLimiter.Subscribe = function Subscribe<TSelected>(props: {
+    selector: (state: RateLimiterState) => TSelected
+    children: ((state: Accessor<TSelected>) => JSX.Element) | JSX.Element
+  }) {
+    const selected = useStore(rateLimiter.store, props.selector)
+
+    return typeof props.children === 'function'
+      ? props.children(selected)
+      : props.children
+  }
 
   const state = useStore(rateLimiter.store, selector)
 

package/src/throttler/createThrottledSignal.ts

@@ -12,7 +12,7 @@ import type {
  * This hook combines Solid's createSignal with throttling functionality to provide controlled state updates.
  *
  * Throttling ensures state updates occur at a controlled rate regardless of how frequently the setter is called.
- * This is useful for rate-limiting expensive re-renders or operations that depend on rapidly changing state.
+ * This is useful for rate-limiting expensive updates or operations that depend on rapidly changing state.
  *
  * The hook returns a tuple containing:
  * - The throttled state value accessor

package/src/throttler/createThrottledValue.ts

@@ -12,7 +12,7 @@ import type {
  * This hook uses Solid's createSignal internally to manage the throttled state.
  *
  * Throttling ensures the value updates occur at a controlled rate regardless of how frequently the input value changes.
- * This is useful for rate-limiting expensive re-renders or API calls that depend on rapidly changing values.
+ * This is useful for rate-limiting expensive updates or API calls that depend on rapidly changing values.
  *
  * The hook returns a tuple containing:
  * - An accessor function that provides the throttled value

package/src/throttler/createThrottler.ts

@@ -3,7 +3,7 @@ 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 { Accessor, JSX } from 'solid-js'
 import type { AnyFunction } from '@tanstack/pacer/types'
 import type {
   ThrottlerOptions,
@@ -14,6 +14,23 @@ export interface SolidThrottler<
   TFn extends AnyFunction,
   TSelected = {},
 > extends Omit<Throttler<TFn>, 'store'> {
+  /**
+   * A Solid component that allows you to subscribe to the throttler state.
+   *
+   * This is useful for tracking specific parts of the throttler state
+   * deep in your component tree without needing to pass a selector to the hook.
+   *
+   * @example
+   * <throttler.Subscribe selector={(state) => ({ isPending: state.isPending })}>
+   *   {(state) => (
+   *     <div>{state().isPending ? 'Loading...' : 'Ready'}</div>
+   *   )}
+   * </throttler.Subscribe>
+   */
+  Subscribe: <TSelected>(props: {
+    selector: (state: ThrottlerState<TFn>) => TSelected
+    children: ((state: Accessor<TSelected>) => JSX.Element) | JSX.Element
+  }) => JSX.Element
   /**
    * Reactive state that will be updated when the throttler state changes
    *
@@ -41,14 +58,24 @@ export interface SolidThrottler<
  *
  * ## State Management and Selector
  *
- * The hook uses TanStack Store for reactive state management. The `selector` parameter allows you
- * to specify which state changes will trigger a re-render, optimizing performance by preventing
- * unnecessary re-renders when irrelevant state changes occur.
+ * The hook uses TanStack Store for reactive state management. You can subscribe to state changes
+ * in two ways:
+ *
+ * **1. Using `throttler.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. 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.
+ * 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:
  * - `canLeadingExecute`: Whether the throttler can execute on the leading edge
@@ -65,21 +92,28 @@ export interface SolidThrottler<
  * // Default behavior - no reactive state subscriptions
  * const throttler = createThrottler(setValue, { wait: 1000 });
  *
- * // Opt-in to re-render when isPending changes (optimized for loading states)
+ * // Subscribe to state changes deep in component tree using Subscribe component
+ * <throttler.Subscribe selector={(state) => ({ isPending: state.isPending })}>
+ *   {(state) => (
+ *     <div>{state().isPending ? 'Loading...' : 'Ready'}</div>
+ *   )}
+ * </throttler.Subscribe>
+ *
+ * // Opt-in to track isPending changes at hook level (optimized for loading states)
  * const throttler = createThrottler(
  *   setValue,
  *   { wait: 1000 },
  *   (state) => ({ isPending: state.isPending })
  * );
  *
- * // Opt-in to re-render when executionCount changes (optimized for tracking execution)
+ * // Opt-in to track executionCount changes (optimized for tracking execution)
  * const throttler = createThrottler(
  *   setValue,
  *   { wait: 1000 },
  *   (state) => ({ executionCount: state.executionCount })
  * );
  *
- * // Multiple state properties - re-render when any of these change
+ * // Multiple state properties - track when any of these change
  * const throttler = createThrottler(
  *   setValue,
  *   {
@@ -109,7 +143,21 @@ export function createThrottler<TFn extends AnyFunction, TSelected = {}>(
     ...options,
   } as ThrottlerOptions<TFn>
 
-  const asyncThrottler = new Throttler<TFn>(fn, mergedOptions)
+  const asyncThrottler = new Throttler<TFn>(
+    fn,
+    mergedOptions,
+  ) as unknown as SolidThrottler<TFn, TSelected>
+
+  asyncThrottler.Subscribe = function Subscribe<TSelected>(props: {
+    selector: (state: ThrottlerState<TFn>) => TSelected
+    children: ((state: Accessor<TSelected>) => JSX.Element) | JSX.Element
+  }) {
+    const selected = useStore(asyncThrottler.store, props.selector)
+
+    return typeof props.children === 'function'
+      ? props.children(selected)
+      : props.children
+  }
 
   const state = useStore(asyncThrottler.store, selector)