@tanstack/preact-pacer 0.18.0 → 0.19.1

package/src/async-queuer/useAsyncQueuer.ts

@@ -7,11 +7,29 @@ import type {
   AsyncQueuerOptions,
   AsyncQueuerState,
 } from '@tanstack/pacer/async-queuer'
+import type { ComponentChildren } from 'preact'
 
-export interface ReactAsyncQueuer<TValue, TSelected = {}> extends Omit<
+export interface PreactAsyncQueuer<TValue, TSelected = {}> extends Omit<
   AsyncQueuer<TValue>,
   'store'
 > {
+  /**
+   * A Preact HOC (Higher Order Component) that allows you to subscribe to the async queuer state.
+   *
+   * This is useful for opting into state re-renders for 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 })}>
+   *   {({ size }) => (
+   *     <div>Queue Size: {size}</div>
+   *   )}
+   * </queuer.Subscribe>
+   */
+  Subscribe: <TSelected>(props: {
+    selector: (state: AsyncQueuerState<TValue>) => TSelected
+    children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+  }) => ComponentChildren
   /**
    * Reactive state that will be updated and re-rendered when the queuer state changes
    *
@@ -50,14 +68,24 @@ export interface ReactAsyncQueuer<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` HOC (Recommended for component tree subscriptions)**
+ *
+ * Use the `Subscribe` HOC 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 a re-render
+ * at the hook level, 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.
+ * tracking by providing a selector function or using the `Subscribe` HOC. This prevents unnecessary
+ * re-renders and gives you full control over when your component updates.
  *
  * Available state properties:
  * - `activeItems`: Items currently being processed by the queuer
@@ -88,7 +116,14 @@ export interface ReactAsyncQueuer<TValue, TSelected = {}> extends Omit<
  *   { concurrency: 2, maxSize: 100, started: false }
  * );
  *
- * // Opt-in to re-render when queue size changes (optimized for displaying queue length)
+ * // Subscribe to state changes deep in component tree using Subscribe HOC
+ * <asyncQueuer.Subscribe selector={(state) => ({ size: state.size })}>
+ *   {({ size }) => (
+ *     <div>Queue Size: {size}</div>
+ *   )}
+ * </asyncQueuer.Subscribe>
+ *
+ * // Opt-in to re-render when queue size changes at hook level (optimized for displaying queue length)
  * const asyncQueuer = useAsyncQueuer(
  *   async (item) => {
  *     const result = await processItem(item);
@@ -172,15 +207,31 @@ export function useAsyncQueuer<TValue, TSelected = {}>(
   options: AsyncQueuerOptions<TValue> = {},
   selector: (state: AsyncQueuerState<TValue>) => TSelected = () =>
     ({}) as TSelected,
-): ReactAsyncQueuer<TValue, TSelected> {
+): PreactAsyncQueuer<TValue, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().asyncQueuer,
     ...options,
   } as AsyncQueuerOptions<TValue>
 
-  const [asyncQueuer] = useState(
-    () => new AsyncQueuer<TValue>(fn, mergedOptions),
-  )
+  const [asyncQueuer] = useState(() => {
+    const queuerInstance = new AsyncQueuer<TValue>(
+      fn,
+      mergedOptions,
+    ) as unknown as PreactAsyncQueuer<TValue, TSelected>
+
+    queuerInstance.Subscribe = function Subscribe<TSelected>(props: {
+      selector: (state: AsyncQueuerState<TValue>) => TSelected
+      children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+    }) {
+      const selected = useStore(queuerInstance.store, props.selector)
+
+      return typeof props.children === 'function'
+        ? props.children(selected)
+        : props.children
+    }
+
+    return queuerInstance
+  })
 
   asyncQueuer.fn = fn
   asyncQueuer.setOptions(mergedOptions)
@@ -192,7 +243,7 @@ export function useAsyncQueuer<TValue, TSelected = {}>(
       ({
         ...asyncQueuer,
         state,
-      }) as ReactAsyncQueuer<TValue, TSelected>, // omit `store` in favor of `state`
+      }) as PreactAsyncQueuer<TValue, TSelected>, // omit `store` in favor of `state`
     [asyncQueuer, state],
   )
 }

package/src/async-rate-limiter/useAsyncRateLimiter.ts

@@ -8,11 +8,29 @@ import type {
   AsyncRateLimiterOptions,
   AsyncRateLimiterState,
 } from '@tanstack/pacer/async-rate-limiter'
+import type { ComponentChildren } from 'preact'
 
-export interface ReactAsyncRateLimiter<
+export interface PreactAsyncRateLimiter<
   TFn extends AnyAsyncFunction,
   TSelected = {},
 > extends Omit<AsyncRateLimiter<TFn>, 'store'> {
+  /**
+   * A Preact HOC (Higher Order Component) that allows you to subscribe to the async rate limiter state.
+   *
+   * This is useful for opting into state re-renders for 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 })}>
+   *   {({ rejectionCount }) => (
+   *     <div>Rejections: {rejectionCount}</div>
+   *   )}
+   * </rateLimiter.Subscribe>
+   */
+  Subscribe: <TSelected>(props: {
+    selector: (state: AsyncRateLimiterState<TFn>) => TSelected
+    children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+  }) => ComponentChildren
   /**
    * Reactive state that will be updated and re-rendered when the rate limiter state changes
    *
@@ -57,14 +75,24 @@ export interface ReactAsyncRateLimiter<
  *
  * ## 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` HOC (Recommended for component tree subscriptions)**
+ *
+ * Use the `Subscribe` HOC 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 a re-render
+ * at the hook level, 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.
+ * tracking by providing a selector function or using the `Subscribe` HOC. This prevents unnecessary
+ * re-renders and gives you full control over when your component updates.
  *
  * Available state properties:
  * - `errorCount`: Number of function executions that have resulted in errors
@@ -86,7 +114,14 @@ export interface ReactAsyncRateLimiter<
  *   { limit: 5, window: 1000 } // 5 calls per second
  * );
  *
- * // Opt-in to re-render when execution state changes (optimized for loading indicators)
+ * // Subscribe to state changes deep in component tree using Subscribe HOC
+ * <asyncRateLimiter.Subscribe selector={(state) => ({ rejectionCount: state.rejectionCount })}>
+ *   {({ rejectionCount }) => (
+ *     <div>Rejections: {rejectionCount}</div>
+ *   )}
+ * </asyncRateLimiter.Subscribe>
+ *
+ * // Opt-in to re-render when execution state changes at hook level (optimized for loading indicators)
  * const asyncRateLimiter = useAsyncRateLimiter(
  *   async (id: string) => {
  *     const data = await api.fetchData(id);
@@ -184,15 +219,31 @@ export function useAsyncRateLimiter<
   options: AsyncRateLimiterOptions<TFn>,
   selector: (state: AsyncRateLimiterState<TFn>) => TSelected = () =>
     ({}) as TSelected,
-): ReactAsyncRateLimiter<TFn, TSelected> {
+): PreactAsyncRateLimiter<TFn, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().asyncRateLimiter,
     ...options,
   } as AsyncRateLimiterOptions<TFn>
 
-  const [asyncRateLimiter] = useState(
-    () => new AsyncRateLimiter<TFn>(fn, mergedOptions),
-  )
+  const [asyncRateLimiter] = useState(() => {
+    const rateLimiterInstance = new AsyncRateLimiter<TFn>(
+      fn,
+      mergedOptions,
+    ) as unknown as PreactAsyncRateLimiter<TFn, TSelected>
+
+    rateLimiterInstance.Subscribe = function Subscribe<TSelected>(props: {
+      selector: (state: AsyncRateLimiterState<TFn>) => TSelected
+      children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+    }) {
+      const selected = useStore(rateLimiterInstance.store, props.selector)
+
+      return typeof props.children === 'function'
+        ? props.children(selected)
+        : props.children
+    }
+
+    return rateLimiterInstance
+  })
 
   asyncRateLimiter.fn = fn
   asyncRateLimiter.setOptions(mergedOptions)
@@ -204,7 +255,7 @@ export function useAsyncRateLimiter<
       ({
         ...asyncRateLimiter,
         state,
-      }) as ReactAsyncRateLimiter<TFn, TSelected>, // omit `store` in favor of `state`
+      }) as PreactAsyncRateLimiter<TFn, TSelected>, // omit `store` in favor of `state`
     [asyncRateLimiter, state],
   )
 }

package/src/async-throttler/useAsyncThrottler.ts

@@ -8,11 +8,29 @@ import type {
   AsyncThrottlerOptions,
   AsyncThrottlerState,
 } from '@tanstack/pacer/async-throttler'
+import type { ComponentChildren } from 'preact'
 
-export interface ReactAsyncThrottler<
+export interface PreactAsyncThrottler<
   TFn extends AnyAsyncFunction,
   TSelected = {},
 > extends Omit<AsyncThrottler<TFn>, 'store'> {
+  /**
+   * A Preact HOC (Higher Order Component) that allows you to subscribe to the async throttler state.
+   *
+   * This is useful for opting into state re-renders for 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 })}>
+   *   {({ isPending }) => (
+   *     <div>{isPending ? 'Loading...' : 'Ready'}</div>
+   *   )}
+   * </throttler.Subscribe>
+   */
+  Subscribe: <TSelected>(props: {
+    selector: (state: AsyncThrottlerState<TFn>) => TSelected
+    children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+  }) => ComponentChildren
   /**
    * Reactive state that will be updated and re-rendered when the throttler state changes
    *
@@ -50,14 +68,24 @@ export interface ReactAsyncThrottler<
  *
  * ## 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` HOC (Recommended for component tree subscriptions)**
+ *
+ * Use the `Subscribe` HOC 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 a re-render
+ * at the hook level, 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.
+ * tracking by providing a selector function or using the `Subscribe` HOC. This prevents unnecessary
+ * re-renders and gives you full control over when your component updates.
  *
  * Available state properties:
  * - `errorCount`: Number of function executions that have resulted in errors
@@ -82,7 +110,14 @@ export interface ReactAsyncThrottler<
  *   { wait: 1000 }
  * );
  *
- * // Opt-in to re-render when execution state changes (optimized for loading indicators)
+ * // Subscribe to state changes deep in component tree using Subscribe HOC
+ * <asyncThrottler.Subscribe selector={(state) => ({ isPending: state.isPending })}>
+ *   {({ isPending }) => (
+ *     <div>{isPending ? 'Processing...' : 'Ready'}</div>
+ *   )}
+ * </asyncThrottler.Subscribe>
+ *
+ * // Opt-in to re-render when execution state changes at hook level (optimized for loading indicators)
  * const asyncThrottler = useAsyncThrottler(
  *   async (id: string) => {
  *     const data = await api.fetchData(id);
@@ -163,15 +198,31 @@ export function useAsyncThrottler<TFn extends AnyAsyncFunction, TSelected = {}>(
   options: AsyncThrottlerOptions<TFn>,
   selector: (state: AsyncThrottlerState<TFn>) => TSelected = () =>
     ({}) as TSelected,
-): ReactAsyncThrottler<TFn, TSelected> {
+): PreactAsyncThrottler<TFn, TSelected> {
   const mergedOptions = {
     ...useDefaultPacerOptions().asyncThrottler,
     ...options,
   } as AsyncThrottlerOptions<TFn>
 
-  const [asyncThrottler] = useState(
-    () => new AsyncThrottler<TFn>(fn, mergedOptions),
-  )
+  const [asyncThrottler] = useState(() => {
+    const throttlerInstance = new AsyncThrottler<TFn>(
+      fn,
+      mergedOptions,
+    ) as unknown as PreactAsyncThrottler<TFn, TSelected>
+
+    throttlerInstance.Subscribe = function Subscribe<TSelected>(props: {
+      selector: (state: AsyncThrottlerState<TFn>) => TSelected
+      children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+    }) {
+      const selected = useStore(throttlerInstance.store, props.selector)
+
+      return typeof props.children === 'function'
+        ? props.children(selected)
+        : props.children
+    }
+
+    return throttlerInstance
+  })
 
   asyncThrottler.fn = fn
   asyncThrottler.setOptions(mergedOptions)
@@ -187,7 +238,7 @@ export function useAsyncThrottler<TFn extends AnyAsyncFunction, TSelected = {}>(
       ({
         ...asyncThrottler,
         state,
-      }) as ReactAsyncThrottler<TFn, TSelected>, // omit `store` in favor of `state`
+      }) as PreactAsyncThrottler<TFn, TSelected>, // omit `store` in favor of `state`
     [asyncThrottler, state],
   )
 }

package/src/batcher/useBatcher.ts

@@ -4,11 +4,29 @@ import { useStore } from '@tanstack/preact-store'
 import { useDefaultPacerOptions } from '../provider/PacerProvider'
 import type { Store } from '@tanstack/preact-store'
 import type { BatcherOptions, BatcherState } from '@tanstack/pacer/batcher'
+import type { ComponentChildren } from 'preact'
 
 export interface PreactBatcher<TValue, TSelected = {}> extends Omit<
   Batcher<TValue>,
   'store'
 > {
+  /**
+   * A Preact HOC (Higher Order Component) that allows you to subscribe to the batcher state.
+   *
+   * This is useful for opting into state re-renders for specific parts of the batcher state
+   * deep in your component tree without needing to pass a selector to the hook.
+   *
+   * @example
+   * <batcher.Subscribe selector={(state) => ({ size: state.size })}>
+   *   {({ size }) => (
+   *     <div>Batch Size: {size}</div>
+   *   )}
+   * </batcher.Subscribe>
+   */
+  Subscribe: <TSelected>(props: {
+    selector: (state: BatcherState<TValue>) => TSelected
+    children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+  }) => ComponentChildren
   /**
    * Reactive state that will be updated and re-rendered when the batcher state changes
    *
@@ -37,14 +55,24 @@ export interface PreactBatcher<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 `batcher.Subscribe` HOC (Recommended for component tree subscriptions)**
+ *
+ * Use the `Subscribe` HOC 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 a re-render
+ * at the hook level, 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.
+ * tracking by providing a selector function or using the `Subscribe` HOC. This prevents unnecessary
+ * re-renders and gives you full control over when your component updates.
  *
  * Available state properties:
  * - `executionCount`: Number of batch executions that have been completed
@@ -64,7 +92,14 @@ export interface PreactBatcher<TValue, TSelected = {}> extends Omit<
  *   { maxSize: 5, wait: 2000 }
  * );
  *
- * // Opt-in to re-render when batch size changes (optimized for displaying queue size)
+ * // Subscribe to state changes deep in component tree using Subscribe HOC
+ * <batcher.Subscribe selector={(state) => ({ size: state.size })}>
+ *   {({ size }) => (
+ *     <div>Batch Size: {size}</div>
+ *   )}
+ * </batcher.Subscribe>
+ *
+ * // Opt-in to re-render when batch size changes at hook level (optimized for displaying queue size)
  * const batcher = useBatcher<number>(
  *   (items) => console.log('Processing batch:', items),
  *   { maxSize: 5, wait: 2000 },
@@ -132,7 +167,25 @@ export function useBatcher<TValue, TSelected = {}>(
     ...options,
   } as BatcherOptions<TValue>
 
-  const [batcher] = useState(() => new Batcher<TValue>(fn, mergedOptions))
+  const [batcher] = useState(() => {
+    const batcherInstance = new Batcher<TValue>(
+      fn,
+      mergedOptions,
+    ) as unknown as PreactBatcher<TValue, TSelected>
+
+    batcherInstance.Subscribe = function Subscribe<TSelected>(props: {
+      selector: (state: BatcherState<TValue>) => TSelected
+      children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+    }) {
+      const selected = useStore(batcherInstance.store, props.selector)
+
+      return typeof props.children === 'function'
+        ? props.children(selected)
+        : props.children
+    }
+
+    return batcherInstance
+  })
 
   batcher.fn = fn
   batcher.setOptions(mergedOptions)

package/src/debouncer/useDebouncer.ts

@@ -8,11 +8,29 @@ import type {
   DebouncerState,
 } from '@tanstack/pacer/debouncer'
 import type { AnyFunction } from '@tanstack/pacer/types'
+import type { ComponentChildren } from 'preact'
 
 export interface PreactDebouncer<
   TFn extends AnyFunction,
   TSelected = {},
 > extends Omit<Debouncer<TFn>, 'store'> {
+  /**
+   * A Preact HOC (Higher Order Component) that allows you to subscribe to the debouncer state.
+   *
+   * This is useful for opting into state re-renders for specific parts of the debouncer state
+   * deep in your component tree without needing to pass a selector to the hook.
+   *
+   * @example
+   * <debouncer.Subscribe selector={(state) => ({ isPending: state.isPending })}>
+   *   {({ isPending }) => (
+   *     <div>{isPending ? 'Loading...' : 'Ready'}</div>
+   *   )}
+   * </debouncer.Subscribe>
+   */
+  Subscribe: <TSelected>(props: {
+    selector: (state: DebouncerState<TFn>) => TSelected
+    children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+  }) => ComponentChildren
   /**
    * Reactive state that will be updated and re-rendered when the debouncer state changes
    *
@@ -44,14 +62,24 @@ export interface PreactDebouncer<
  *
  * ## 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 `debouncer.Subscribe` HOC (Recommended for component tree subscriptions)**
+ *
+ * Use the `Subscribe` HOC 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 a re-render
+ * at the hook level, 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.
+ * tracking by providing a selector function or using the `Subscribe` HOC. This prevents unnecessary
+ * re-renders and gives you full control over when your component updates.
  *
  * Available state properties:
  * - `canLeadingExecute`: Whether the debouncer can execute on the leading edge
@@ -68,7 +96,14 @@ export interface PreactDebouncer<
  *   { wait: 500 }
  * );
  *
- * // Opt-in to re-render when isPending changes (optimized for loading states)
+ * // Subscribe to state changes deep in component tree using Subscribe HOC
+ * <searchDebouncer.Subscribe selector={(state) => ({ isPending: state.isPending })}>
+ *   {({ isPending }) => (
+ *     <div>{isPending ? 'Searching...' : 'Ready'}</div>
+ *   )}
+ * </searchDebouncer.Subscribe>
+ *
+ * // Opt-in to re-render when isPending changes at hook level (optimized for loading states)
  * const searchDebouncer = useDebouncer(
  *   (query: string) => fetchSearchResults(query),
  *   { wait: 500 },
@@ -112,7 +147,25 @@ export function useDebouncer<TFn extends AnyFunction, TSelected = {}>(
     ...options,
   } as DebouncerOptions<TFn>
 
-  const [debouncer] = useState(() => new Debouncer(fn, mergedOptions))
+  const [debouncer] = useState(() => {
+    const debouncerInstance = new Debouncer(
+      fn,
+      mergedOptions,
+    ) as unknown as PreactDebouncer<TFn, TSelected>
+
+    debouncerInstance.Subscribe = function Subscribe<TSelected>(props: {
+      selector: (state: DebouncerState<TFn>) => TSelected
+      children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+    }) {
+      const selected = useStore(debouncerInstance.store, props.selector)
+
+      return typeof props.children === 'function'
+        ? props.children(selected)
+        : props.children
+    }
+
+    return debouncerInstance
+  })
 
   debouncer.fn = fn
   debouncer.setOptions(mergedOptions)

package/src/queuer/useQueuer.ts

@@ -4,11 +4,29 @@ import { useStore } from '@tanstack/preact-store'
 import { useDefaultPacerOptions } from '../provider/PacerProvider'
 import type { Store } from '@tanstack/preact-store'
 import type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
+import type { ComponentChildren } from 'preact'
 
 export interface PreactQueuer<TValue, TSelected = {}> extends Omit<
   Queuer<TValue>,
   'store'
 > {
+  /**
+   * A Preact HOC (Higher Order Component) that allows you to subscribe to the queuer state.
+   *
+   * This is useful for opting into state re-renders for 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 })}>
+   *   {({ size }) => (
+   *     <div>Queue Size: {size}</div>
+   *   )}
+   * </queuer.Subscribe>
+   */
+  Subscribe: <TSelected>(props: {
+    selector: (state: QueuerState<TValue>) => TSelected
+    children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+  }) => ComponentChildren
   /**
    * Reactive state that will be updated and re-rendered when the queuer state changes
    *
@@ -42,14 +60,24 @@ export interface PreactQueuer<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` HOC (Recommended for component tree subscriptions)**
+ *
+ * Use the `Subscribe` HOC 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 a re-render
+ * at the hook level, 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.
+ * tracking by providing a selector function or using the `Subscribe` HOC. This prevents unnecessary
+ * re-renders and gives you full control over when your component updates.
  *
  * Available state properties:
  * - `executionCount`: Number of items that have been processed by the queuer
@@ -73,7 +101,14 @@ export interface PreactQueuer<TValue, TSelected = {}> extends Omit<
  *   { started: true, wait: 1000 }
  * );
  *
- * // Opt-in to re-render when queue size changes (optimized for displaying queue length)
+ * // Subscribe to state changes deep in component tree using Subscribe HOC
+ * <queue.Subscribe selector={(state) => ({ size: state.size })}>
+ *   {({ size }) => (
+ *     <div>Queue Size: {size}</div>
+ *   )}
+ * </queue.Subscribe>
+ *
+ * // Opt-in to re-render when queue size changes at hook level (optimized for displaying queue length)
  * const queue = useQueuer(
  *   (item) => console.log('Processing:', item),
  *   { started: true, wait: 1000 },
@@ -142,7 +177,25 @@ export function useQueuer<TValue, TSelected = {}>(
     ...options,
   } as QueuerOptions<TValue>
 
-  const [queuer] = useState(() => new Queuer<TValue>(fn, mergedOptions))
+  const [queuer] = useState(() => {
+    const queuerInstance = new Queuer<TValue>(
+      fn,
+      mergedOptions,
+    ) as unknown as PreactQueuer<TValue, TSelected>
+
+    queuerInstance.Subscribe = function Subscribe<TSelected>(props: {
+      selector: (state: QueuerState<TValue>) => TSelected
+      children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+    }) {
+      const selected = useStore(queuerInstance.store, props.selector)
+
+      return typeof props.children === 'function'
+        ? props.children(selected)
+        : props.children
+    }
+
+    return queuerInstance
+  })
 
   queuer.fn = fn
   queuer.setOptions(mergedOptions)