@tanstack/solid-pacer 0.9.1 → 0.11.0

package/src/async-throttler/createAsyncThrottler.ts

@@ -1,5 +1,6 @@
 import { AsyncThrottler } from '@tanstack/pacer/async-throttler'
 import { useStore } from '@tanstack/solid-store'
+import type { Store } from '@tanstack/solid-store'
 import type { Accessor } from 'solid-js'
 import type { AnyAsyncFunction } from '@tanstack/pacer/types'
 import type {
@@ -9,14 +10,20 @@ import type {
 
 export interface SolidAsyncThrottler<
   TFn extends AnyAsyncFunction,
-  TSelected = AsyncThrottlerState<TFn>,
+  TSelected = {},
 > extends Omit<AsyncThrottler<TFn>, 'store'> {
   /**
-   * Reactive state that will be updated and re-rendered when the throttler state changes
+   * Reactive state that will be updated when the throttler state changes
    *
    * Use this instead of `throttler.store.state`
    */
   readonly state: Accessor<Readonly<TSelected>>
+  /**
+   * @deprecated Use `throttler.state` instead of `throttler.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 `useStore` hook internally.
+   * Although, you can make the state reactive by using the `useStore` in your own usage.
+   */
+  readonly store: Store<Readonly<AsyncThrottlerState<TFn>>>
 }
 
 /**
@@ -40,9 +47,34 @@ export interface SolidAsyncThrottler<
  * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
  * - The error state can be checked using the underlying AsyncThrottler instance
  *
+ * ## 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.
+ *
+ * **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 state properties:
+ * - `canLeadingExecute`: Whether the throttler can execute on the leading edge
+ * - `canTrailingExecute`: Whether the throttler can execute on the trailing edge
+ * - `executionCount`: Number of function executions that have been completed
+ * - `hasError`: Whether the last execution resulted in an error
+ * - `isPending`: Whether the throttler is waiting for the timeout to trigger execution
+ * - `isExecuting`: Whether an async function execution is currently in progress
+ * - `lastArgs`: The arguments from the most recent call to maybeExecute
+ * - `lastError`: The error from the most recent failed execution (if any)
+ * - `lastExecutionTime`: Timestamp of the last execution
+ * - `lastResult`: The result from the most recent successful execution
+ * - `nextExecutionTime`: Timestamp of the next allowed execution
+ * - `status`: Current execution status ('disabled' | 'idle' | 'pending' | 'executing')
+ *
  * @example
  * ```tsx
- * // Basic API call throttling
+ * // Default behavior - no reactive state subscriptions
  * const { maybeExecute } = createAsyncThrottler(
  *   async (id: string) => {
  *     const data = await api.fetchData(id);
@@ -51,12 +83,21 @@ export interface SolidAsyncThrottler<
  *   { wait: 1000 }
  * );
  *
- * // With state management
- * const [data, setData] = createSignal(null);
- * const { maybeExecute } = createAsyncThrottler(
+ * // Opt-in to re-render when isPending or isExecuting changes (optimized for loading states)
+ * const throttler = createAsyncThrottler(
  *   async (query) => {
  *     const result = await searchAPI(query);
- *     setData(result);
+ *     return result;
+ *   },
+ *   { wait: 2000 },
+ *   (state) => ({ isPending: state.isPending, isExecuting: state.isExecuting })
+ * );
+ *
+ * // Opt-in to re-render when error state changes (optimized for error handling)
+ * const throttler = createAsyncThrottler(
+ *   async (query) => {
+ *     const result = await searchAPI(query);
+ *     return result;
  *   },
  *   {
  *     wait: 2000,
@@ -65,17 +106,22 @@ export interface SolidAsyncThrottler<
  *     onError: (error) => {
  *       console.error('API call failed:', error);
  *     }
- *   }
+ *   },
+ *   (state) => ({ hasError: state.hasError, lastError: state.lastError })
  * );
+ *
+ * // Access the selected state (will be empty object {} unless selector provided)
+ * const { isPending, isExecuting } = throttler.state();
  * ```
  */
 export function createAsyncThrottler<
   TFn extends AnyAsyncFunction,
-  TSelected = AsyncThrottlerState<TFn>,
+  TSelected = {},
 >(
   fn: TFn,
   initialOptions: AsyncThrottlerOptions<TFn>,
-  selector?: (state: AsyncThrottlerState<TFn>) => TSelected,
+  selector: (state: AsyncThrottlerState<TFn>) => TSelected = () =>
+    ({}) as TSelected,
 ): SolidAsyncThrottler<TFn, TSelected> {
   const asyncThrottler = new AsyncThrottler(fn, initialOptions)
 

package/src/batcher/createBatcher.ts

@@ -1,9 +1,10 @@
 import { Batcher } from '@tanstack/pacer/batcher'
 import { useStore } from '@tanstack/solid-store'
+import type { Store } from '@tanstack/solid-store'
 import type { Accessor } from 'solid-js'
 import type { BatcherOptions, BatcherState } from '@tanstack/pacer/batcher'
 
-export interface SolidBatcher<TValue, TSelected = BatcherState<TValue>>
+export interface SolidBatcher<TValue, TSelected = {}>
   extends Omit<Batcher<TValue>, 'store'> {
   /**
    * Reactive state that will be updated when the batcher state changes
@@ -11,6 +12,12 @@ export interface SolidBatcher<TValue, TSelected = BatcherState<TValue>>
    * Use this instead of `batcher.store.state`
    */
   readonly state: Accessor<Readonly<TSelected>>
+  /**
+   * @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 `useStore` hook internally.
+   * Although, you can make the state reactive by using the `useStore` in your own usage.
+   */
+  readonly store: Store<Readonly<BatcherState<TValue>>>
 }
 
 /**
@@ -28,8 +35,26 @@ export interface SolidBatcher<TValue, TSelected = BatcherState<TValue>>
  * - 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. 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.
+ *
+ * **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 state properties:
+ * - `executionCount`: Number of batch executions that have been completed
+ * - `isRunning`: Whether the batcher is currently running (not stopped)
+ * - `items`: Array of items currently queued for batching
+ * - `totalItemsProcessed`: Total number of individual items that have been processed across all batches
+ *
  * Example usage:
  * ```tsx
+ * // Default behavior - no reactive state subscriptions
  * const batcher = createBatcher(
  *   (items) => {
  *     // Process batch of items
@@ -43,6 +68,23 @@ export interface SolidBatcher<TValue, TSelected = BatcherState<TValue>>
  *   }
  * );
  *
+ * // Opt-in to re-render when items or isRunning changes (optimized for UI updates)
+ * const batcher = createBatcher(
+ *   (items) => console.log('Processing batch:', items),
+ *   { maxSize: 5, wait: 2000 },
+ *   (state) => ({ items: state.items, isRunning: state.isRunning })
+ * );
+ *
+ * // Opt-in to re-render when execution metrics change (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');
@@ -51,19 +93,15 @@ export interface SolidBatcher<TValue, TSelected = BatcherState<TValue>>
  * 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.executionCount());
- * console.log('Item count:', batcher.totalItemsProcessed());
+ * // Access the selected state (will be empty object {} unless selector provided)
+ * const { items, isRunning } = batcher.state();
  * ```
  */
-export function createBatcher<TValue, TSelected = BatcherState<TValue>>(
+export function createBatcher<TValue, TSelected = {}>(
   fn: (items: Array<TValue>) => void,
   initialOptions: BatcherOptions<TValue> = {},
-  selector?: (state: BatcherState<TValue>) => TSelected,
+  selector: (state: BatcherState<TValue>) => TSelected = () =>
+    ({}) as TSelected,
 ): SolidBatcher<TValue, TSelected> {
   const batcher = new Batcher(fn, initialOptions)
 

package/src/debouncer/createDebouncedSignal.ts

@@ -21,21 +21,53 @@ import type {
  * - A function to update the debounced value
  * - The debouncer instance with additional control methods and state signals
  *
+ * ## State Management and Selector
+ *
+ * The hook uses TanStack Store for reactive state management via the underlying debouncer instance.
+ * The `selector` parameter allows you to specify which debouncer state changes will trigger reactive updates,
+ * optimizing performance by preventing unnecessary subscriptions 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 reactive updates and gives you
+ * full control over when your component subscribes to state changes. Only when you provide a selector will
+ * the reactive system track the selected state values.
+ *
+ * Available debouncer state properties:
+ * - `canLeadingExecute`: Whether the debouncer can execute on the leading edge
+ * - `executionCount`: Number of function executions that have been completed
+ * - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution
+ * - `lastArgs`: The arguments from the most recent call to maybeExecute
+ * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
+ *
  * @example
  * ```tsx
- * // Debounced search input
+ * // Default behavior - no reactive state subscriptions
  * const [searchTerm, setSearchTerm, debouncer] = createDebouncedSignal('', {
  *   wait: 500 // Wait 500ms after last keystroke
  * });
  *
+ * // Opt-in to reactive updates when pending state changes (optimized for loading indicators)
+ * const [searchTerm, setSearchTerm, debouncer] = createDebouncedSignal(
+ *   '',
+ *   { wait: 500 },
+ *   (state) => ({ isPending: state.isPending })
+ * );
+ *
+ * // Opt-in to reactive updates when execution count changes (optimized for tracking executions)
+ * const [searchTerm, setSearchTerm, debouncer] = createDebouncedSignal(
+ *   '',
+ *   { wait: 500 },
+ *   (state) => ({ executionCount: state.executionCount })
+ * );
+ *
  * // Update value - will be debounced
  * const handleChange = (e) => {
  *   setSearchTerm(e.target.value);
  * };
  *
  * // Access debouncer state via signals
- * console.log('Executions:', debouncer.executionCount());
- * console.log('Is pending:', debouncer.isPending());
+ * console.log('Executions:', debouncer.state().executionCount);
+ * console.log('Is pending:', debouncer.state().isPending);
  *
  * // In onExecute callback, use get* methods
  * const [searchTerm, setSearchTerm, debouncer] = createDebouncedSignal('', {
@@ -46,10 +78,7 @@ import type {
  * });
  * ```
  */
-export function createDebouncedSignal<
-  TValue,
-  TSelected = DebouncerState<Setter<TValue>>,
->(
+export function createDebouncedSignal<TValue, TSelected = {}>(
   value: TValue,
   initialOptions: DebouncerOptions<Setter<TValue>>,
   selector?: (state: DebouncerState<Setter<TValue>>) => TSelected,

package/src/debouncer/createDebouncedValue.ts

@@ -24,27 +24,52 @@ import type {
  * - An Accessor that provides the current debounced value
  * - The debouncer instance with control methods
  *
+ * ## State Management and Selector
+ *
+ * The hook uses TanStack Store for reactive state management via the underlying debouncer instance.
+ * The `selector` parameter allows you to specify which debouncer state changes will trigger reactive updates,
+ * optimizing performance by preventing unnecessary subscriptions 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 reactive updates and gives you
+ * full control over when your component subscribes to state changes. Only when you provide a selector will
+ * the reactive system track the selected state values.
+ *
+ * Available debouncer state properties:
+ * - `canLeadingExecute`: Whether the debouncer can execute on the leading edge
+ * - `executionCount`: Number of function executions that have been completed
+ * - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution
+ * - `lastArgs`: The arguments from the most recent call to maybeExecute
+ * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
+ *
  * @example
  * ```tsx
- * // Debounce a search query
+ * // Default behavior - no reactive state subscriptions
  * const [searchQuery, setSearchQuery] = createSignal('');
  * const [debouncedQuery, debouncer] = createDebouncedValue(searchQuery, {
  *   wait: 500 // Wait 500ms after last change
  * });
  *
+ * // Opt-in to reactive updates when pending state changes (optimized for loading indicators)
+ * const [debouncedQuery, debouncer] = createDebouncedValue(
+ *   searchQuery,
+ *   { wait: 500 },
+ *   (state) => ({ isPending: state.isPending })
+ * );
+ *
  * // debouncedQuery will update 500ms after searchQuery stops changing
  * createEffect(() => {
  *   fetchSearchResults(debouncedQuery());
  * });
  *
+ * // Access debouncer state via signals
+ * console.log('Is pending:', debouncer.state().isPending);
+ *
  * // Control the debouncer
  * debouncer.cancel(); // Cancel any pending updates
  * ```
  */
-export function createDebouncedValue<
-  TValue,
-  TSelected = DebouncerState<Setter<TValue>>,
->(
+export function createDebouncedValue<TValue, TSelected = {}>(
   value: Accessor<TValue>,
   initialOptions: DebouncerOptions<Setter<TValue>>,
   selector?: (state: DebouncerState<Setter<TValue>>) => TSelected,

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 type { Store } from '@tanstack/solid-store'
 import type { Accessor } from 'solid-js'
 import type { AnyFunction } from '@tanstack/pacer/types'
 import type {
@@ -8,16 +9,20 @@ import type {
   DebouncerState,
 } from '@tanstack/pacer/debouncer'
 
-export interface SolidDebouncer<
-  TFn extends AnyFunction,
-  TSelected = DebouncerState<TFn>,
-> extends Omit<Debouncer<TFn>, 'store'> {
+export interface SolidDebouncer<TFn extends AnyFunction, TSelected = {}>
+  extends Omit<Debouncer<TFn>, 'store'> {
   /**
    * Reactive state that will be updated when the debouncer state changes
    *
    * Use this instead of `debouncer.store.state`
    */
   readonly state: Accessor<Readonly<TSelected>>
+  /**
+   * @deprecated Use `debouncer.state` instead of `debouncer.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 `useStore` hook internally.
+   * Although, you can make the state reactive by using the `useStore` in your own usage.
+   */
+  readonly store: Store<Readonly<DebouncerState<TFn>>>
 }
 
 /**
@@ -35,12 +40,55 @@ export interface SolidDebouncer<
  * since the last call. If the function is called again before the wait time expires, the
  * timer resets and starts waiting again.
  *
+ * ## 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.
+ *
+ * **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 state properties:
+ * - `canLeadingExecute`: Whether the debouncer can execute on the leading edge
+ * - `executionCount`: Number of function executions that have been completed
+ * - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution
+ * - `lastArgs`: The arguments from the most recent call to maybeExecute
+ * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
+ *
  * @example
  * ```tsx
- * // Debounce a search function to limit API calls
+ * // Default behavior - no reactive state subscriptions
+ * const debouncer = createDebouncer(
+ *   (query: string) => fetchSearchResults(query),
+ *   { wait: 500 }
+ * );
+ *
+ * // Opt-in to re-render when isPending changes (optimized for loading states)
  * const debouncer = createDebouncer(
  *   (query: string) => fetchSearchResults(query),
- *   { wait: 500 } // Wait 500ms after last keystroke
+ *   { wait: 500 },
+ *   (state) => ({ isPending: state.isPending })
+ * );
+ *
+ * // Opt-in to re-render when executionCount changes (optimized for tracking execution)
+ * const debouncer = createDebouncer(
+ *   (query: string) => fetchSearchResults(query),
+ *   { wait: 500 },
+ *   (state) => ({ executionCount: state.executionCount })
+ * );
+ *
+ * // Multiple state properties - re-render when any of these change
+ * const debouncer = createDebouncer(
+ *   (query: string) => fetchSearchResults(query),
+ *   { wait: 500 },
+ *   (state) => ({
+ *     isPending: state.isPending,
+ *     executionCount: state.executionCount,
+ *     status: state.status
+ *   })
  * );
  *
  * // In an event handler
@@ -48,21 +96,14 @@ export interface SolidDebouncer<
  *   debouncer.maybeExecute(e.target.value);
  * };
  *
- * // Access debouncer state via signals
- * console.log('Executions:', debouncer.executionCount());
- * console.log('Is pending:', debouncer.isPending());
- *
- * // Update options
- * debouncer.setOptions({ wait: 1000 });
+ * // Access the selected state (will be empty object {} unless selector provided)
+ * const { isPending } = debouncer.state();
  * ```
  */
-export function createDebouncer<
-  TFn extends AnyFunction,
-  TSelected = DebouncerState<TFn>,
->(
+export function createDebouncer<TFn extends AnyFunction, TSelected = {}>(
   fn: TFn,
   initialOptions: DebouncerOptions<TFn>,
-  selector?: (state: DebouncerState<TFn>) => TSelected,
+  selector: (state: DebouncerState<TFn>) => TSelected = () => ({}) as TSelected,
 ): SolidDebouncer<TFn, TSelected> {
   const asyncDebouncer = new Debouncer<TFn>(fn, initialOptions)
 

package/src/queuer/createQueuer.ts

@@ -1,9 +1,10 @@
 import { Queuer } from '@tanstack/pacer/queuer'
 import { useStore } from '@tanstack/solid-store'
+import type { Store } from '@tanstack/solid-store'
 import type { Accessor } from 'solid-js'
 import type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
 
-export interface SolidQueuer<TValue, TSelected = QueuerState<TValue>>
+export interface SolidQueuer<TValue, TSelected = {}>
   extends Omit<Queuer<TValue>, 'store'> {
   /**
    * Reactive state that will be updated when the queuer state changes
@@ -11,6 +12,12 @@ export interface SolidQueuer<TValue, TSelected = QueuerState<TValue>>
    * Use this instead of `queuer.store.state`
    */
   readonly state: Accessor<Readonly<TSelected>>
+  /**
+   * @deprecated Use `queuer.state` instead of `queuer.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 `useStore` hook internally.
+   * Although, you can make the state reactive by using the `useStore` in your own usage.
+   */
+  readonly store: Store<Readonly<QueuerState<TValue>>>
 }
 
 /**
@@ -30,11 +37,26 @@ export interface SolidQueuer<TValue, TSelected = QueuerState<TValue>>
  *
  * 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.
  *
+ * ## 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.
+ *
+ * **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 state properties:
+ * - `executionCount`: Number of items that have been processed
+ * - `isRunning`: Whether the queuer is currently running (not stopped)
+ * - `items`: Array of items currently queued for processing
+ * - `rejectionCount`: Number of items that were rejected (expired or failed validation)
+ *
  * Example usage:
  * ```tsx
- * // Example with Solid signals and scheduling
- * const [items, setItems] = createSignal([]);
- *
+ * // Default behavior - no reactive state subscriptions
  * const queue = createQueuer(
  *   (item) => {
  *     // process item synchronously
@@ -43,11 +65,27 @@ export interface SolidQueuer<TValue, TSelected = QueuerState<TValue>>
  *   {
  *     started: true, // Start processing immediately
  *     wait: 1000,    // Process one item every second
- *     onItemsChange: (queue) => setItems(queue.peekAllItems()),
  *     getPriority: (item) => item.priority // Process higher priority items first
  *   }
  * );
  *
+ * // Opt-in to re-render when 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)
+ * const queue = createQueuer(
+ *   (item) => console.log('Processing', item),
+ *   { started: true, wait: 1000 },
+ *   (state) => ({
+ *     executionCount: state.executionCount,
+ *     rejectionCount: state.rejectionCount
+ *   })
+ * );
+ *
  * // Add items to process - they'll be handled automatically
  * queue.addItem('task1');
  * queue.addItem('task2');
@@ -56,18 +94,14 @@ export interface SolidQueuer<TValue, TSelected = QueuerState<TValue>>
  * queue.stop();  // Pause processing
  * queue.start(); // Resume processing
  *
- * // Access queue state via signals
- * console.log('Items:', queue.allItems());
- * console.log('Size:', queue.size());
- * console.log('Is empty:', queue.isEmpty());
- * console.log('Is running:', queue.isRunning());
- * console.log('Next item:', queue.nextItem());
+ * // Access the selected state (will be empty object {} unless selector provided)
+ * const { items, isRunning } = queue.state();
  * ```
  */
-export function createQueuer<TValue, TSelected = QueuerState<TValue>>(
+export function createQueuer<TValue, TSelected = {}>(
   fn: (item: TValue) => void,
   initialOptions: QueuerOptions<TValue> = {},
-  selector?: (state: QueuerState<TValue>) => TSelected,
+  selector: (state: QueuerState<TValue>) => TSelected = () => ({}) as TSelected,
 ): SolidQueuer<TValue, TSelected> {
   const queuer = new Queuer(fn, initialOptions)
 
@@ -76,5 +110,5 @@ export function createQueuer<TValue, TSelected = QueuerState<TValue>>(
   return {
     ...queuer,
     state,
-  } as unknown as SolidQueuer<TValue, TSelected> // omit `store` in favor of `state`
+  } as SolidQueuer<TValue, TSelected> // omit `store` in favor of `state`
 }

package/src/rate-limiter/createRateLimitedSignal.ts

@@ -35,15 +35,42 @@ import type {
  * For more direct control over rate limiting without state management,
  * consider using the lower-level createRateLimiter hook instead.
  *
+ * ## State Management and Selector
+ *
+ * The hook uses TanStack Store for reactive state management via the underlying rate limiter instance.
+ * The `selector` parameter allows you to specify which rate limiter state changes will trigger reactive updates,
+ * optimizing performance by preventing unnecessary subscriptions 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 reactive updates and gives you
+ * full control over when your component subscribes to state changes. Only when you provide a selector will
+ * 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')
+ *
  * @example
  * ```tsx
- * // Basic rate limiting - update state at most 5 times per minute with a sliding window
+ * // Default behavior - no reactive state subscriptions
  * const [value, setValue, rateLimiter] = createRateLimitedSignal(0, {
  *   limit: 5,
  *   window: 60000,
  *   windowType: 'sliding'
  * });
  *
+ * // Opt-in to reactive updates when limit state changes (optimized for UI feedback)
+ * const [value, setValue, rateLimiter] = createRateLimitedSignal(
+ *   0,
+ *   { limit: 5, window: 60000 },
+ *   (state) => ({ isAtLimit: state.isAtLimit, remainingInWindow: state.remainingInWindow })
+ * );
+ *
  * // With rejection callback and fixed window
  * const [value, setValue] = createRateLimitedSignal(0, {
  *   limit: 3,
@@ -56,7 +83,7 @@ import type {
  *
  * // Access rateLimiter state via signals
  * const handleSubmit = () => {
- *   const remaining = rateLimiter.remainingInWindow();
+ *   const remaining = rateLimiter.state().remainingInWindow;
  *   if (remaining > 0) {
  *     setValue(newValue);
  *   } else {
@@ -65,7 +92,7 @@ import type {
  * };
  * ```
  */
-export function createRateLimitedSignal<TValue, TSelected = RateLimiterState>(
+export function createRateLimitedSignal<TValue, TSelected = {}>(
   value: TValue,
   initialOptions: RateLimiterOptions<Setter<TValue>>,
   selector?: (state: RateLimiterState) => TSelected,