@tanstack/preact-pacer 0.19.4 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (199) hide show
  1. package/README.md +6 -6
  2. package/dist/async-batcher/index.cjs +1 -0
  3. package/dist/async-batcher/index.d.cts +2 -2
  4. package/dist/async-batcher/index.d.ts +2 -2
  5. package/dist/async-batcher/useAsyncBatchedCallback.cjs +2 -2
  6. package/dist/async-batcher/useAsyncBatchedCallback.cjs.map +1 -1
  7. package/dist/async-batcher/useAsyncBatchedCallback.d.cts +2 -3
  8. package/dist/async-batcher/useAsyncBatchedCallback.d.ts +2 -3
  9. package/dist/async-batcher/useAsyncBatchedCallback.js +2 -2
  10. package/dist/async-batcher/useAsyncBatchedCallback.js.map +1 -1
  11. package/dist/async-batcher/useAsyncBatcher.cjs +30 -2
  12. package/dist/async-batcher/useAsyncBatcher.cjs.map +1 -1
  13. package/dist/async-batcher/useAsyncBatcher.d.cts +28 -2
  14. package/dist/async-batcher/useAsyncBatcher.d.ts +28 -2
  15. package/dist/async-batcher/useAsyncBatcher.js +32 -4
  16. package/dist/async-batcher/useAsyncBatcher.js.map +1 -1
  17. package/dist/async-debouncer/index.cjs +1 -0
  18. package/dist/async-debouncer/index.d.cts +2 -2
  19. package/dist/async-debouncer/index.d.ts +2 -2
  20. package/dist/async-debouncer/useAsyncDebouncedCallback.cjs.map +1 -1
  21. package/dist/async-debouncer/useAsyncDebouncedCallback.d.cts +2 -2
  22. package/dist/async-debouncer/useAsyncDebouncedCallback.d.ts +2 -2
  23. package/dist/async-debouncer/useAsyncDebouncedCallback.js.map +1 -1
  24. package/dist/async-debouncer/useAsyncDebouncer.cjs +26 -4
  25. package/dist/async-debouncer/useAsyncDebouncer.cjs.map +1 -1
  26. package/dist/async-debouncer/useAsyncDebouncer.d.cts +28 -3
  27. package/dist/async-debouncer/useAsyncDebouncer.d.ts +27 -2
  28. package/dist/async-debouncer/useAsyncDebouncer.js +27 -5
  29. package/dist/async-debouncer/useAsyncDebouncer.js.map +1 -1
  30. package/dist/async-queuer/index.cjs +1 -0
  31. package/dist/async-queuer/index.d.cts +2 -2
  32. package/dist/async-queuer/index.d.ts +2 -2
  33. package/dist/async-queuer/useAsyncQueuedState.cjs.map +1 -1
  34. package/dist/async-queuer/useAsyncQueuedState.d.cts +3 -3
  35. package/dist/async-queuer/useAsyncQueuedState.d.ts +3 -3
  36. package/dist/async-queuer/useAsyncQueuedState.js.map +1 -1
  37. package/dist/async-queuer/useAsyncQueuer.cjs +30 -2
  38. package/dist/async-queuer/useAsyncQueuer.cjs.map +1 -1
  39. package/dist/async-queuer/useAsyncQueuer.d.cts +28 -2
  40. package/dist/async-queuer/useAsyncQueuer.d.ts +28 -2
  41. package/dist/async-queuer/useAsyncQueuer.js +32 -4
  42. package/dist/async-queuer/useAsyncQueuer.js.map +1 -1
  43. package/dist/async-rate-limiter/index.cjs +1 -0
  44. package/dist/async-rate-limiter/index.d.cts +2 -2
  45. package/dist/async-rate-limiter/index.d.ts +2 -2
  46. package/dist/async-rate-limiter/useAsyncRateLimitedCallback.cjs.map +1 -1
  47. package/dist/async-rate-limiter/useAsyncRateLimitedCallback.d.cts +2 -2
  48. package/dist/async-rate-limiter/useAsyncRateLimitedCallback.d.ts +2 -2
  49. package/dist/async-rate-limiter/useAsyncRateLimitedCallback.js.map +1 -1
  50. package/dist/async-rate-limiter/useAsyncRateLimiter.cjs +14 -2
  51. package/dist/async-rate-limiter/useAsyncRateLimiter.cjs.map +1 -1
  52. package/dist/async-rate-limiter/useAsyncRateLimiter.d.cts +15 -2
  53. package/dist/async-rate-limiter/useAsyncRateLimiter.d.ts +15 -2
  54. package/dist/async-rate-limiter/useAsyncRateLimiter.js +16 -4
  55. package/dist/async-rate-limiter/useAsyncRateLimiter.js.map +1 -1
  56. package/dist/async-throttler/index.cjs +1 -0
  57. package/dist/async-throttler/index.d.cts +2 -2
  58. package/dist/async-throttler/index.d.ts +2 -2
  59. package/dist/async-throttler/useAsyncThrottledCallback.cjs.map +1 -1
  60. package/dist/async-throttler/useAsyncThrottledCallback.d.cts +2 -2
  61. package/dist/async-throttler/useAsyncThrottledCallback.d.ts +2 -2
  62. package/dist/async-throttler/useAsyncThrottledCallback.js.map +1 -1
  63. package/dist/async-throttler/useAsyncThrottler.cjs +28 -4
  64. package/dist/async-throttler/useAsyncThrottler.cjs.map +1 -1
  65. package/dist/async-throttler/useAsyncThrottler.d.cts +27 -2
  66. package/dist/async-throttler/useAsyncThrottler.d.ts +27 -2
  67. package/dist/async-throttler/useAsyncThrottler.js +29 -5
  68. package/dist/async-throttler/useAsyncThrottler.js.map +1 -1
  69. package/dist/batcher/index.cjs +1 -0
  70. package/dist/batcher/index.d.cts +2 -2
  71. package/dist/batcher/index.d.ts +2 -2
  72. package/dist/batcher/useBatchedCallback.cjs +1 -1
  73. package/dist/batcher/useBatchedCallback.cjs.map +1 -1
  74. package/dist/batcher/useBatchedCallback.d.cts +2 -3
  75. package/dist/batcher/useBatchedCallback.d.ts +2 -3
  76. package/dist/batcher/useBatchedCallback.js +1 -1
  77. package/dist/batcher/useBatchedCallback.js.map +1 -1
  78. package/dist/batcher/useBatcher.cjs +21 -2
  79. package/dist/batcher/useBatcher.cjs.map +1 -1
  80. package/dist/batcher/useBatcher.d.cts +22 -2
  81. package/dist/batcher/useBatcher.d.ts +22 -2
  82. package/dist/batcher/useBatcher.js +23 -4
  83. package/dist/batcher/useBatcher.js.map +1 -1
  84. package/dist/debouncer/index.cjs +1 -0
  85. package/dist/debouncer/index.d.cts +2 -2
  86. package/dist/debouncer/index.d.ts +2 -2
  87. package/dist/debouncer/useDebouncedCallback.cjs.map +1 -1
  88. package/dist/debouncer/useDebouncedCallback.d.cts +2 -2
  89. package/dist/debouncer/useDebouncedCallback.d.ts +2 -2
  90. package/dist/debouncer/useDebouncedCallback.js.map +1 -1
  91. package/dist/debouncer/useDebouncedState.cjs.map +1 -1
  92. package/dist/debouncer/useDebouncedState.d.cts +3 -3
  93. package/dist/debouncer/useDebouncedState.d.ts +3 -3
  94. package/dist/debouncer/useDebouncedState.js.map +1 -1
  95. package/dist/debouncer/useDebouncedValue.cjs.map +1 -1
  96. package/dist/debouncer/useDebouncedValue.d.cts +3 -3
  97. package/dist/debouncer/useDebouncedValue.d.ts +3 -3
  98. package/dist/debouncer/useDebouncedValue.js.map +1 -1
  99. package/dist/debouncer/useDebouncer.cjs +17 -4
  100. package/dist/debouncer/useDebouncer.cjs.map +1 -1
  101. package/dist/debouncer/useDebouncer.d.cts +21 -2
  102. package/dist/debouncer/useDebouncer.d.ts +21 -2
  103. package/dist/debouncer/useDebouncer.js +18 -5
  104. package/dist/debouncer/useDebouncer.js.map +1 -1
  105. package/dist/index.cjs +1 -0
  106. package/dist/index.d.cts +11 -11
  107. package/dist/index.d.ts +11 -11
  108. package/dist/provider/PacerProvider.cjs.map +1 -1
  109. package/dist/provider/PacerProvider.d.cts +2 -2
  110. package/dist/provider/PacerProvider.d.ts +2 -2
  111. package/dist/provider/PacerProvider.js.map +1 -1
  112. package/dist/provider/index.cjs +1 -0
  113. package/dist/queuer/index.cjs +1 -0
  114. package/dist/queuer/index.d.cts +2 -2
  115. package/dist/queuer/index.d.ts +2 -2
  116. package/dist/queuer/useQueuedState.cjs.map +1 -1
  117. package/dist/queuer/useQueuedState.d.cts +3 -3
  118. package/dist/queuer/useQueuedState.d.ts +3 -3
  119. package/dist/queuer/useQueuedState.js.map +1 -1
  120. package/dist/queuer/useQueuedValue.cjs.map +1 -1
  121. package/dist/queuer/useQueuedValue.d.cts +3 -3
  122. package/dist/queuer/useQueuedValue.d.ts +3 -3
  123. package/dist/queuer/useQueuedValue.js.map +1 -1
  124. package/dist/queuer/useQueuer.cjs +21 -2
  125. package/dist/queuer/useQueuer.cjs.map +1 -1
  126. package/dist/queuer/useQueuer.d.cts +22 -2
  127. package/dist/queuer/useQueuer.d.ts +22 -2
  128. package/dist/queuer/useQueuer.js +23 -4
  129. package/dist/queuer/useQueuer.js.map +1 -1
  130. package/dist/rate-limiter/index.cjs +1 -0
  131. package/dist/rate-limiter/index.d.cts +2 -2
  132. package/dist/rate-limiter/index.d.ts +2 -2
  133. package/dist/rate-limiter/useRateLimitedCallback.cjs.map +1 -1
  134. package/dist/rate-limiter/useRateLimitedCallback.d.cts +2 -2
  135. package/dist/rate-limiter/useRateLimitedCallback.d.ts +2 -2
  136. package/dist/rate-limiter/useRateLimitedCallback.js.map +1 -1
  137. package/dist/rate-limiter/useRateLimitedState.cjs.map +1 -1
  138. package/dist/rate-limiter/useRateLimitedState.d.cts +3 -3
  139. package/dist/rate-limiter/useRateLimitedState.d.ts +3 -3
  140. package/dist/rate-limiter/useRateLimitedState.js.map +1 -1
  141. package/dist/rate-limiter/useRateLimitedValue.cjs.map +1 -1
  142. package/dist/rate-limiter/useRateLimitedValue.d.cts +3 -3
  143. package/dist/rate-limiter/useRateLimitedValue.d.ts +3 -3
  144. package/dist/rate-limiter/useRateLimitedValue.js.map +1 -1
  145. package/dist/rate-limiter/useRateLimiter.cjs +7 -2
  146. package/dist/rate-limiter/useRateLimiter.cjs.map +1 -1
  147. package/dist/rate-limiter/useRateLimiter.d.cts +9 -2
  148. package/dist/rate-limiter/useRateLimiter.d.ts +9 -2
  149. package/dist/rate-limiter/useRateLimiter.js +9 -4
  150. package/dist/rate-limiter/useRateLimiter.js.map +1 -1
  151. package/dist/throttler/index.cjs +1 -0
  152. package/dist/throttler/index.d.cts +2 -2
  153. package/dist/throttler/index.d.ts +2 -2
  154. package/dist/throttler/useThrottledCallback.cjs.map +1 -1
  155. package/dist/throttler/useThrottledCallback.d.cts +2 -2
  156. package/dist/throttler/useThrottledCallback.d.ts +2 -2
  157. package/dist/throttler/useThrottledCallback.js.map +1 -1
  158. package/dist/throttler/useThrottledState.cjs.map +1 -1
  159. package/dist/throttler/useThrottledState.d.cts +3 -3
  160. package/dist/throttler/useThrottledState.d.ts +3 -3
  161. package/dist/throttler/useThrottledState.js.map +1 -1
  162. package/dist/throttler/useThrottledValue.cjs.map +1 -1
  163. package/dist/throttler/useThrottledValue.d.cts +3 -3
  164. package/dist/throttler/useThrottledValue.d.ts +3 -3
  165. package/dist/throttler/useThrottledValue.js.map +1 -1
  166. package/dist/throttler/useThrottler.cjs +17 -4
  167. package/dist/throttler/useThrottler.cjs.map +1 -1
  168. package/dist/throttler/useThrottler.d.cts +21 -2
  169. package/dist/throttler/useThrottler.d.ts +21 -2
  170. package/dist/throttler/useThrottler.js +18 -5
  171. package/dist/throttler/useThrottler.js.map +1 -1
  172. package/package.json +36 -35
  173. package/src/async-batcher/useAsyncBatchedCallback.ts +7 -8
  174. package/src/async-batcher/useAsyncBatcher.ts +51 -7
  175. package/src/async-debouncer/useAsyncDebouncedCallback.ts +2 -2
  176. package/src/async-debouncer/useAsyncDebouncer.ts +45 -8
  177. package/src/async-queuer/useAsyncQueuedState.ts +5 -5
  178. package/src/async-queuer/useAsyncQueuer.ts +51 -7
  179. package/src/async-rate-limiter/useAsyncRateLimitedCallback.ts +2 -2
  180. package/src/async-rate-limiter/useAsyncRateLimiter.ts +37 -6
  181. package/src/async-throttler/useAsyncThrottledCallback.ts +2 -2
  182. package/src/async-throttler/useAsyncThrottler.ts +47 -8
  183. package/src/batcher/useBatchedCallback.ts +6 -10
  184. package/src/batcher/useBatcher.ts +44 -6
  185. package/src/debouncer/useDebouncedCallback.ts +2 -2
  186. package/src/debouncer/useDebouncedState.ts +3 -6
  187. package/src/debouncer/useDebouncedValue.ts +3 -6
  188. package/src/debouncer/useDebouncer.ts +38 -8
  189. package/src/queuer/useQueuedState.ts +3 -3
  190. package/src/queuer/useQueuedValue.ts +3 -3
  191. package/src/queuer/useQueuer.ts +44 -6
  192. package/src/rate-limiter/useRateLimitedCallback.ts +2 -2
  193. package/src/rate-limiter/useRateLimitedState.ts +6 -6
  194. package/src/rate-limiter/useRateLimitedValue.ts +6 -6
  195. package/src/rate-limiter/useRateLimiter.ts +29 -7
  196. package/src/throttler/useThrottledCallback.ts +2 -2
  197. package/src/throttler/useThrottledState.ts +3 -6
  198. package/src/throttler/useThrottledValue.ts +3 -6
  199. package/src/throttler/useThrottler.ts +38 -8
@@ -1,6 +1,6 @@
1
1
  import { useDefaultPacerOptions } from "../provider/PacerProvider.js";
2
2
  import { useEffect, useMemo, useState } from "preact/hooks";
3
- import { useStore } from "@tanstack/preact-store";
3
+ import { shallow, useStore } from "@tanstack/preact-store";
4
4
  import { Debouncer } from "@tanstack/pacer/debouncer";
5
5
 
6
6
  //#region src/debouncer/useDebouncer.ts
@@ -47,6 +47,18 @@ import { Debouncer } from "@tanstack/pacer/debouncer";
47
47
  * - `lastArgs`: The arguments from the most recent call to maybeExecute
48
48
  * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
49
49
  *
50
+ * ## Unmount behavior
51
+ *
52
+ * By default, the hook cancels any pending execution when the component unmounts.
53
+ * Use the `onUnmount` option to customize this. For example, to flush pending work instead:
54
+ *
55
+ * ```tsx
56
+ * const debouncer = useDebouncer(fn, {
57
+ * wait: 500,
58
+ * onUnmount: (d) => d.flush()
59
+ * });
60
+ * ```
61
+ *
50
62
  * @example
51
63
  * ```tsx
52
64
  * // Default behavior - no reactive state subscriptions
@@ -104,7 +116,7 @@ function useDebouncer(fn, options, selector = () => ({})) {
104
116
  const [debouncer] = useState(() => {
105
117
  const debouncerInstance = new Debouncer(fn, mergedOptions);
106
118
  debouncerInstance.Subscribe = function Subscribe(props) {
107
- const selected = useStore(debouncerInstance.store, props.selector);
119
+ const selected = useStore(debouncerInstance.store, props.selector, { equal: shallow });
108
120
  return typeof props.children === "function" ? props.children(selected) : props.children;
109
121
  };
110
122
  return debouncerInstance;
@@ -113,10 +125,11 @@ function useDebouncer(fn, options, selector = () => ({})) {
113
125
  debouncer.setOptions(mergedOptions);
114
126
  useEffect(() => {
115
127
  return () => {
116
- debouncer.cancel();
128
+ if (mergedOptions.onUnmount) mergedOptions.onUnmount(debouncer);
129
+ else debouncer.cancel();
117
130
  };
118
- }, [debouncer]);
119
- const state = useStore(debouncer.store, selector);
131
+ }, []);
132
+ const state = useStore(debouncer.store, selector, { equal: shallow });
120
133
  return useMemo(() => ({
121
134
  ...debouncer,
122
135
  state
@@ -1 +1 @@
1
- {"version":3,"file":"useDebouncer.js","names":[],"sources":["../../src/debouncer/useDebouncer.ts"],"sourcesContent":["import { useEffect, useMemo, useState } from 'preact/hooks'\nimport { Debouncer } from '@tanstack/pacer/debouncer'\nimport { useStore } from '@tanstack/preact-store'\nimport { useDefaultPacerOptions } from '../provider/PacerProvider'\nimport type { Store } from '@tanstack/preact-store'\nimport type {\n DebouncerOptions,\n DebouncerState,\n} from '@tanstack/pacer/debouncer'\nimport type { AnyFunction } from '@tanstack/pacer/types'\nimport type { ComponentChildren } from 'preact'\n\nexport interface PreactDebouncer<\n TFn extends AnyFunction,\n TSelected = {},\n> extends Omit<Debouncer<TFn>, 'store'> {\n /**\n * A Preact HOC (Higher Order Component) that allows you to subscribe to the debouncer state.\n *\n * This is useful for opting into state re-renders for specific parts of the debouncer state\n * deep in your component tree without needing to pass a selector to the hook.\n *\n * @example\n * <debouncer.Subscribe selector={(state) => ({ isPending: state.isPending })}>\n * {({ isPending }) => (\n * <div>{isPending ? 'Loading...' : 'Ready'}</div>\n * )}\n * </debouncer.Subscribe>\n */\n Subscribe: <TSelected>(props: {\n selector: (state: DebouncerState<TFn>) => TSelected\n children: ((state: TSelected) => ComponentChildren) | ComponentChildren\n }) => ComponentChildren\n /**\n * Reactive state that will be updated and re-rendered when the debouncer state changes\n *\n * Use this instead of `debouncer.store.state`\n */\n readonly state: Readonly<TSelected>\n /**\n * @deprecated Use `debouncer.state` instead of `debouncer.store.state` if you want to read reactive state.\n * The state on the store object is not reactive, as it has not been wrapped in a `useStore` hook internally.\n * Although, you can make the state reactive by using the `useStore` in your own usage.\n */\n readonly store: Store<Readonly<DebouncerState<TFn>>>\n}\n\n/**\n * A Preact hook that creates and manages a Debouncer instance.\n *\n * This is a lower-level hook that provides direct access to the Debouncer's functionality without\n * any built-in state management. This allows you to integrate it with any state management solution\n * you prefer (useState, Redux, Zustand, etc.).\n *\n * This hook provides debouncing functionality to limit how often a function can be called,\n * waiting for a specified delay before executing the latest call. This is useful for handling\n * frequent events like window resizing, scroll events, or real-time search inputs.\n *\n * The debouncer will only execute the function after the specified wait time has elapsed\n * since the last call. If the function is called again before the wait time expires, the\n * timer resets and starts waiting again.\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management. You can subscribe to state changes\n * in two ways:\n *\n * **1. Using `debouncer.Subscribe` HOC (Recommended for component tree subscriptions)**\n *\n * Use the `Subscribe` HOC to subscribe to state changes deep in your component tree without\n * needing to pass a selector to the hook. This is ideal when you want to subscribe to state\n * in child components.\n *\n * **2. Using the `selector` parameter (For hook-level subscriptions)**\n *\n * The `selector` parameter allows you to specify which state changes will trigger a re-render\n * at the hook level, optimizing performance by preventing unnecessary re-renders when irrelevant\n * state changes occur.\n *\n * **By default, there will be no reactive state subscriptions** and you must opt-in to state\n * tracking by providing a selector function or using the `Subscribe` HOC. This prevents unnecessary\n * re-renders and gives you full control over when your component updates.\n *\n * Available state properties:\n * - `canLeadingExecute`: Whether the debouncer can execute on the leading edge\n * - `executionCount`: Number of function executions that have been completed\n * - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution\n * - `lastArgs`: The arguments from the most recent call to maybeExecute\n * - `status`: Current execution status ('disabled' | 'idle' | 'pending')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const searchDebouncer = useDebouncer(\n * (query: string) => fetchSearchResults(query),\n * { wait: 500 }\n * );\n *\n * // Subscribe to state changes deep in component tree using Subscribe HOC\n * <searchDebouncer.Subscribe selector={(state) => ({ isPending: state.isPending })}>\n * {({ isPending }) => (\n * <div>{isPending ? 'Searching...' : 'Ready'}</div>\n * )}\n * </searchDebouncer.Subscribe>\n *\n * // Opt-in to re-render when isPending changes at hook level (optimized for loading states)\n * const searchDebouncer = useDebouncer(\n * (query: string) => fetchSearchResults(query),\n * { wait: 500 },\n * (state) => ({ isPending: state.isPending })\n * );\n *\n * // Opt-in to re-render when executionCount changes (optimized for tracking execution)\n * const searchDebouncer = useDebouncer(\n * (query: string) => fetchSearchResults(query),\n * { wait: 500 },\n * (state) => ({ executionCount: state.executionCount })\n * );\n *\n * // Multiple state properties - re-render when any of these change\n * const searchDebouncer = useDebouncer(\n * (query: string) => fetchSearchResults(query),\n * { wait: 500 },\n * (state) => ({\n * isPending: state.isPending,\n * executionCount: state.executionCount,\n * status: state.status\n * })\n * );\n *\n * // In an event handler\n * const handleChange = (e) => {\n * searchDebouncer.maybeExecute(e.target.value);\n * };\n *\n * // Access the selected state (will be empty object {} unless selector provided)\n * const { isPending } = searchDebouncer.state;\n * ```\n */\nexport function useDebouncer<TFn extends AnyFunction, TSelected = {}>(\n fn: TFn,\n options: DebouncerOptions<TFn>,\n selector: (state: DebouncerState<TFn>) => TSelected = () => ({}) as TSelected,\n): PreactDebouncer<TFn, TSelected> {\n const mergedOptions = {\n ...useDefaultPacerOptions().debouncer,\n ...options,\n } as DebouncerOptions<TFn>\n\n const [debouncer] = useState(() => {\n const debouncerInstance = new Debouncer(\n fn,\n mergedOptions,\n ) as unknown as PreactDebouncer<TFn, TSelected>\n\n debouncerInstance.Subscribe = function Subscribe<TSelected>(props: {\n selector: (state: DebouncerState<TFn>) => TSelected\n children: ((state: TSelected) => ComponentChildren) | ComponentChildren\n }) {\n const selected = useStore(debouncerInstance.store, props.selector)\n\n return typeof props.children === 'function'\n ? props.children(selected)\n : props.children\n }\n\n return debouncerInstance\n })\n\n debouncer.fn = fn\n debouncer.setOptions(mergedOptions)\n\n useEffect(() => {\n return () => {\n debouncer.cancel()\n }\n }, [debouncer])\n\n const state = useStore(debouncer.store, selector)\n\n return useMemo(\n () =>\n ({\n ...debouncer,\n state,\n }) as PreactDebouncer<TFn, TSelected>, // omit `store` in favor of `state`\n [debouncer, state],\n )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2IA,SAAgB,aACd,IACA,SACA,kBAA6D,EAAE,GAC9B;CACjC,MAAM,gBAAgB;EACpB,GAAG,wBAAwB,CAAC;EAC5B,GAAG;EACJ;CAED,MAAM,CAAC,aAAa,eAAe;EACjC,MAAM,oBAAoB,IAAI,UAC5B,IACA,cACD;AAED,oBAAkB,YAAY,SAAS,UAAqB,OAGzD;GACD,MAAM,WAAW,SAAS,kBAAkB,OAAO,MAAM,SAAS;AAElE,UAAO,OAAO,MAAM,aAAa,aAC7B,MAAM,SAAS,SAAS,GACxB,MAAM;;AAGZ,SAAO;GACP;AAEF,WAAU,KAAK;AACf,WAAU,WAAW,cAAc;AAEnC,iBAAgB;AACd,eAAa;AACX,aAAU,QAAQ;;IAEnB,CAAC,UAAU,CAAC;CAEf,MAAM,QAAQ,SAAS,UAAU,OAAO,SAAS;AAEjD,QAAO,eAEF;EACC,GAAG;EACH;EACD,GACH,CAAC,WAAW,MAAM,CACnB"}
1
+ {"version":3,"file":"useDebouncer.js","names":[],"sources":["../../src/debouncer/useDebouncer.ts"],"sourcesContent":["import { useEffect, useMemo, useState } from 'preact/hooks'\nimport { Debouncer } from '@tanstack/pacer/debouncer'\nimport { shallow, useStore } from '@tanstack/preact-store'\nimport { useDefaultPacerOptions } from '../provider/PacerProvider'\nimport type { Store } from '@tanstack/preact-store'\nimport type {\n DebouncerOptions,\n DebouncerState,\n} from '@tanstack/pacer/debouncer'\nimport type { AnyFunction } from '@tanstack/pacer/types'\nimport type { ComponentChildren } from 'preact'\n\nexport interface PreactDebouncerOptions<\n TFn extends AnyFunction,\n TSelected = {},\n> extends DebouncerOptions<TFn> {\n /**\n * Optional callback invoked when the component unmounts. Receives the debouncer instance.\n * When provided, replaces the default cleanup (cancel); use it to call flush(), reset(), cancel(), add logging, etc.\n */\n onUnmount?: (debouncer: PreactDebouncer<TFn, TSelected>) => void\n}\n\nexport interface PreactDebouncer<\n TFn extends AnyFunction,\n TSelected = {},\n> extends Omit<Debouncer<TFn>, 'store'> {\n /**\n * A Preact HOC (Higher Order Component) that allows you to subscribe to the debouncer state.\n *\n * This is useful for opting into state re-renders for specific parts of the debouncer state\n * deep in your component tree without needing to pass a selector to the hook.\n *\n * @example\n * <debouncer.Subscribe selector={(state) => ({ isPending: state.isPending })}>\n * {({ isPending }) => (\n * <div>{isPending ? 'Loading...' : 'Ready'}</div>\n * )}\n * </debouncer.Subscribe>\n */\n Subscribe: <TSelected>(props: {\n selector: (state: DebouncerState<TFn>) => TSelected\n children: ((state: TSelected) => ComponentChildren) | ComponentChildren\n }) => ComponentChildren\n /**\n * Reactive state that will be updated and re-rendered when the debouncer state changes\n *\n * Use this instead of `debouncer.store.state`\n */\n readonly state: Readonly<TSelected>\n /**\n * @deprecated Use `debouncer.state` instead of `debouncer.store.state` if you want to read reactive state.\n * The state on the store object is not reactive, as it has not been wrapped in a `useStore` hook internally.\n * Although, you can make the state reactive by using the `useStore` in your own usage.\n */\n readonly store: Store<Readonly<DebouncerState<TFn>>>\n}\n\n/**\n * A Preact hook that creates and manages a Debouncer instance.\n *\n * This is a lower-level hook that provides direct access to the Debouncer's functionality without\n * any built-in state management. This allows you to integrate it with any state management solution\n * you prefer (useState, Redux, Zustand, etc.).\n *\n * This hook provides debouncing functionality to limit how often a function can be called,\n * waiting for a specified delay before executing the latest call. This is useful for handling\n * frequent events like window resizing, scroll events, or real-time search inputs.\n *\n * The debouncer will only execute the function after the specified wait time has elapsed\n * since the last call. If the function is called again before the wait time expires, the\n * timer resets and starts waiting again.\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management. You can subscribe to state changes\n * in two ways:\n *\n * **1. Using `debouncer.Subscribe` HOC (Recommended for component tree subscriptions)**\n *\n * Use the `Subscribe` HOC to subscribe to state changes deep in your component tree without\n * needing to pass a selector to the hook. This is ideal when you want to subscribe to state\n * in child components.\n *\n * **2. Using the `selector` parameter (For hook-level subscriptions)**\n *\n * The `selector` parameter allows you to specify which state changes will trigger a re-render\n * at the hook level, optimizing performance by preventing unnecessary re-renders when irrelevant\n * state changes occur.\n *\n * **By default, there will be no reactive state subscriptions** and you must opt-in to state\n * tracking by providing a selector function or using the `Subscribe` HOC. This prevents unnecessary\n * re-renders and gives you full control over when your component updates.\n *\n * Available state properties:\n * - `canLeadingExecute`: Whether the debouncer can execute on the leading edge\n * - `executionCount`: Number of function executions that have been completed\n * - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution\n * - `lastArgs`: The arguments from the most recent call to maybeExecute\n * - `status`: Current execution status ('disabled' | 'idle' | 'pending')\n *\n * ## Unmount behavior\n *\n * By default, the hook cancels any pending execution when the component unmounts.\n * Use the `onUnmount` option to customize this. For example, to flush pending work instead:\n *\n * ```tsx\n * const debouncer = useDebouncer(fn, {\n * wait: 500,\n * onUnmount: (d) => d.flush()\n * });\n * ```\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const searchDebouncer = useDebouncer(\n * (query: string) => fetchSearchResults(query),\n * { wait: 500 }\n * );\n *\n * // Subscribe to state changes deep in component tree using Subscribe HOC\n * <searchDebouncer.Subscribe selector={(state) => ({ isPending: state.isPending })}>\n * {({ isPending }) => (\n * <div>{isPending ? 'Searching...' : 'Ready'}</div>\n * )}\n * </searchDebouncer.Subscribe>\n *\n * // Opt-in to re-render when isPending changes at hook level (optimized for loading states)\n * const searchDebouncer = useDebouncer(\n * (query: string) => fetchSearchResults(query),\n * { wait: 500 },\n * (state) => ({ isPending: state.isPending })\n * );\n *\n * // Opt-in to re-render when executionCount changes (optimized for tracking execution)\n * const searchDebouncer = useDebouncer(\n * (query: string) => fetchSearchResults(query),\n * { wait: 500 },\n * (state) => ({ executionCount: state.executionCount })\n * );\n *\n * // Multiple state properties - re-render when any of these change\n * const searchDebouncer = useDebouncer(\n * (query: string) => fetchSearchResults(query),\n * { wait: 500 },\n * (state) => ({\n * isPending: state.isPending,\n * executionCount: state.executionCount,\n * status: state.status\n * })\n * );\n *\n * // In an event handler\n * const handleChange = (e) => {\n * searchDebouncer.maybeExecute(e.target.value);\n * };\n *\n * // Access the selected state (will be empty object {} unless selector provided)\n * const { isPending } = searchDebouncer.state;\n * ```\n */\nexport function useDebouncer<TFn extends AnyFunction, TSelected = {}>(\n fn: TFn,\n options: PreactDebouncerOptions<TFn, TSelected>,\n selector: (state: DebouncerState<TFn>) => TSelected = () => ({}) as TSelected,\n): PreactDebouncer<TFn, TSelected> {\n const mergedOptions = {\n ...useDefaultPacerOptions().debouncer,\n ...options,\n } as PreactDebouncerOptions<TFn, TSelected>\n const [debouncer] = useState(() => {\n const debouncerInstance = new Debouncer(\n fn,\n mergedOptions,\n ) as unknown as PreactDebouncer<TFn, TSelected>\n\n debouncerInstance.Subscribe = function Subscribe<TSelected>(props: {\n selector: (state: DebouncerState<TFn>) => TSelected\n children: ((state: TSelected) => ComponentChildren) | ComponentChildren\n }) {\n const selected = useStore(debouncerInstance.store, props.selector, {\n equal: shallow,\n })\n\n return typeof props.children === 'function'\n ? props.children(selected)\n : props.children\n }\n\n return debouncerInstance\n })\n\n debouncer.fn = fn\n debouncer.setOptions(mergedOptions)\n\n /* eslint-disable react-hooks/exhaustive-deps -- cleanup only; runs on unmount */\n useEffect(() => {\n return () => {\n if (mergedOptions.onUnmount) {\n mergedOptions.onUnmount(debouncer)\n } else {\n debouncer.cancel()\n }\n }\n }, [])\n /* eslint-enable react-hooks/exhaustive-deps */\n\n const state = useStore(debouncer.store, selector, { equal: shallow })\n\n return useMemo(\n () =>\n ({\n ...debouncer,\n state,\n }) as PreactDebouncer<TFn, TSelected>, // omit `store` in favor of `state`\n [debouncer, state],\n )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkKA,SAAgB,aACd,IACA,SACA,kBAA6D,EAAE,GAC9B;CACjC,MAAM,gBAAgB;EACpB,GAAG,wBAAwB,CAAC;EAC5B,GAAG;EACJ;CACD,MAAM,CAAC,aAAa,eAAe;EACjC,MAAM,oBAAoB,IAAI,UAC5B,IACA,cACD;AAED,oBAAkB,YAAY,SAAS,UAAqB,OAGzD;GACD,MAAM,WAAW,SAAS,kBAAkB,OAAO,MAAM,UAAU,EACjE,OAAO,SACR,CAAC;AAEF,UAAO,OAAO,MAAM,aAAa,aAC7B,MAAM,SAAS,SAAS,GACxB,MAAM;;AAGZ,SAAO;GACP;AAEF,WAAU,KAAK;AACf,WAAU,WAAW,cAAc;AAGnC,iBAAgB;AACd,eAAa;AACX,OAAI,cAAc,UAChB,eAAc,UAAU,UAAU;OAElC,WAAU,QAAQ;;IAGrB,EAAE,CAAC;CAGN,MAAM,QAAQ,SAAS,UAAU,OAAO,UAAU,EAAE,OAAO,SAAS,CAAC;AAErE,QAAO,eAEF;EACC,GAAG;EACH;EACD,GACH,CAAC,WAAW,MAAM,CACnB"}
package/dist/index.cjs CHANGED
@@ -1,3 +1,4 @@
1
+ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
1
2
  const require_PacerProvider = require('./provider/PacerProvider.cjs');
2
3
  const require_useAsyncBatcher = require('./async-batcher/useAsyncBatcher.cjs');
3
4
  const require_useAsyncBatchedCallback = require('./async-batcher/useAsyncBatchedCallback.cjs');
package/dist/index.d.cts CHANGED
@@ -1,30 +1,30 @@
1
- import { PreactAsyncBatcher, useAsyncBatcher } from "./async-batcher/useAsyncBatcher.cjs";
1
+ import { PreactAsyncBatcher, PreactAsyncBatcherOptions, useAsyncBatcher } from "./async-batcher/useAsyncBatcher.cjs";
2
2
  import { useAsyncBatchedCallback } from "./async-batcher/useAsyncBatchedCallback.cjs";
3
- import { PreactAsyncDebouncer, useAsyncDebouncer } from "./async-debouncer/useAsyncDebouncer.cjs";
3
+ import { PreactAsyncDebouncer, PreactAsyncDebouncerOptions, useAsyncDebouncer } from "./async-debouncer/useAsyncDebouncer.cjs";
4
4
  import { useAsyncDebouncedCallback } from "./async-debouncer/useAsyncDebouncedCallback.cjs";
5
- import { PreactAsyncQueuer, useAsyncQueuer } from "./async-queuer/useAsyncQueuer.cjs";
5
+ import { PreactAsyncQueuer, PreactAsyncQueuerOptions, useAsyncQueuer } from "./async-queuer/useAsyncQueuer.cjs";
6
6
  import { useAsyncQueuedState } from "./async-queuer/useAsyncQueuedState.cjs";
7
- import { PreactAsyncRateLimiter, useAsyncRateLimiter } from "./async-rate-limiter/useAsyncRateLimiter.cjs";
7
+ import { PreactAsyncRateLimiter, PreactAsyncRateLimiterOptions, useAsyncRateLimiter } from "./async-rate-limiter/useAsyncRateLimiter.cjs";
8
8
  import { useAsyncRateLimitedCallback } from "./async-rate-limiter/useAsyncRateLimitedCallback.cjs";
9
- import { PreactAsyncThrottler, useAsyncThrottler } from "./async-throttler/useAsyncThrottler.cjs";
9
+ import { PreactAsyncThrottler, PreactAsyncThrottlerOptions, useAsyncThrottler } from "./async-throttler/useAsyncThrottler.cjs";
10
10
  import { useAsyncThrottledCallback } from "./async-throttler/useAsyncThrottledCallback.cjs";
11
- import { PreactBatcher, useBatcher } from "./batcher/useBatcher.cjs";
11
+ import { PreactBatcher, PreactBatcherOptions, useBatcher } from "./batcher/useBatcher.cjs";
12
12
  import { useBatchedCallback } from "./batcher/useBatchedCallback.cjs";
13
+ import { PreactDebouncer, PreactDebouncerOptions, useDebouncer } from "./debouncer/useDebouncer.cjs";
13
14
  import { useDebouncedCallback } from "./debouncer/useDebouncedCallback.cjs";
14
- import { PreactDebouncer, useDebouncer } from "./debouncer/useDebouncer.cjs";
15
15
  import { useDebouncedState } from "./debouncer/useDebouncedState.cjs";
16
16
  import { useDebouncedValue } from "./debouncer/useDebouncedValue.cjs";
17
17
  import { PacerProvider, PacerProviderOptions, PacerProviderProps, useDefaultPacerOptions, usePacerContext } from "./provider/PacerProvider.cjs";
18
- import { PreactQueuer, useQueuer } from "./queuer/useQueuer.cjs";
18
+ import { PreactQueuer, PreactQueuerOptions, useQueuer } from "./queuer/useQueuer.cjs";
19
19
  import { useQueuedState } from "./queuer/useQueuedState.cjs";
20
20
  import { useQueuedValue } from "./queuer/useQueuedValue.cjs";
21
+ import { PreactRateLimiter, PreactRateLimiterOptions, useRateLimiter } from "./rate-limiter/useRateLimiter.cjs";
21
22
  import { useRateLimitedCallback } from "./rate-limiter/useRateLimitedCallback.cjs";
22
- import { PreactRateLimiter, useRateLimiter } from "./rate-limiter/useRateLimiter.cjs";
23
23
  import { useRateLimitedState } from "./rate-limiter/useRateLimitedState.cjs";
24
24
  import { useRateLimitedValue } from "./rate-limiter/useRateLimitedValue.cjs";
25
+ import { PreactThrottler, PreactThrottlerOptions, useThrottler } from "./throttler/useThrottler.cjs";
25
26
  import { useThrottledCallback } from "./throttler/useThrottledCallback.cjs";
26
- import { PreactThrottler, useThrottler } from "./throttler/useThrottler.cjs";
27
27
  import { useThrottledState } from "./throttler/useThrottledState.cjs";
28
28
  import { useThrottledValue } from "./throttler/useThrottledValue.cjs";
29
29
  export * from "@tanstack/pacer";
30
- export { PacerProvider, PacerProviderOptions, PacerProviderProps, PreactAsyncBatcher, PreactAsyncDebouncer, PreactAsyncQueuer, PreactAsyncRateLimiter, PreactAsyncThrottler, PreactBatcher, PreactDebouncer, PreactQueuer, PreactRateLimiter, PreactThrottler, useAsyncBatchedCallback, useAsyncBatcher, useAsyncDebouncedCallback, useAsyncDebouncer, useAsyncQueuedState, useAsyncQueuer, useAsyncRateLimitedCallback, useAsyncRateLimiter, useAsyncThrottledCallback, useAsyncThrottler, useBatchedCallback, useBatcher, useDebouncedCallback, useDebouncedState, useDebouncedValue, useDebouncer, useDefaultPacerOptions, usePacerContext, useQueuedState, useQueuedValue, useQueuer, useRateLimitedCallback, useRateLimitedState, useRateLimitedValue, useRateLimiter, useThrottledCallback, useThrottledState, useThrottledValue, useThrottler };
30
+ export { PacerProvider, PacerProviderOptions, PacerProviderProps, PreactAsyncBatcher, PreactAsyncBatcherOptions, PreactAsyncDebouncer, PreactAsyncDebouncerOptions, PreactAsyncQueuer, PreactAsyncQueuerOptions, PreactAsyncRateLimiter, PreactAsyncRateLimiterOptions, PreactAsyncThrottler, PreactAsyncThrottlerOptions, PreactBatcher, PreactBatcherOptions, PreactDebouncer, PreactDebouncerOptions, PreactQueuer, PreactQueuerOptions, PreactRateLimiter, PreactRateLimiterOptions, PreactThrottler, PreactThrottlerOptions, useAsyncBatchedCallback, useAsyncBatcher, useAsyncDebouncedCallback, useAsyncDebouncer, useAsyncQueuedState, useAsyncQueuer, useAsyncRateLimitedCallback, useAsyncRateLimiter, useAsyncThrottledCallback, useAsyncThrottler, useBatchedCallback, useBatcher, useDebouncedCallback, useDebouncedState, useDebouncedValue, useDebouncer, useDefaultPacerOptions, usePacerContext, useQueuedState, useQueuedValue, useQueuer, useRateLimitedCallback, useRateLimitedState, useRateLimitedValue, useRateLimiter, useThrottledCallback, useThrottledState, useThrottledValue, useThrottler };
package/dist/index.d.ts CHANGED
@@ -1,30 +1,30 @@
1
- import { PreactAsyncBatcher, useAsyncBatcher } from "./async-batcher/useAsyncBatcher.js";
1
+ import { PreactAsyncBatcher, PreactAsyncBatcherOptions, useAsyncBatcher } from "./async-batcher/useAsyncBatcher.js";
2
2
  import { useAsyncBatchedCallback } from "./async-batcher/useAsyncBatchedCallback.js";
3
- import { PreactAsyncDebouncer, useAsyncDebouncer } from "./async-debouncer/useAsyncDebouncer.js";
3
+ import { PreactAsyncDebouncer, PreactAsyncDebouncerOptions, useAsyncDebouncer } from "./async-debouncer/useAsyncDebouncer.js";
4
4
  import { useAsyncDebouncedCallback } from "./async-debouncer/useAsyncDebouncedCallback.js";
5
- import { PreactAsyncQueuer, useAsyncQueuer } from "./async-queuer/useAsyncQueuer.js";
5
+ import { PreactAsyncQueuer, PreactAsyncQueuerOptions, useAsyncQueuer } from "./async-queuer/useAsyncQueuer.js";
6
6
  import { useAsyncQueuedState } from "./async-queuer/useAsyncQueuedState.js";
7
- import { PreactAsyncRateLimiter, useAsyncRateLimiter } from "./async-rate-limiter/useAsyncRateLimiter.js";
7
+ import { PreactAsyncRateLimiter, PreactAsyncRateLimiterOptions, useAsyncRateLimiter } from "./async-rate-limiter/useAsyncRateLimiter.js";
8
8
  import { useAsyncRateLimitedCallback } from "./async-rate-limiter/useAsyncRateLimitedCallback.js";
9
- import { PreactAsyncThrottler, useAsyncThrottler } from "./async-throttler/useAsyncThrottler.js";
9
+ import { PreactAsyncThrottler, PreactAsyncThrottlerOptions, useAsyncThrottler } from "./async-throttler/useAsyncThrottler.js";
10
10
  import { useAsyncThrottledCallback } from "./async-throttler/useAsyncThrottledCallback.js";
11
- import { PreactBatcher, useBatcher } from "./batcher/useBatcher.js";
11
+ import { PreactBatcher, PreactBatcherOptions, useBatcher } from "./batcher/useBatcher.js";
12
12
  import { useBatchedCallback } from "./batcher/useBatchedCallback.js";
13
+ import { PreactDebouncer, PreactDebouncerOptions, useDebouncer } from "./debouncer/useDebouncer.js";
13
14
  import { useDebouncedCallback } from "./debouncer/useDebouncedCallback.js";
14
- import { PreactDebouncer, useDebouncer } from "./debouncer/useDebouncer.js";
15
15
  import { useDebouncedState } from "./debouncer/useDebouncedState.js";
16
16
  import { useDebouncedValue } from "./debouncer/useDebouncedValue.js";
17
17
  import { PacerProvider, PacerProviderOptions, PacerProviderProps, useDefaultPacerOptions, usePacerContext } from "./provider/PacerProvider.js";
18
- import { PreactQueuer, useQueuer } from "./queuer/useQueuer.js";
18
+ import { PreactQueuer, PreactQueuerOptions, useQueuer } from "./queuer/useQueuer.js";
19
19
  import { useQueuedState } from "./queuer/useQueuedState.js";
20
20
  import { useQueuedValue } from "./queuer/useQueuedValue.js";
21
+ import { PreactRateLimiter, PreactRateLimiterOptions, useRateLimiter } from "./rate-limiter/useRateLimiter.js";
21
22
  import { useRateLimitedCallback } from "./rate-limiter/useRateLimitedCallback.js";
22
- import { PreactRateLimiter, useRateLimiter } from "./rate-limiter/useRateLimiter.js";
23
23
  import { useRateLimitedState } from "./rate-limiter/useRateLimitedState.js";
24
24
  import { useRateLimitedValue } from "./rate-limiter/useRateLimitedValue.js";
25
+ import { PreactThrottler, PreactThrottlerOptions, useThrottler } from "./throttler/useThrottler.js";
25
26
  import { useThrottledCallback } from "./throttler/useThrottledCallback.js";
26
- import { PreactThrottler, useThrottler } from "./throttler/useThrottler.js";
27
27
  import { useThrottledState } from "./throttler/useThrottledState.js";
28
28
  import { useThrottledValue } from "./throttler/useThrottledValue.js";
29
29
  export * from "@tanstack/pacer";
30
- export { PacerProvider, PacerProviderOptions, PacerProviderProps, PreactAsyncBatcher, PreactAsyncDebouncer, PreactAsyncQueuer, PreactAsyncRateLimiter, PreactAsyncThrottler, PreactBatcher, PreactDebouncer, PreactQueuer, PreactRateLimiter, PreactThrottler, useAsyncBatchedCallback, useAsyncBatcher, useAsyncDebouncedCallback, useAsyncDebouncer, useAsyncQueuedState, useAsyncQueuer, useAsyncRateLimitedCallback, useAsyncRateLimiter, useAsyncThrottledCallback, useAsyncThrottler, useBatchedCallback, useBatcher, useDebouncedCallback, useDebouncedState, useDebouncedValue, useDebouncer, useDefaultPacerOptions, usePacerContext, useQueuedState, useQueuedValue, useQueuer, useRateLimitedCallback, useRateLimitedState, useRateLimitedValue, useRateLimiter, useThrottledCallback, useThrottledState, useThrottledValue, useThrottler };
30
+ export { PacerProvider, PacerProviderOptions, PacerProviderProps, PreactAsyncBatcher, PreactAsyncBatcherOptions, PreactAsyncDebouncer, PreactAsyncDebouncerOptions, PreactAsyncQueuer, PreactAsyncQueuerOptions, PreactAsyncRateLimiter, PreactAsyncRateLimiterOptions, PreactAsyncThrottler, PreactAsyncThrottlerOptions, PreactBatcher, PreactBatcherOptions, PreactDebouncer, PreactDebouncerOptions, PreactQueuer, PreactQueuerOptions, PreactRateLimiter, PreactRateLimiterOptions, PreactThrottler, PreactThrottlerOptions, useAsyncBatchedCallback, useAsyncBatcher, useAsyncDebouncedCallback, useAsyncDebouncer, useAsyncQueuedState, useAsyncQueuer, useAsyncRateLimitedCallback, useAsyncRateLimiter, useAsyncThrottledCallback, useAsyncThrottler, useBatchedCallback, useBatcher, useDebouncedCallback, useDebouncedState, useDebouncedValue, useDebouncer, useDefaultPacerOptions, usePacerContext, useQueuedState, useQueuedValue, useQueuer, useRateLimitedCallback, useRateLimitedState, useRateLimitedValue, useRateLimiter, useThrottledCallback, useThrottledState, useThrottledValue, useThrottler };
@@ -1 +1 @@
1
- {"version":3,"file":"PacerProvider.cjs","names":[],"sources":["../../src/provider/PacerProvider.tsx"],"sourcesContent":["import { useContext, useMemo } from 'preact/hooks'\nimport { createContext } from 'preact'\nimport type { ComponentChildren } from 'preact'\nimport type {\n AnyAsyncFunction,\n AnyFunction,\n AsyncBatcherOptions,\n AsyncDebouncerOptions,\n AsyncQueuerOptions,\n AsyncRateLimiterOptions,\n AsyncThrottlerOptions,\n BatcherOptions,\n DebouncerOptions,\n QueuerOptions,\n RateLimiterOptions,\n ThrottlerOptions,\n} from '@tanstack/pacer'\n\nexport interface PacerProviderOptions {\n asyncBatcher?: Partial<AsyncBatcherOptions<any>>\n asyncDebouncer?: Partial<AsyncDebouncerOptions<AnyAsyncFunction>>\n asyncQueuer?: Partial<AsyncQueuerOptions<any>>\n asyncRateLimiter?: Partial<AsyncRateLimiterOptions<AnyAsyncFunction>>\n asyncThrottler?: Partial<AsyncThrottlerOptions<AnyAsyncFunction>>\n batcher?: Partial<BatcherOptions<any>>\n debouncer?: Partial<DebouncerOptions<AnyFunction>>\n queuer?: Partial<QueuerOptions<any>>\n rateLimiter?: Partial<RateLimiterOptions<AnyFunction>>\n throttler?: Partial<ThrottlerOptions<AnyFunction>>\n}\n\ninterface PacerContextValue {\n defaultOptions: PacerProviderOptions\n}\n\nconst PacerContext = createContext<PacerContextValue | null>(null)\n\nexport interface PacerProviderProps {\n children: ComponentChildren\n defaultOptions?: PacerProviderOptions\n}\n\nconst DEFAULT_OPTIONS: PacerProviderOptions = {}\n\nexport function PacerProvider({\n children,\n defaultOptions = DEFAULT_OPTIONS,\n}: PacerProviderProps) {\n const contextValue: PacerContextValue = useMemo(\n () => ({\n defaultOptions,\n }),\n [defaultOptions],\n )\n\n return (\n <PacerContext.Provider value={contextValue}>\n {children}\n </PacerContext.Provider>\n )\n}\n\nexport function usePacerContext() {\n return useContext(PacerContext)\n}\n\nexport function useDefaultPacerOptions() {\n const context = useContext(PacerContext)\n return context?.defaultOptions ?? {}\n}\n"],"mappings":";;;;;AAmCA,MAAM,yCAAuD,KAAK;AAOlE,MAAM,kBAAwC,EAAE;AAEhD,SAAgB,cAAc,EAC5B,UACA,iBAAiB,mBACI;CACrB,MAAM,gDACG,EACL,gBACD,GACD,CAAC,eAAe,CACjB;AAED,QACE,4CAAC,aAAa;EAAS,OAAO;EAC3B;GACqB;;AAI5B,SAAgB,kBAAkB;AAChC,qCAAkB,aAAa;;AAGjC,SAAgB,yBAAyB;AAEvC,qCAD2B,aAAa,EACxB,kBAAkB,EAAE"}
1
+ {"version":3,"file":"PacerProvider.cjs","names":[],"sources":["../../src/provider/PacerProvider.tsx"],"sourcesContent":["import { useContext, useMemo } from 'preact/hooks'\nimport { createContext } from 'preact'\nimport type { ComponentChildren } from 'preact'\nimport type {\n AnyAsyncFunction,\n AnyFunction,\n AsyncBatcherOptions,\n AsyncDebouncerOptions,\n AsyncQueuerOptions,\n AsyncRateLimiterOptions,\n AsyncThrottlerOptions,\n BatcherOptions,\n DebouncerOptions,\n QueuerOptions,\n RateLimiterOptions,\n ThrottlerOptions,\n} from '@tanstack/pacer'\n\nexport interface PacerProviderOptions {\n asyncBatcher?: Partial<AsyncBatcherOptions<any>>\n asyncDebouncer?: Partial<AsyncDebouncerOptions<AnyAsyncFunction>>\n asyncQueuer?: Partial<AsyncQueuerOptions<any>>\n asyncRateLimiter?: Partial<AsyncRateLimiterOptions<AnyAsyncFunction>>\n asyncThrottler?: Partial<AsyncThrottlerOptions<AnyAsyncFunction>>\n batcher?: Partial<BatcherOptions<any>>\n debouncer?: Partial<DebouncerOptions<AnyFunction>>\n queuer?: Partial<QueuerOptions<any>>\n rateLimiter?: Partial<RateLimiterOptions<AnyFunction>>\n throttler?: Partial<ThrottlerOptions<AnyFunction>>\n}\n\ninterface PacerContextValue {\n defaultOptions: PacerProviderOptions\n}\n\nconst PacerContext = createContext<PacerContextValue | null>(null)\n\nexport interface PacerProviderProps {\n children: ComponentChildren\n defaultOptions?: PacerProviderOptions\n}\n\nconst DEFAULT_OPTIONS: PacerProviderOptions = {}\n\nexport function PacerProvider({\n children,\n defaultOptions = DEFAULT_OPTIONS,\n}: PacerProviderProps) {\n const contextValue: PacerContextValue = useMemo(\n () => ({\n defaultOptions,\n }),\n [defaultOptions],\n )\n\n return (\n <PacerContext.Provider value={contextValue}>\n {children}\n </PacerContext.Provider>\n )\n}\n\nexport function usePacerContext() {\n return useContext(PacerContext)\n}\n\nexport function useDefaultPacerOptions() {\n const context = useContext(PacerContext)\n return context?.defaultOptions ?? {}\n}\n"],"mappings":";;;;;AAmCA,MAAM,yCAAuD,KAAK;AAOlE,MAAM,kBAAwC,EAAE;AAEhD,SAAgB,cAAc,EAC5B,UACA,iBAAiB,mBACI;CACrB,MAAM,gDACG,EACL,gBACD,GACD,CAAC,eAAe,CACjB;AAED,QACE,4CAAC,aAAa,UAAd;EAAuB,OAAO;EAC3B;EACqB;;AAI5B,SAAgB,kBAAkB;AAChC,qCAAkB,aAAa;;AAGjC,SAAgB,yBAAyB;AAEvC,qCAD2B,aAAa,EACxB,kBAAkB,EAAE"}
@@ -1,4 +1,4 @@
1
- import * as preact0 from "preact";
1
+ import * as preact from "preact";
2
2
  import { ComponentChildren } from "preact";
3
3
  import { AnyAsyncFunction, AnyFunction, AsyncBatcherOptions, AsyncDebouncerOptions, AsyncQueuerOptions, AsyncRateLimiterOptions, AsyncThrottlerOptions, BatcherOptions, DebouncerOptions, QueuerOptions, RateLimiterOptions, ThrottlerOptions } from "@tanstack/pacer";
4
4
 
@@ -25,7 +25,7 @@ interface PacerProviderProps {
25
25
  declare function PacerProvider({
26
26
  children,
27
27
  defaultOptions
28
- }: PacerProviderProps): preact0.JSX.Element;
28
+ }: PacerProviderProps): preact.JSX.Element;
29
29
  declare function usePacerContext(): PacerContextValue | null;
30
30
  declare function useDefaultPacerOptions(): PacerProviderOptions;
31
31
  //#endregion
@@ -1,5 +1,5 @@
1
1
  import { AnyAsyncFunction, AnyFunction, AsyncBatcherOptions, AsyncDebouncerOptions, AsyncQueuerOptions, AsyncRateLimiterOptions, AsyncThrottlerOptions, BatcherOptions, DebouncerOptions, QueuerOptions, RateLimiterOptions, ThrottlerOptions } from "@tanstack/pacer";
2
- import * as preact0 from "preact";
2
+ import * as preact from "preact";
3
3
  import { ComponentChildren } from "preact";
4
4
 
5
5
  //#region src/provider/PacerProvider.d.ts
@@ -25,7 +25,7 @@ interface PacerProviderProps {
25
25
  declare function PacerProvider({
26
26
  children,
27
27
  defaultOptions
28
- }: PacerProviderProps): preact0.JSX.Element;
28
+ }: PacerProviderProps): preact.JSX.Element;
29
29
  declare function usePacerContext(): PacerContextValue | null;
30
30
  declare function useDefaultPacerOptions(): PacerProviderOptions;
31
31
  //#endregion
@@ -1 +1 @@
1
- {"version":3,"file":"PacerProvider.js","names":[],"sources":["../../src/provider/PacerProvider.tsx"],"sourcesContent":["import { useContext, useMemo } from 'preact/hooks'\nimport { createContext } from 'preact'\nimport type { ComponentChildren } from 'preact'\nimport type {\n AnyAsyncFunction,\n AnyFunction,\n AsyncBatcherOptions,\n AsyncDebouncerOptions,\n AsyncQueuerOptions,\n AsyncRateLimiterOptions,\n AsyncThrottlerOptions,\n BatcherOptions,\n DebouncerOptions,\n QueuerOptions,\n RateLimiterOptions,\n ThrottlerOptions,\n} from '@tanstack/pacer'\n\nexport interface PacerProviderOptions {\n asyncBatcher?: Partial<AsyncBatcherOptions<any>>\n asyncDebouncer?: Partial<AsyncDebouncerOptions<AnyAsyncFunction>>\n asyncQueuer?: Partial<AsyncQueuerOptions<any>>\n asyncRateLimiter?: Partial<AsyncRateLimiterOptions<AnyAsyncFunction>>\n asyncThrottler?: Partial<AsyncThrottlerOptions<AnyAsyncFunction>>\n batcher?: Partial<BatcherOptions<any>>\n debouncer?: Partial<DebouncerOptions<AnyFunction>>\n queuer?: Partial<QueuerOptions<any>>\n rateLimiter?: Partial<RateLimiterOptions<AnyFunction>>\n throttler?: Partial<ThrottlerOptions<AnyFunction>>\n}\n\ninterface PacerContextValue {\n defaultOptions: PacerProviderOptions\n}\n\nconst PacerContext = createContext<PacerContextValue | null>(null)\n\nexport interface PacerProviderProps {\n children: ComponentChildren\n defaultOptions?: PacerProviderOptions\n}\n\nconst DEFAULT_OPTIONS: PacerProviderOptions = {}\n\nexport function PacerProvider({\n children,\n defaultOptions = DEFAULT_OPTIONS,\n}: PacerProviderProps) {\n const contextValue: PacerContextValue = useMemo(\n () => ({\n defaultOptions,\n }),\n [defaultOptions],\n )\n\n return (\n <PacerContext.Provider value={contextValue}>\n {children}\n </PacerContext.Provider>\n )\n}\n\nexport function usePacerContext() {\n return useContext(PacerContext)\n}\n\nexport function useDefaultPacerOptions() {\n const context = useContext(PacerContext)\n return context?.defaultOptions ?? {}\n}\n"],"mappings":";;;;;AAmCA,MAAM,eAAe,cAAwC,KAAK;AAOlE,MAAM,kBAAwC,EAAE;AAEhD,SAAgB,cAAc,EAC5B,UACA,iBAAiB,mBACI;CACrB,MAAM,eAAkC,eAC/B,EACL,gBACD,GACD,CAAC,eAAe,CACjB;AAED,QACE,oBAAC,aAAa;EAAS,OAAO;EAC3B;GACqB;;AAI5B,SAAgB,kBAAkB;AAChC,QAAO,WAAW,aAAa;;AAGjC,SAAgB,yBAAyB;AAEvC,QADgB,WAAW,aAAa,EACxB,kBAAkB,EAAE"}
1
+ {"version":3,"file":"PacerProvider.js","names":[],"sources":["../../src/provider/PacerProvider.tsx"],"sourcesContent":["import { useContext, useMemo } from 'preact/hooks'\nimport { createContext } from 'preact'\nimport type { ComponentChildren } from 'preact'\nimport type {\n AnyAsyncFunction,\n AnyFunction,\n AsyncBatcherOptions,\n AsyncDebouncerOptions,\n AsyncQueuerOptions,\n AsyncRateLimiterOptions,\n AsyncThrottlerOptions,\n BatcherOptions,\n DebouncerOptions,\n QueuerOptions,\n RateLimiterOptions,\n ThrottlerOptions,\n} from '@tanstack/pacer'\n\nexport interface PacerProviderOptions {\n asyncBatcher?: Partial<AsyncBatcherOptions<any>>\n asyncDebouncer?: Partial<AsyncDebouncerOptions<AnyAsyncFunction>>\n asyncQueuer?: Partial<AsyncQueuerOptions<any>>\n asyncRateLimiter?: Partial<AsyncRateLimiterOptions<AnyAsyncFunction>>\n asyncThrottler?: Partial<AsyncThrottlerOptions<AnyAsyncFunction>>\n batcher?: Partial<BatcherOptions<any>>\n debouncer?: Partial<DebouncerOptions<AnyFunction>>\n queuer?: Partial<QueuerOptions<any>>\n rateLimiter?: Partial<RateLimiterOptions<AnyFunction>>\n throttler?: Partial<ThrottlerOptions<AnyFunction>>\n}\n\ninterface PacerContextValue {\n defaultOptions: PacerProviderOptions\n}\n\nconst PacerContext = createContext<PacerContextValue | null>(null)\n\nexport interface PacerProviderProps {\n children: ComponentChildren\n defaultOptions?: PacerProviderOptions\n}\n\nconst DEFAULT_OPTIONS: PacerProviderOptions = {}\n\nexport function PacerProvider({\n children,\n defaultOptions = DEFAULT_OPTIONS,\n}: PacerProviderProps) {\n const contextValue: PacerContextValue = useMemo(\n () => ({\n defaultOptions,\n }),\n [defaultOptions],\n )\n\n return (\n <PacerContext.Provider value={contextValue}>\n {children}\n </PacerContext.Provider>\n )\n}\n\nexport function usePacerContext() {\n return useContext(PacerContext)\n}\n\nexport function useDefaultPacerOptions() {\n const context = useContext(PacerContext)\n return context?.defaultOptions ?? {}\n}\n"],"mappings":";;;;;AAmCA,MAAM,eAAe,cAAwC,KAAK;AAOlE,MAAM,kBAAwC,EAAE;AAEhD,SAAgB,cAAc,EAC5B,UACA,iBAAiB,mBACI;CACrB,MAAM,eAAkC,eAC/B,EACL,gBACD,GACD,CAAC,eAAe,CACjB;AAED,QACE,oBAAC,aAAa,UAAd;EAAuB,OAAO;EAC3B;EACqB;;AAI5B,SAAgB,kBAAkB;AAChC,QAAO,WAAW,aAAa;;AAGjC,SAAgB,yBAAyB;AAEvC,QADgB,WAAW,aAAa,EACxB,kBAAkB,EAAE"}
@@ -1,3 +1,4 @@
1
+ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
1
2
  const require_PacerProvider = require('./PacerProvider.cjs');
2
3
 
3
4
  exports.PacerProvider = require_PacerProvider.PacerProvider;
@@ -1,3 +1,4 @@
1
+ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
1
2
  const require_useQueuer = require('./useQueuer.cjs');
2
3
  const require_useQueuedState = require('./useQueuedState.cjs');
3
4
  const require_useQueuedValue = require('./useQueuedValue.cjs');
@@ -1,5 +1,5 @@
1
- import { PreactQueuer, useQueuer } from "./useQueuer.cjs";
1
+ import { PreactQueuer, PreactQueuerOptions, useQueuer } from "./useQueuer.cjs";
2
2
  import { useQueuedState } from "./useQueuedState.cjs";
3
3
  import { useQueuedValue } from "./useQueuedValue.cjs";
4
4
  export * from "@tanstack/pacer/queuer";
5
- export { PreactQueuer, useQueuedState, useQueuedValue, useQueuer };
5
+ export { PreactQueuer, PreactQueuerOptions, useQueuedState, useQueuedValue, useQueuer };
@@ -1,5 +1,5 @@
1
- import { PreactQueuer, useQueuer } from "./useQueuer.js";
1
+ import { PreactQueuer, PreactQueuerOptions, useQueuer } from "./useQueuer.js";
2
2
  import { useQueuedState } from "./useQueuedState.js";
3
3
  import { useQueuedValue } from "./useQueuedValue.js";
4
4
  export * from "@tanstack/pacer/queuer";
5
- export { PreactQueuer, useQueuedState, useQueuedValue, useQueuer };
5
+ export { PreactQueuer, PreactQueuerOptions, useQueuedState, useQueuedValue, useQueuer };
@@ -1 +1 @@
1
- {"version":3,"file":"useQueuedState.cjs","names":["useQueuer"],"sources":["../../src/queuer/useQueuedState.ts"],"sourcesContent":["import { useQueuer } from './useQueuer'\nimport type { PreactQueuer } from './useQueuer'\nimport type { Queuer, QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'\n\n/**\n * A Preact hook that creates a queuer with managed state, combining Preact's useState with queuing functionality.\n * This hook provides both the current queue state and queue control methods.\n *\n * The queue state is automatically updated whenever items are added, removed, or reordered in the queue.\n * All queue operations are reflected in the state array returned by the hook.\n *\n * The queue can be started and stopped to automatically process items at a specified interval,\n * making it useful as a scheduler. When started, it will process one item per tick, with an\n * optional wait time between ticks.\n *\n * The hook returns a tuple containing:\n * - The current queue state as an array\n * - The queue instance with methods for queue manipulation\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying queuer instance.\n * The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,\n * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.\n *\n * **By default, there will be no reactive state subscriptions** and you must opt-in to state\n * tracking by providing a selector function. This prevents unnecessary re-renders and gives you\n * full control over when your component updates. Only when you provide a selector will the\n * component re-render when the selected state values change.\n *\n * Available queuer state properties:\n * - `executionCount`: Number of items that have been processed by the queuer\n * - `expirationCount`: Number of items that have been removed due to expiration\n * - `isEmpty`: Whether the queuer has no items to process\n * - `isFull`: Whether the queuer has reached its maximum capacity\n * - `isIdle`: Whether the queuer is not currently processing any items\n * - `isRunning`: Whether the queuer is active and will process items automatically\n * - `items`: Array of items currently waiting to be processed\n * - `itemTimestamps`: Timestamps when items were added for expiration tracking\n * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item\n * - `rejectionCount`: Number of items that have been rejected from being added\n * - `size`: Number of items currently in the queue\n * - `status`: Current processing status ('idle' | 'running' | 'stopped')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [items, addItem, queue] = useQueuedState(\n * (item) => console.log('Processing:', item),\n * {\n * initialItems: ['item1', 'item2'],\n * started: true,\n * wait: 1000,\n * getPriority: (item) => item.priority\n * }\n * );\n *\n * // Opt-in to re-render when queue contents change (optimized for displaying queue items)\n * const [items, addItem, queue] = useQueuedState(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * items: state.items,\n * size: state.size,\n * isEmpty: state.isEmpty\n * })\n * );\n *\n * // Opt-in to re-render when processing state changes (optimized for loading indicators)\n * const [items, addItem, queue] = useQueuedState(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * isRunning: state.isRunning,\n * isIdle: state.isIdle,\n * status: state.status,\n * pendingTick: state.pendingTick\n * })\n * );\n *\n * // Opt-in to re-render when execution metrics change (optimized for stats display)\n * const [items, addItem, queue] = useQueuedState(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * executionCount: state.executionCount,\n * expirationCount: state.expirationCount,\n * rejectionCount: state.rejectionCount\n * })\n * );\n *\n * // Add items to queue\n * const handleAdd = (item) => {\n * addItem(item);\n * };\n *\n * // Start automatic processing\n * const startProcessing = () => {\n * queue.start();\n * };\n *\n * // Stop automatic processing\n * const stopProcessing = () => {\n * queue.stop();\n * };\n *\n * // Manual processing still available\n * const handleProcess = () => {\n * const nextItem = queue.getNextItem();\n * if (nextItem) {\n * processItem(nextItem);\n * }\n * };\n *\n * // Access the selected queuer state (will be empty object {} unless selector provided)\n * const { size, isRunning, executionCount } = queue.state;\n * ```\n */\nexport function useQueuedState<\n TValue,\n TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<\n QueuerState<TValue>,\n 'items'\n >,\n>(\n fn: (item: TValue) => void,\n options: QueuerOptions<TValue> = {},\n selector?: (state: QueuerState<TValue>) => TSelected,\n): [Array<TValue>, Queuer<TValue>['addItem'], PreactQueuer<TValue, TSelected>] {\n const queue = useQueuer(fn, options, selector)\n\n return [queue.state.items, queue.addItem, queue]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsHA,SAAgB,eAOd,IACA,UAAiC,EAAE,EACnC,UAC6E;CAC7E,MAAM,QAAQA,4BAAU,IAAI,SAAS,SAAS;AAE9C,QAAO;EAAC,MAAM,MAAM;EAAO,MAAM;EAAS;EAAM"}
1
+ {"version":3,"file":"useQueuedState.cjs","names":["useQueuer"],"sources":["../../src/queuer/useQueuedState.ts"],"sourcesContent":["import { useQueuer } from './useQueuer'\nimport type { PreactQueuer, PreactQueuerOptions } from './useQueuer'\nimport type { Queuer, QueuerState } from '@tanstack/pacer/queuer'\n\n/**\n * A Preact hook that creates a queuer with managed state, combining Preact's useState with queuing functionality.\n * This hook provides both the current queue state and queue control methods.\n *\n * The queue state is automatically updated whenever items are added, removed, or reordered in the queue.\n * All queue operations are reflected in the state array returned by the hook.\n *\n * The queue can be started and stopped to automatically process items at a specified interval,\n * making it useful as a scheduler. When started, it will process one item per tick, with an\n * optional wait time between ticks.\n *\n * The hook returns a tuple containing:\n * - The current queue state as an array\n * - The queue instance with methods for queue manipulation\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying queuer instance.\n * The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,\n * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.\n *\n * **By default, there will be no reactive state subscriptions** and you must opt-in to state\n * tracking by providing a selector function. This prevents unnecessary re-renders and gives you\n * full control over when your component updates. Only when you provide a selector will the\n * component re-render when the selected state values change.\n *\n * Available queuer state properties:\n * - `executionCount`: Number of items that have been processed by the queuer\n * - `expirationCount`: Number of items that have been removed due to expiration\n * - `isEmpty`: Whether the queuer has no items to process\n * - `isFull`: Whether the queuer has reached its maximum capacity\n * - `isIdle`: Whether the queuer is not currently processing any items\n * - `isRunning`: Whether the queuer is active and will process items automatically\n * - `items`: Array of items currently waiting to be processed\n * - `itemTimestamps`: Timestamps when items were added for expiration tracking\n * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item\n * - `rejectionCount`: Number of items that have been rejected from being added\n * - `size`: Number of items currently in the queue\n * - `status`: Current processing status ('idle' | 'running' | 'stopped')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [items, addItem, queue] = useQueuedState(\n * (item) => console.log('Processing:', item),\n * {\n * initialItems: ['item1', 'item2'],\n * started: true,\n * wait: 1000,\n * getPriority: (item) => item.priority\n * }\n * );\n *\n * // Opt-in to re-render when queue contents change (optimized for displaying queue items)\n * const [items, addItem, queue] = useQueuedState(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * items: state.items,\n * size: state.size,\n * isEmpty: state.isEmpty\n * })\n * );\n *\n * // Opt-in to re-render when processing state changes (optimized for loading indicators)\n * const [items, addItem, queue] = useQueuedState(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * isRunning: state.isRunning,\n * isIdle: state.isIdle,\n * status: state.status,\n * pendingTick: state.pendingTick\n * })\n * );\n *\n * // Opt-in to re-render when execution metrics change (optimized for stats display)\n * const [items, addItem, queue] = useQueuedState(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * executionCount: state.executionCount,\n * expirationCount: state.expirationCount,\n * rejectionCount: state.rejectionCount\n * })\n * );\n *\n * // Add items to queue\n * const handleAdd = (item) => {\n * addItem(item);\n * };\n *\n * // Start automatic processing\n * const startProcessing = () => {\n * queue.start();\n * };\n *\n * // Stop automatic processing\n * const stopProcessing = () => {\n * queue.stop();\n * };\n *\n * // Manual processing still available\n * const handleProcess = () => {\n * const nextItem = queue.getNextItem();\n * if (nextItem) {\n * processItem(nextItem);\n * }\n * };\n *\n * // Access the selected queuer state (will be empty object {} unless selector provided)\n * const { size, isRunning, executionCount } = queue.state;\n * ```\n */\nexport function useQueuedState<\n TValue,\n TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<\n QueuerState<TValue>,\n 'items'\n >,\n>(\n fn: (item: TValue) => void,\n options: PreactQueuerOptions<TValue, TSelected> = {},\n selector?: (state: QueuerState<TValue>) => TSelected,\n): [Array<TValue>, Queuer<TValue>['addItem'], PreactQueuer<TValue, TSelected>] {\n const queue = useQueuer(fn, options, selector)\n\n return [queue.state.items, queue.addItem, queue]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsHA,SAAgB,eAOd,IACA,UAAkD,EAAE,EACpD,UAC6E;CAC7E,MAAM,QAAQA,4BAAU,IAAI,SAAS,SAAS;AAE9C,QAAO;EAAC,MAAM,MAAM;EAAO,MAAM;EAAS;EAAM"}
@@ -1,5 +1,5 @@
1
- import { PreactQueuer } from "./useQueuer.cjs";
2
- import { Queuer, QueuerOptions, QueuerState } from "@tanstack/pacer/queuer";
1
+ import { PreactQueuer, PreactQueuerOptions } from "./useQueuer.cjs";
2
+ import { Queuer, QueuerState } from "@tanstack/pacer/queuer";
3
3
 
4
4
  //#region src/queuer/useQueuedState.d.ts
5
5
  /**
@@ -116,7 +116,7 @@ import { Queuer, QueuerOptions, QueuerState } from "@tanstack/pacer/queuer";
116
116
  * const { size, isRunning, executionCount } = queue.state;
117
117
  * ```
118
118
  */
119
- declare function useQueuedState<TValue, TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<QueuerState<TValue>, 'items'>>(fn: (item: TValue) => void, options?: QueuerOptions<TValue>, selector?: (state: QueuerState<TValue>) => TSelected): [Array<TValue>, Queuer<TValue>['addItem'], PreactQueuer<TValue, TSelected>];
119
+ declare function useQueuedState<TValue, TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<QueuerState<TValue>, 'items'>>(fn: (item: TValue) => void, options?: PreactQueuerOptions<TValue, TSelected>, selector?: (state: QueuerState<TValue>) => TSelected): [Array<TValue>, Queuer<TValue>['addItem'], PreactQueuer<TValue, TSelected>];
120
120
  //#endregion
121
121
  export { useQueuedState };
122
122
  //# sourceMappingURL=useQueuedState.d.cts.map
@@ -1,5 +1,5 @@
1
- import { PreactQueuer } from "./useQueuer.js";
2
- import { Queuer, QueuerOptions, QueuerState } from "@tanstack/pacer/queuer";
1
+ import { PreactQueuer, PreactQueuerOptions } from "./useQueuer.js";
2
+ import { Queuer, QueuerState } from "@tanstack/pacer/queuer";
3
3
 
4
4
  //#region src/queuer/useQueuedState.d.ts
5
5
  /**
@@ -116,7 +116,7 @@ import { Queuer, QueuerOptions, QueuerState } from "@tanstack/pacer/queuer";
116
116
  * const { size, isRunning, executionCount } = queue.state;
117
117
  * ```
118
118
  */
119
- declare function useQueuedState<TValue, TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<QueuerState<TValue>, 'items'>>(fn: (item: TValue) => void, options?: QueuerOptions<TValue>, selector?: (state: QueuerState<TValue>) => TSelected): [Array<TValue>, Queuer<TValue>['addItem'], PreactQueuer<TValue, TSelected>];
119
+ declare function useQueuedState<TValue, TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<QueuerState<TValue>, 'items'>>(fn: (item: TValue) => void, options?: PreactQueuerOptions<TValue, TSelected>, selector?: (state: QueuerState<TValue>) => TSelected): [Array<TValue>, Queuer<TValue>['addItem'], PreactQueuer<TValue, TSelected>];
120
120
  //#endregion
121
121
  export { useQueuedState };
122
122
  //# sourceMappingURL=useQueuedState.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"useQueuedState.js","names":[],"sources":["../../src/queuer/useQueuedState.ts"],"sourcesContent":["import { useQueuer } from './useQueuer'\nimport type { PreactQueuer } from './useQueuer'\nimport type { Queuer, QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'\n\n/**\n * A Preact hook that creates a queuer with managed state, combining Preact's useState with queuing functionality.\n * This hook provides both the current queue state and queue control methods.\n *\n * The queue state is automatically updated whenever items are added, removed, or reordered in the queue.\n * All queue operations are reflected in the state array returned by the hook.\n *\n * The queue can be started and stopped to automatically process items at a specified interval,\n * making it useful as a scheduler. When started, it will process one item per tick, with an\n * optional wait time between ticks.\n *\n * The hook returns a tuple containing:\n * - The current queue state as an array\n * - The queue instance with methods for queue manipulation\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying queuer instance.\n * The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,\n * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.\n *\n * **By default, there will be no reactive state subscriptions** and you must opt-in to state\n * tracking by providing a selector function. This prevents unnecessary re-renders and gives you\n * full control over when your component updates. Only when you provide a selector will the\n * component re-render when the selected state values change.\n *\n * Available queuer state properties:\n * - `executionCount`: Number of items that have been processed by the queuer\n * - `expirationCount`: Number of items that have been removed due to expiration\n * - `isEmpty`: Whether the queuer has no items to process\n * - `isFull`: Whether the queuer has reached its maximum capacity\n * - `isIdle`: Whether the queuer is not currently processing any items\n * - `isRunning`: Whether the queuer is active and will process items automatically\n * - `items`: Array of items currently waiting to be processed\n * - `itemTimestamps`: Timestamps when items were added for expiration tracking\n * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item\n * - `rejectionCount`: Number of items that have been rejected from being added\n * - `size`: Number of items currently in the queue\n * - `status`: Current processing status ('idle' | 'running' | 'stopped')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [items, addItem, queue] = useQueuedState(\n * (item) => console.log('Processing:', item),\n * {\n * initialItems: ['item1', 'item2'],\n * started: true,\n * wait: 1000,\n * getPriority: (item) => item.priority\n * }\n * );\n *\n * // Opt-in to re-render when queue contents change (optimized for displaying queue items)\n * const [items, addItem, queue] = useQueuedState(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * items: state.items,\n * size: state.size,\n * isEmpty: state.isEmpty\n * })\n * );\n *\n * // Opt-in to re-render when processing state changes (optimized for loading indicators)\n * const [items, addItem, queue] = useQueuedState(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * isRunning: state.isRunning,\n * isIdle: state.isIdle,\n * status: state.status,\n * pendingTick: state.pendingTick\n * })\n * );\n *\n * // Opt-in to re-render when execution metrics change (optimized for stats display)\n * const [items, addItem, queue] = useQueuedState(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * executionCount: state.executionCount,\n * expirationCount: state.expirationCount,\n * rejectionCount: state.rejectionCount\n * })\n * );\n *\n * // Add items to queue\n * const handleAdd = (item) => {\n * addItem(item);\n * };\n *\n * // Start automatic processing\n * const startProcessing = () => {\n * queue.start();\n * };\n *\n * // Stop automatic processing\n * const stopProcessing = () => {\n * queue.stop();\n * };\n *\n * // Manual processing still available\n * const handleProcess = () => {\n * const nextItem = queue.getNextItem();\n * if (nextItem) {\n * processItem(nextItem);\n * }\n * };\n *\n * // Access the selected queuer state (will be empty object {} unless selector provided)\n * const { size, isRunning, executionCount } = queue.state;\n * ```\n */\nexport function useQueuedState<\n TValue,\n TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<\n QueuerState<TValue>,\n 'items'\n >,\n>(\n fn: (item: TValue) => void,\n options: QueuerOptions<TValue> = {},\n selector?: (state: QueuerState<TValue>) => TSelected,\n): [Array<TValue>, Queuer<TValue>['addItem'], PreactQueuer<TValue, TSelected>] {\n const queue = useQueuer(fn, options, selector)\n\n return [queue.state.items, queue.addItem, queue]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsHA,SAAgB,eAOd,IACA,UAAiC,EAAE,EACnC,UAC6E;CAC7E,MAAM,QAAQ,UAAU,IAAI,SAAS,SAAS;AAE9C,QAAO;EAAC,MAAM,MAAM;EAAO,MAAM;EAAS;EAAM"}
1
+ {"version":3,"file":"useQueuedState.js","names":[],"sources":["../../src/queuer/useQueuedState.ts"],"sourcesContent":["import { useQueuer } from './useQueuer'\nimport type { PreactQueuer, PreactQueuerOptions } from './useQueuer'\nimport type { Queuer, QueuerState } from '@tanstack/pacer/queuer'\n\n/**\n * A Preact hook that creates a queuer with managed state, combining Preact's useState with queuing functionality.\n * This hook provides both the current queue state and queue control methods.\n *\n * The queue state is automatically updated whenever items are added, removed, or reordered in the queue.\n * All queue operations are reflected in the state array returned by the hook.\n *\n * The queue can be started and stopped to automatically process items at a specified interval,\n * making it useful as a scheduler. When started, it will process one item per tick, with an\n * optional wait time between ticks.\n *\n * The hook returns a tuple containing:\n * - The current queue state as an array\n * - The queue instance with methods for queue manipulation\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying queuer instance.\n * The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,\n * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.\n *\n * **By default, there will be no reactive state subscriptions** and you must opt-in to state\n * tracking by providing a selector function. This prevents unnecessary re-renders and gives you\n * full control over when your component updates. Only when you provide a selector will the\n * component re-render when the selected state values change.\n *\n * Available queuer state properties:\n * - `executionCount`: Number of items that have been processed by the queuer\n * - `expirationCount`: Number of items that have been removed due to expiration\n * - `isEmpty`: Whether the queuer has no items to process\n * - `isFull`: Whether the queuer has reached its maximum capacity\n * - `isIdle`: Whether the queuer is not currently processing any items\n * - `isRunning`: Whether the queuer is active and will process items automatically\n * - `items`: Array of items currently waiting to be processed\n * - `itemTimestamps`: Timestamps when items were added for expiration tracking\n * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item\n * - `rejectionCount`: Number of items that have been rejected from being added\n * - `size`: Number of items currently in the queue\n * - `status`: Current processing status ('idle' | 'running' | 'stopped')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [items, addItem, queue] = useQueuedState(\n * (item) => console.log('Processing:', item),\n * {\n * initialItems: ['item1', 'item2'],\n * started: true,\n * wait: 1000,\n * getPriority: (item) => item.priority\n * }\n * );\n *\n * // Opt-in to re-render when queue contents change (optimized for displaying queue items)\n * const [items, addItem, queue] = useQueuedState(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * items: state.items,\n * size: state.size,\n * isEmpty: state.isEmpty\n * })\n * );\n *\n * // Opt-in to re-render when processing state changes (optimized for loading indicators)\n * const [items, addItem, queue] = useQueuedState(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * isRunning: state.isRunning,\n * isIdle: state.isIdle,\n * status: state.status,\n * pendingTick: state.pendingTick\n * })\n * );\n *\n * // Opt-in to re-render when execution metrics change (optimized for stats display)\n * const [items, addItem, queue] = useQueuedState(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * executionCount: state.executionCount,\n * expirationCount: state.expirationCount,\n * rejectionCount: state.rejectionCount\n * })\n * );\n *\n * // Add items to queue\n * const handleAdd = (item) => {\n * addItem(item);\n * };\n *\n * // Start automatic processing\n * const startProcessing = () => {\n * queue.start();\n * };\n *\n * // Stop automatic processing\n * const stopProcessing = () => {\n * queue.stop();\n * };\n *\n * // Manual processing still available\n * const handleProcess = () => {\n * const nextItem = queue.getNextItem();\n * if (nextItem) {\n * processItem(nextItem);\n * }\n * };\n *\n * // Access the selected queuer state (will be empty object {} unless selector provided)\n * const { size, isRunning, executionCount } = queue.state;\n * ```\n */\nexport function useQueuedState<\n TValue,\n TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<\n QueuerState<TValue>,\n 'items'\n >,\n>(\n fn: (item: TValue) => void,\n options: PreactQueuerOptions<TValue, TSelected> = {},\n selector?: (state: QueuerState<TValue>) => TSelected,\n): [Array<TValue>, Queuer<TValue>['addItem'], PreactQueuer<TValue, TSelected>] {\n const queue = useQueuer(fn, options, selector)\n\n return [queue.state.items, queue.addItem, queue]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsHA,SAAgB,eAOd,IACA,UAAkD,EAAE,EACpD,UAC6E;CAC7E,MAAM,QAAQ,UAAU,IAAI,SAAS,SAAS;AAE9C,QAAO;EAAC,MAAM,MAAM;EAAO,MAAM;EAAS;EAAM"}
@@ -1 +1 @@
1
- {"version":3,"file":"useQueuedValue.cjs","names":["useQueuedState"],"sources":["../../src/queuer/useQueuedValue.ts"],"sourcesContent":["import { useEffect, useState } from 'preact/hooks'\nimport { useQueuedState } from './useQueuedState'\nimport type { PreactQueuer } from './useQueuer'\nimport type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'\n\n/**\n * A Preact hook that creates a queued value that processes state changes in order with an optional delay.\n * This hook uses useQueuer internally to manage a queue of state changes and apply them sequentially.\n *\n * The queued value will process changes in the order they are received, with optional delays between\n * processing each change. This is useful for handling state updates that need to be processed\n * in a specific order, like animations or sequential UI updates.\n *\n * The hook returns a tuple containing:\n * - The current queued value\n * - The queuer instance with control methods\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying queuer instance.\n * The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,\n * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.\n *\n * **By default, there will be no reactive state subscriptions** and you must opt-in to state\n * tracking by providing a selector function. This prevents unnecessary re-renders and gives you\n * full control over when your component updates. Only when you provide a selector will the\n * component re-render when the selected state values change.\n *\n * Available queuer state properties:\n * - `executionCount`: Number of items that have been processed by the queuer\n * - `expirationCount`: Number of items that have been removed due to expiration\n * - `isEmpty`: Whether the queuer has no items to process\n * - `isFull`: Whether the queuer has reached its maximum capacity\n * - `isIdle`: Whether the queuer is not currently processing any items\n * - `isRunning`: Whether the queuer is active and will process items automatically\n * - `items`: Array of items currently waiting to be processed\n * - `itemTimestamps`: Timestamps when items were added for expiration tracking\n * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item\n * - `rejectionCount`: Number of items that have been rejected from being added\n * - `size`: Number of items currently in the queue\n * - `status`: Current processing status ('idle' | 'running' | 'stopped')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [value, queuer] = useQueuedValue(initialValue, {\n * wait: 500, // Wait 500ms between processing each change\n * started: true // Start processing immediately\n * });\n *\n * // Opt-in to re-render when queue processing state changes (optimized for loading indicators)\n * const [value, queuer] = useQueuedValue(\n * initialValue,\n * { wait: 500, started: true },\n * (state) => ({\n * isRunning: state.isRunning,\n * isIdle: state.isIdle,\n * status: state.status,\n * pendingTick: state.pendingTick\n * })\n * );\n *\n * // Opt-in to re-render when queue contents change (optimized for displaying queue status)\n * const [value, queuer] = useQueuedValue(\n * initialValue,\n * { wait: 500, started: true },\n * (state) => ({\n * size: state.size,\n * isEmpty: state.isEmpty,\n * isFull: state.isFull\n * })\n * );\n *\n * // Opt-in to re-render when execution metrics change (optimized for stats display)\n * const [value, queuer] = useQueuedValue(\n * initialValue,\n * { wait: 500, started: true },\n * (state) => ({\n * executionCount: state.executionCount,\n * expirationCount: state.expirationCount,\n * rejectionCount: state.rejectionCount\n * })\n * );\n *\n * // Add changes to the queue\n * const handleChange = (newValue) => {\n * queuer.addItem(newValue);\n * };\n *\n * // Control the queue\n * const pauseProcessing = () => {\n * queuer.stop();\n * };\n *\n * const resumeProcessing = () => {\n * queuer.start();\n * };\n *\n * // Access the selected queuer state (will be empty object {} unless selector provided)\n * const { size, isRunning, executionCount } = queuer.state;\n * ```\n */\nexport function useQueuedValue<\n TValue,\n TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<\n QueuerState<TValue>,\n 'items'\n >,\n>(\n initialValue: TValue,\n options: QueuerOptions<TValue> = {},\n selector?: (state: QueuerState<TValue>) => TSelected,\n): [TValue, PreactQueuer<TValue, TSelected>] {\n const [value, setValue] = useState<TValue>(initialValue)\n\n const [, addItem, queuer] = useQueuedState(\n (item) => {\n setValue(item)\n },\n options,\n selector,\n )\n\n useEffect(() => {\n addItem(initialValue)\n }, [initialValue, addItem])\n\n return [value, queuer]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsGA,SAAgB,eAOd,cACA,UAAiC,EAAE,EACnC,UAC2C;CAC3C,MAAM,CAAC,OAAO,uCAA6B,aAAa;CAExD,MAAM,GAAG,SAAS,UAAUA,uCACzB,SAAS;AACR,WAAS,KAAK;IAEhB,SACA,SACD;AAED,mCAAgB;AACd,UAAQ,aAAa;IACpB,CAAC,cAAc,QAAQ,CAAC;AAE3B,QAAO,CAAC,OAAO,OAAO"}
1
+ {"version":3,"file":"useQueuedValue.cjs","names":["useQueuedState"],"sources":["../../src/queuer/useQueuedValue.ts"],"sourcesContent":["import { useEffect, useState } from 'preact/hooks'\nimport { useQueuedState } from './useQueuedState'\nimport type { PreactQueuer, PreactQueuerOptions } from './useQueuer'\nimport type { QueuerState } from '@tanstack/pacer/queuer'\n\n/**\n * A Preact hook that creates a queued value that processes state changes in order with an optional delay.\n * This hook uses useQueuer internally to manage a queue of state changes and apply them sequentially.\n *\n * The queued value will process changes in the order they are received, with optional delays between\n * processing each change. This is useful for handling state updates that need to be processed\n * in a specific order, like animations or sequential UI updates.\n *\n * The hook returns a tuple containing:\n * - The current queued value\n * - The queuer instance with control methods\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying queuer instance.\n * The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,\n * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.\n *\n * **By default, there will be no reactive state subscriptions** and you must opt-in to state\n * tracking by providing a selector function. This prevents unnecessary re-renders and gives you\n * full control over when your component updates. Only when you provide a selector will the\n * component re-render when the selected state values change.\n *\n * Available queuer state properties:\n * - `executionCount`: Number of items that have been processed by the queuer\n * - `expirationCount`: Number of items that have been removed due to expiration\n * - `isEmpty`: Whether the queuer has no items to process\n * - `isFull`: Whether the queuer has reached its maximum capacity\n * - `isIdle`: Whether the queuer is not currently processing any items\n * - `isRunning`: Whether the queuer is active and will process items automatically\n * - `items`: Array of items currently waiting to be processed\n * - `itemTimestamps`: Timestamps when items were added for expiration tracking\n * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item\n * - `rejectionCount`: Number of items that have been rejected from being added\n * - `size`: Number of items currently in the queue\n * - `status`: Current processing status ('idle' | 'running' | 'stopped')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [value, queuer] = useQueuedValue(initialValue, {\n * wait: 500, // Wait 500ms between processing each change\n * started: true // Start processing immediately\n * });\n *\n * // Opt-in to re-render when queue processing state changes (optimized for loading indicators)\n * const [value, queuer] = useQueuedValue(\n * initialValue,\n * { wait: 500, started: true },\n * (state) => ({\n * isRunning: state.isRunning,\n * isIdle: state.isIdle,\n * status: state.status,\n * pendingTick: state.pendingTick\n * })\n * );\n *\n * // Opt-in to re-render when queue contents change (optimized for displaying queue status)\n * const [value, queuer] = useQueuedValue(\n * initialValue,\n * { wait: 500, started: true },\n * (state) => ({\n * size: state.size,\n * isEmpty: state.isEmpty,\n * isFull: state.isFull\n * })\n * );\n *\n * // Opt-in to re-render when execution metrics change (optimized for stats display)\n * const [value, queuer] = useQueuedValue(\n * initialValue,\n * { wait: 500, started: true },\n * (state) => ({\n * executionCount: state.executionCount,\n * expirationCount: state.expirationCount,\n * rejectionCount: state.rejectionCount\n * })\n * );\n *\n * // Add changes to the queue\n * const handleChange = (newValue) => {\n * queuer.addItem(newValue);\n * };\n *\n * // Control the queue\n * const pauseProcessing = () => {\n * queuer.stop();\n * };\n *\n * const resumeProcessing = () => {\n * queuer.start();\n * };\n *\n * // Access the selected queuer state (will be empty object {} unless selector provided)\n * const { size, isRunning, executionCount } = queuer.state;\n * ```\n */\nexport function useQueuedValue<\n TValue,\n TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<\n QueuerState<TValue>,\n 'items'\n >,\n>(\n initialValue: TValue,\n options: PreactQueuerOptions<TValue, TSelected> = {},\n selector?: (state: QueuerState<TValue>) => TSelected,\n): [TValue, PreactQueuer<TValue, TSelected>] {\n const [value, setValue] = useState<TValue>(initialValue)\n\n const [, addItem, queuer] = useQueuedState(\n (item) => {\n setValue(item)\n },\n options,\n selector,\n )\n\n useEffect(() => {\n addItem(initialValue)\n }, [initialValue, addItem])\n\n return [value, queuer]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsGA,SAAgB,eAOd,cACA,UAAkD,EAAE,EACpD,UAC2C;CAC3C,MAAM,CAAC,OAAO,uCAA6B,aAAa;CAExD,MAAM,GAAG,SAAS,UAAUA,uCACzB,SAAS;AACR,WAAS,KAAK;IAEhB,SACA,SACD;AAED,mCAAgB;AACd,UAAQ,aAAa;IACpB,CAAC,cAAc,QAAQ,CAAC;AAE3B,QAAO,CAAC,OAAO,OAAO"}
@@ -1,5 +1,5 @@
1
- import { PreactQueuer } from "./useQueuer.cjs";
2
- import { QueuerOptions, QueuerState } from "@tanstack/pacer/queuer";
1
+ import { PreactQueuer, PreactQueuerOptions } from "./useQueuer.cjs";
2
+ import { QueuerState } from "@tanstack/pacer/queuer";
3
3
 
4
4
  //#region src/queuer/useQueuedValue.d.ts
5
5
  /**
@@ -99,7 +99,7 @@ import { QueuerOptions, QueuerState } from "@tanstack/pacer/queuer";
99
99
  * const { size, isRunning, executionCount } = queuer.state;
100
100
  * ```
101
101
  */
102
- declare function useQueuedValue<TValue, TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<QueuerState<TValue>, 'items'>>(initialValue: TValue, options?: QueuerOptions<TValue>, selector?: (state: QueuerState<TValue>) => TSelected): [TValue, PreactQueuer<TValue, TSelected>];
102
+ declare function useQueuedValue<TValue, TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<QueuerState<TValue>, 'items'>>(initialValue: TValue, options?: PreactQueuerOptions<TValue, TSelected>, selector?: (state: QueuerState<TValue>) => TSelected): [TValue, PreactQueuer<TValue, TSelected>];
103
103
  //#endregion
104
104
  export { useQueuedValue };
105
105
  //# sourceMappingURL=useQueuedValue.d.cts.map
@@ -1,5 +1,5 @@
1
- import { PreactQueuer } from "./useQueuer.js";
2
- import { QueuerOptions, QueuerState } from "@tanstack/pacer/queuer";
1
+ import { PreactQueuer, PreactQueuerOptions } from "./useQueuer.js";
2
+ import { QueuerState } from "@tanstack/pacer/queuer";
3
3
 
4
4
  //#region src/queuer/useQueuedValue.d.ts
5
5
  /**
@@ -99,7 +99,7 @@ import { QueuerOptions, QueuerState } from "@tanstack/pacer/queuer";
99
99
  * const { size, isRunning, executionCount } = queuer.state;
100
100
  * ```
101
101
  */
102
- declare function useQueuedValue<TValue, TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<QueuerState<TValue>, 'items'>>(initialValue: TValue, options?: QueuerOptions<TValue>, selector?: (state: QueuerState<TValue>) => TSelected): [TValue, PreactQueuer<TValue, TSelected>];
102
+ declare function useQueuedValue<TValue, TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<QueuerState<TValue>, 'items'>>(initialValue: TValue, options?: PreactQueuerOptions<TValue, TSelected>, selector?: (state: QueuerState<TValue>) => TSelected): [TValue, PreactQueuer<TValue, TSelected>];
103
103
  //#endregion
104
104
  export { useQueuedValue };
105
105
  //# sourceMappingURL=useQueuedValue.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"useQueuedValue.js","names":[],"sources":["../../src/queuer/useQueuedValue.ts"],"sourcesContent":["import { useEffect, useState } from 'preact/hooks'\nimport { useQueuedState } from './useQueuedState'\nimport type { PreactQueuer } from './useQueuer'\nimport type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'\n\n/**\n * A Preact hook that creates a queued value that processes state changes in order with an optional delay.\n * This hook uses useQueuer internally to manage a queue of state changes and apply them sequentially.\n *\n * The queued value will process changes in the order they are received, with optional delays between\n * processing each change. This is useful for handling state updates that need to be processed\n * in a specific order, like animations or sequential UI updates.\n *\n * The hook returns a tuple containing:\n * - The current queued value\n * - The queuer instance with control methods\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying queuer instance.\n * The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,\n * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.\n *\n * **By default, there will be no reactive state subscriptions** and you must opt-in to state\n * tracking by providing a selector function. This prevents unnecessary re-renders and gives you\n * full control over when your component updates. Only when you provide a selector will the\n * component re-render when the selected state values change.\n *\n * Available queuer state properties:\n * - `executionCount`: Number of items that have been processed by the queuer\n * - `expirationCount`: Number of items that have been removed due to expiration\n * - `isEmpty`: Whether the queuer has no items to process\n * - `isFull`: Whether the queuer has reached its maximum capacity\n * - `isIdle`: Whether the queuer is not currently processing any items\n * - `isRunning`: Whether the queuer is active and will process items automatically\n * - `items`: Array of items currently waiting to be processed\n * - `itemTimestamps`: Timestamps when items were added for expiration tracking\n * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item\n * - `rejectionCount`: Number of items that have been rejected from being added\n * - `size`: Number of items currently in the queue\n * - `status`: Current processing status ('idle' | 'running' | 'stopped')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [value, queuer] = useQueuedValue(initialValue, {\n * wait: 500, // Wait 500ms between processing each change\n * started: true // Start processing immediately\n * });\n *\n * // Opt-in to re-render when queue processing state changes (optimized for loading indicators)\n * const [value, queuer] = useQueuedValue(\n * initialValue,\n * { wait: 500, started: true },\n * (state) => ({\n * isRunning: state.isRunning,\n * isIdle: state.isIdle,\n * status: state.status,\n * pendingTick: state.pendingTick\n * })\n * );\n *\n * // Opt-in to re-render when queue contents change (optimized for displaying queue status)\n * const [value, queuer] = useQueuedValue(\n * initialValue,\n * { wait: 500, started: true },\n * (state) => ({\n * size: state.size,\n * isEmpty: state.isEmpty,\n * isFull: state.isFull\n * })\n * );\n *\n * // Opt-in to re-render when execution metrics change (optimized for stats display)\n * const [value, queuer] = useQueuedValue(\n * initialValue,\n * { wait: 500, started: true },\n * (state) => ({\n * executionCount: state.executionCount,\n * expirationCount: state.expirationCount,\n * rejectionCount: state.rejectionCount\n * })\n * );\n *\n * // Add changes to the queue\n * const handleChange = (newValue) => {\n * queuer.addItem(newValue);\n * };\n *\n * // Control the queue\n * const pauseProcessing = () => {\n * queuer.stop();\n * };\n *\n * const resumeProcessing = () => {\n * queuer.start();\n * };\n *\n * // Access the selected queuer state (will be empty object {} unless selector provided)\n * const { size, isRunning, executionCount } = queuer.state;\n * ```\n */\nexport function useQueuedValue<\n TValue,\n TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<\n QueuerState<TValue>,\n 'items'\n >,\n>(\n initialValue: TValue,\n options: QueuerOptions<TValue> = {},\n selector?: (state: QueuerState<TValue>) => TSelected,\n): [TValue, PreactQueuer<TValue, TSelected>] {\n const [value, setValue] = useState<TValue>(initialValue)\n\n const [, addItem, queuer] = useQueuedState(\n (item) => {\n setValue(item)\n },\n options,\n selector,\n )\n\n useEffect(() => {\n addItem(initialValue)\n }, [initialValue, addItem])\n\n return [value, queuer]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsGA,SAAgB,eAOd,cACA,UAAiC,EAAE,EACnC,UAC2C;CAC3C,MAAM,CAAC,OAAO,YAAY,SAAiB,aAAa;CAExD,MAAM,GAAG,SAAS,UAAU,gBACzB,SAAS;AACR,WAAS,KAAK;IAEhB,SACA,SACD;AAED,iBAAgB;AACd,UAAQ,aAAa;IACpB,CAAC,cAAc,QAAQ,CAAC;AAE3B,QAAO,CAAC,OAAO,OAAO"}
1
+ {"version":3,"file":"useQueuedValue.js","names":[],"sources":["../../src/queuer/useQueuedValue.ts"],"sourcesContent":["import { useEffect, useState } from 'preact/hooks'\nimport { useQueuedState } from './useQueuedState'\nimport type { PreactQueuer, PreactQueuerOptions } from './useQueuer'\nimport type { QueuerState } from '@tanstack/pacer/queuer'\n\n/**\n * A Preact hook that creates a queued value that processes state changes in order with an optional delay.\n * This hook uses useQueuer internally to manage a queue of state changes and apply them sequentially.\n *\n * The queued value will process changes in the order they are received, with optional delays between\n * processing each change. This is useful for handling state updates that need to be processed\n * in a specific order, like animations or sequential UI updates.\n *\n * The hook returns a tuple containing:\n * - The current queued value\n * - The queuer instance with control methods\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying queuer instance.\n * The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,\n * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.\n *\n * **By default, there will be no reactive state subscriptions** and you must opt-in to state\n * tracking by providing a selector function. This prevents unnecessary re-renders and gives you\n * full control over when your component updates. Only when you provide a selector will the\n * component re-render when the selected state values change.\n *\n * Available queuer state properties:\n * - `executionCount`: Number of items that have been processed by the queuer\n * - `expirationCount`: Number of items that have been removed due to expiration\n * - `isEmpty`: Whether the queuer has no items to process\n * - `isFull`: Whether the queuer has reached its maximum capacity\n * - `isIdle`: Whether the queuer is not currently processing any items\n * - `isRunning`: Whether the queuer is active and will process items automatically\n * - `items`: Array of items currently waiting to be processed\n * - `itemTimestamps`: Timestamps when items were added for expiration tracking\n * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item\n * - `rejectionCount`: Number of items that have been rejected from being added\n * - `size`: Number of items currently in the queue\n * - `status`: Current processing status ('idle' | 'running' | 'stopped')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [value, queuer] = useQueuedValue(initialValue, {\n * wait: 500, // Wait 500ms between processing each change\n * started: true // Start processing immediately\n * });\n *\n * // Opt-in to re-render when queue processing state changes (optimized for loading indicators)\n * const [value, queuer] = useQueuedValue(\n * initialValue,\n * { wait: 500, started: true },\n * (state) => ({\n * isRunning: state.isRunning,\n * isIdle: state.isIdle,\n * status: state.status,\n * pendingTick: state.pendingTick\n * })\n * );\n *\n * // Opt-in to re-render when queue contents change (optimized for displaying queue status)\n * const [value, queuer] = useQueuedValue(\n * initialValue,\n * { wait: 500, started: true },\n * (state) => ({\n * size: state.size,\n * isEmpty: state.isEmpty,\n * isFull: state.isFull\n * })\n * );\n *\n * // Opt-in to re-render when execution metrics change (optimized for stats display)\n * const [value, queuer] = useQueuedValue(\n * initialValue,\n * { wait: 500, started: true },\n * (state) => ({\n * executionCount: state.executionCount,\n * expirationCount: state.expirationCount,\n * rejectionCount: state.rejectionCount\n * })\n * );\n *\n * // Add changes to the queue\n * const handleChange = (newValue) => {\n * queuer.addItem(newValue);\n * };\n *\n * // Control the queue\n * const pauseProcessing = () => {\n * queuer.stop();\n * };\n *\n * const resumeProcessing = () => {\n * queuer.start();\n * };\n *\n * // Access the selected queuer state (will be empty object {} unless selector provided)\n * const { size, isRunning, executionCount } = queuer.state;\n * ```\n */\nexport function useQueuedValue<\n TValue,\n TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<\n QueuerState<TValue>,\n 'items'\n >,\n>(\n initialValue: TValue,\n options: PreactQueuerOptions<TValue, TSelected> = {},\n selector?: (state: QueuerState<TValue>) => TSelected,\n): [TValue, PreactQueuer<TValue, TSelected>] {\n const [value, setValue] = useState<TValue>(initialValue)\n\n const [, addItem, queuer] = useQueuedState(\n (item) => {\n setValue(item)\n },\n options,\n selector,\n )\n\n useEffect(() => {\n addItem(initialValue)\n }, [initialValue, addItem])\n\n return [value, queuer]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsGA,SAAgB,eAOd,cACA,UAAkD,EAAE,EACpD,UAC2C;CAC3C,MAAM,CAAC,OAAO,YAAY,SAAiB,aAAa;CAExD,MAAM,GAAG,SAAS,UAAU,gBACzB,SAAS;AACR,WAAS,KAAK;IAEhB,SACA,SACD;AAED,iBAAgB;AACd,UAAQ,aAAa;IACpB,CAAC,cAAc,QAAQ,CAAC;AAE3B,QAAO,CAAC,OAAO,OAAO"}
@@ -56,6 +56,19 @@ let _tanstack_pacer_queuer = require("@tanstack/pacer/queuer");
56
56
  * - `size`: Number of items currently in the queue
57
57
  * - `status`: Current processing status ('idle' | 'running' | 'stopped')
58
58
  *
59
+ * ## Unmount behavior
60
+ *
61
+ * By default, the hook stops the queuer when the component unmounts.
62
+ * Use the `onUnmount` option to customize this. For example, to flush pending items instead:
63
+ *
64
+ * ```tsx
65
+ * const queue = useQueuer(fn, {
66
+ * started: true,
67
+ * wait: 1000,
68
+ * onUnmount: (q) => q.flush()
69
+ * });
70
+ * ```
71
+ *
59
72
  * @example
60
73
  * ```tsx
61
74
  * // Default behavior - no reactive state subscriptions
@@ -138,14 +151,20 @@ function useQueuer(fn, options = {}, selector = () => ({})) {
138
151
  const [queuer] = (0, preact_hooks.useState)(() => {
139
152
  const queuerInstance = new _tanstack_pacer_queuer.Queuer(fn, mergedOptions);
140
153
  queuerInstance.Subscribe = function Subscribe(props) {
141
- const selected = (0, _tanstack_preact_store.useStore)(queuerInstance.store, props.selector);
154
+ const selected = (0, _tanstack_preact_store.useStore)(queuerInstance.store, props.selector, { equal: _tanstack_preact_store.shallow });
142
155
  return typeof props.children === "function" ? props.children(selected) : props.children;
143
156
  };
144
157
  return queuerInstance;
145
158
  });
146
159
  queuer.fn = fn;
147
160
  queuer.setOptions(mergedOptions);
148
- const state = (0, _tanstack_preact_store.useStore)(queuer.store, selector);
161
+ (0, preact_hooks.useEffect)(() => {
162
+ return () => {
163
+ if (mergedOptions.onUnmount) mergedOptions.onUnmount(queuer);
164
+ else queuer.stop();
165
+ };
166
+ }, []);
167
+ const state = (0, _tanstack_preact_store.useStore)(queuer.store, selector, { equal: _tanstack_preact_store.shallow });
149
168
  return (0, preact_hooks.useMemo)(() => ({
150
169
  ...queuer,
151
170
  state
@@ -1 +1 @@
1
- {"version":3,"file":"useQueuer.cjs","names":["useDefaultPacerOptions","Queuer"],"sources":["../../src/queuer/useQueuer.ts"],"sourcesContent":["import { useMemo, useState } from 'preact/hooks'\nimport { Queuer } from '@tanstack/pacer/queuer'\nimport { useStore } from '@tanstack/preact-store'\nimport { useDefaultPacerOptions } from '../provider/PacerProvider'\nimport type { Store } from '@tanstack/preact-store'\nimport type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'\nimport type { ComponentChildren } from 'preact'\n\nexport interface PreactQueuer<TValue, TSelected = {}> extends Omit<\n Queuer<TValue>,\n 'store'\n> {\n /**\n * A Preact HOC (Higher Order Component) that allows you to subscribe to the queuer state.\n *\n * This is useful for opting into state re-renders for specific parts of the queuer state\n * deep in your component tree without needing to pass a selector to the hook.\n *\n * @example\n * <queuer.Subscribe selector={(state) => ({ size: state.size })}>\n * {({ size }) => (\n * <div>Queue Size: {size}</div>\n * )}\n * </queuer.Subscribe>\n */\n Subscribe: <TSelected>(props: {\n selector: (state: QueuerState<TValue>) => TSelected\n children: ((state: TSelected) => ComponentChildren) | ComponentChildren\n }) => ComponentChildren\n /**\n * Reactive state that will be updated and re-rendered when the queuer state changes\n *\n * Use this instead of `queuer.store.state`\n */\n readonly state: Readonly<TSelected>\n /**\n * @deprecated Use `queuer.state` instead of `queuer.store.state` if you want to read reactive state.\n * The state on the store object is not reactive, as it has not been wrapped in a `useStore` hook internally.\n * Although, you can make the state reactive by using the `useStore` in your own usage.\n */\n readonly store: Store<Readonly<QueuerState<TValue>>>\n}\n\n/**\n * A Preact hook that creates and manages a Queuer instance.\n *\n * This is a lower-level hook that provides direct access to the Queuer's functionality without\n * any built-in state management. This allows you to integrate it with any state management solution\n * you prefer (useState, Redux, Zustand, etc.) by utilizing the onItemsChange callback.\n *\n * For a hook with built-in state management, see useQueuedState.\n *\n * The Queuer extends the base Queue to add processing capabilities. Items are processed\n * synchronously in order, with optional delays between processing each item. The queuer includes\n * an internal tick mechanism that can be started and stopped, making it useful as a scheduler.\n * When started, it will process one item per tick, with an optional wait time between ticks.\n *\n * By default uses FIFO (First In First Out) behavior, but can be configured for LIFO\n * (Last In First Out) by specifying 'front' position when adding items.\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management. You can subscribe to state changes\n * in two ways:\n *\n * **1. Using `queuer.Subscribe` HOC (Recommended for component tree subscriptions)**\n *\n * Use the `Subscribe` HOC to subscribe to state changes deep in your component tree without\n * needing to pass a selector to the hook. This is ideal when you want to subscribe to state\n * in child components.\n *\n * **2. Using the `selector` parameter (For hook-level subscriptions)**\n *\n * The `selector` parameter allows you to specify which state changes will trigger a re-render\n * at the hook level, optimizing performance by preventing unnecessary re-renders when irrelevant\n * state changes occur.\n *\n * **By default, there will be no reactive state subscriptions** and you must opt-in to state\n * tracking by providing a selector function or using the `Subscribe` HOC. This prevents unnecessary\n * re-renders and gives you full control over when your component updates.\n *\n * Available state properties:\n * - `executionCount`: Number of items that have been processed by the queuer\n * - `expirationCount`: Number of items that have been removed due to expiration\n * - `isEmpty`: Whether the queuer has no items to process\n * - `isFull`: Whether the queuer has reached its maximum capacity\n * - `isIdle`: Whether the queuer is not currently processing any items\n * - `isRunning`: Whether the queuer is active and will process items automatically\n * - `items`: Array of items currently waiting to be processed\n * - `itemTimestamps`: Timestamps when items were added for expiration tracking\n * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item\n * - `rejectionCount`: Number of items that have been rejected from being added\n * - `size`: Number of items currently in the queue\n * - `status`: Current processing status ('idle' | 'running' | 'stopped')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const queue = useQueuer(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 }\n * );\n *\n * // Subscribe to state changes deep in component tree using Subscribe HOC\n * <queue.Subscribe selector={(state) => ({ size: state.size })}>\n * {({ size }) => (\n * <div>Queue Size: {size}</div>\n * )}\n * </queue.Subscribe>\n *\n * // Opt-in to re-render when queue size changes at hook level (optimized for displaying queue length)\n * const queue = useQueuer(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * size: state.size,\n * isEmpty: state.isEmpty,\n * isFull: state.isFull\n * })\n * );\n *\n * // Opt-in to re-render when processing state changes (optimized for loading indicators)\n * const queue = useQueuer(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * isRunning: state.isRunning,\n * isIdle: state.isIdle,\n * status: state.status,\n * pendingTick: state.pendingTick\n * })\n * );\n *\n * // Opt-in to re-render when execution metrics change (optimized for stats display)\n * const queue = useQueuer(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * executionCount: state.executionCount,\n * expirationCount: state.expirationCount,\n * rejectionCount: state.rejectionCount\n * })\n * );\n *\n * // Example with custom state management and scheduling\n * const [items, setItems] = useState([]);\n *\n * const queue = useQueuer(\n * (item) => console.log('Processing:', item),\n * {\n * started: true, // Start processing immediately\n * wait: 1000, // Process one item every second\n * onItemsChange: (queue) => setItems(queue.peekAllItems()),\n * getPriority: (item) => item.priority // Process higher priority items first\n * }\n * );\n *\n * // Add items to process - they'll be handled automatically\n * queue.addItem('task1');\n * queue.addItem('task2');\n *\n * // Control the scheduler\n * queue.stop(); // Pause processing\n * queue.start(); // Resume processing\n *\n * // Access the selected state (will be empty object {} unless selector provided)\n * const { size, isRunning, executionCount } = queue.state;\n * ```\n */\nexport function useQueuer<TValue, TSelected = {}>(\n fn: (item: TValue) => void,\n options: QueuerOptions<TValue> = {},\n selector: (state: QueuerState<TValue>) => TSelected = () => ({}) as TSelected,\n): PreactQueuer<TValue, TSelected> {\n const mergedOptions = {\n ...useDefaultPacerOptions().queuer,\n ...options,\n } as QueuerOptions<TValue>\n\n const [queuer] = useState(() => {\n const queuerInstance = new Queuer<TValue>(\n fn,\n mergedOptions,\n ) as unknown as PreactQueuer<TValue, TSelected>\n\n queuerInstance.Subscribe = function Subscribe<TSelected>(props: {\n selector: (state: QueuerState<TValue>) => TSelected\n children: ((state: TSelected) => ComponentChildren) | ComponentChildren\n }) {\n const selected = useStore(queuerInstance.store, props.selector)\n\n return typeof props.children === 'function'\n ? props.children(selected)\n : props.children\n }\n\n return queuerInstance\n })\n\n queuer.fn = fn\n queuer.setOptions(mergedOptions)\n\n const state = useStore(queuer.store, selector)\n\n return useMemo(\n () =>\n ({\n ...queuer,\n state,\n }) as PreactQueuer<TValue, TSelected>, // omit `store` in favor of `state`\n [queuer, state],\n )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyKA,SAAgB,UACd,IACA,UAAiC,EAAE,EACnC,kBAA6D,EAAE,GAC9B;CACjC,MAAM,gBAAgB;EACpB,GAAGA,8CAAwB,CAAC;EAC5B,GAAG;EACJ;CAED,MAAM,CAAC,2CAAyB;EAC9B,MAAM,iBAAiB,IAAIC,8BACzB,IACA,cACD;AAED,iBAAe,YAAY,SAAS,UAAqB,OAGtD;GACD,MAAM,gDAAoB,eAAe,OAAO,MAAM,SAAS;AAE/D,UAAO,OAAO,MAAM,aAAa,aAC7B,MAAM,SAAS,SAAS,GACxB,MAAM;;AAGZ,SAAO;GACP;AAEF,QAAO,KAAK;AACZ,QAAO,WAAW,cAAc;CAEhC,MAAM,6CAAiB,OAAO,OAAO,SAAS;AAE9C,yCAEK;EACC,GAAG;EACH;EACD,GACH,CAAC,QAAQ,MAAM,CAChB"}
1
+ {"version":3,"file":"useQueuer.cjs","names":["useDefaultPacerOptions","Queuer","shallow"],"sources":["../../src/queuer/useQueuer.ts"],"sourcesContent":["import { useEffect, useMemo, useState } from 'preact/hooks'\nimport { Queuer } from '@tanstack/pacer/queuer'\nimport { shallow, useStore } from '@tanstack/preact-store'\nimport { useDefaultPacerOptions } from '../provider/PacerProvider'\nimport type { Store } from '@tanstack/preact-store'\nimport type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'\nimport type { ComponentChildren } from 'preact'\n\nexport interface PreactQueuerOptions<\n TValue,\n TSelected = {},\n> extends QueuerOptions<TValue> {\n /**\n * Optional callback invoked when the component unmounts. Receives the queuer instance.\n * When provided, replaces the default cleanup (stop); use it to call flush(), flushAsBatch(), stop(), add logging, etc.\n */\n onUnmount?: (queuer: PreactQueuer<TValue, TSelected>) => void\n}\n\nexport interface PreactQueuer<TValue, TSelected = {}> extends Omit<\n Queuer<TValue>,\n 'store'\n> {\n /**\n * A Preact HOC (Higher Order Component) that allows you to subscribe to the queuer state.\n *\n * This is useful for opting into state re-renders for specific parts of the queuer state\n * deep in your component tree without needing to pass a selector to the hook.\n *\n * @example\n * <queuer.Subscribe selector={(state) => ({ size: state.size })}>\n * {({ size }) => (\n * <div>Queue Size: {size}</div>\n * )}\n * </queuer.Subscribe>\n */\n Subscribe: <TSelected>(props: {\n selector: (state: QueuerState<TValue>) => TSelected\n children: ((state: TSelected) => ComponentChildren) | ComponentChildren\n }) => ComponentChildren\n /**\n * Reactive state that will be updated and re-rendered when the queuer state changes\n *\n * Use this instead of `queuer.store.state`\n */\n readonly state: Readonly<TSelected>\n /**\n * @deprecated Use `queuer.state` instead of `queuer.store.state` if you want to read reactive state.\n * The state on the store object is not reactive, as it has not been wrapped in a `useStore` hook internally.\n * Although, you can make the state reactive by using the `useStore` in your own usage.\n */\n readonly store: Store<Readonly<QueuerState<TValue>>>\n}\n\n/**\n * A Preact hook that creates and manages a Queuer instance.\n *\n * This is a lower-level hook that provides direct access to the Queuer's functionality without\n * any built-in state management. This allows you to integrate it with any state management solution\n * you prefer (useState, Redux, Zustand, etc.) by utilizing the onItemsChange callback.\n *\n * For a hook with built-in state management, see useQueuedState.\n *\n * The Queuer extends the base Queue to add processing capabilities. Items are processed\n * synchronously in order, with optional delays between processing each item. The queuer includes\n * an internal tick mechanism that can be started and stopped, making it useful as a scheduler.\n * When started, it will process one item per tick, with an optional wait time between ticks.\n *\n * By default uses FIFO (First In First Out) behavior, but can be configured for LIFO\n * (Last In First Out) by specifying 'front' position when adding items.\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management. You can subscribe to state changes\n * in two ways:\n *\n * **1. Using `queuer.Subscribe` HOC (Recommended for component tree subscriptions)**\n *\n * Use the `Subscribe` HOC to subscribe to state changes deep in your component tree without\n * needing to pass a selector to the hook. This is ideal when you want to subscribe to state\n * in child components.\n *\n * **2. Using the `selector` parameter (For hook-level subscriptions)**\n *\n * The `selector` parameter allows you to specify which state changes will trigger a re-render\n * at the hook level, optimizing performance by preventing unnecessary re-renders when irrelevant\n * state changes occur.\n *\n * **By default, there will be no reactive state subscriptions** and you must opt-in to state\n * tracking by providing a selector function or using the `Subscribe` HOC. This prevents unnecessary\n * re-renders and gives you full control over when your component updates.\n *\n * Available state properties:\n * - `executionCount`: Number of items that have been processed by the queuer\n * - `expirationCount`: Number of items that have been removed due to expiration\n * - `isEmpty`: Whether the queuer has no items to process\n * - `isFull`: Whether the queuer has reached its maximum capacity\n * - `isIdle`: Whether the queuer is not currently processing any items\n * - `isRunning`: Whether the queuer is active and will process items automatically\n * - `items`: Array of items currently waiting to be processed\n * - `itemTimestamps`: Timestamps when items were added for expiration tracking\n * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item\n * - `rejectionCount`: Number of items that have been rejected from being added\n * - `size`: Number of items currently in the queue\n * - `status`: Current processing status ('idle' | 'running' | 'stopped')\n *\n * ## Unmount behavior\n *\n * By default, the hook stops the queuer when the component unmounts.\n * Use the `onUnmount` option to customize this. For example, to flush pending items instead:\n *\n * ```tsx\n * const queue = useQueuer(fn, {\n * started: true,\n * wait: 1000,\n * onUnmount: (q) => q.flush()\n * });\n * ```\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const queue = useQueuer(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 }\n * );\n *\n * // Subscribe to state changes deep in component tree using Subscribe HOC\n * <queue.Subscribe selector={(state) => ({ size: state.size })}>\n * {({ size }) => (\n * <div>Queue Size: {size}</div>\n * )}\n * </queue.Subscribe>\n *\n * // Opt-in to re-render when queue size changes at hook level (optimized for displaying queue length)\n * const queue = useQueuer(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * size: state.size,\n * isEmpty: state.isEmpty,\n * isFull: state.isFull\n * })\n * );\n *\n * // Opt-in to re-render when processing state changes (optimized for loading indicators)\n * const queue = useQueuer(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * isRunning: state.isRunning,\n * isIdle: state.isIdle,\n * status: state.status,\n * pendingTick: state.pendingTick\n * })\n * );\n *\n * // Opt-in to re-render when execution metrics change (optimized for stats display)\n * const queue = useQueuer(\n * (item) => console.log('Processing:', item),\n * { started: true, wait: 1000 },\n * (state) => ({\n * executionCount: state.executionCount,\n * expirationCount: state.expirationCount,\n * rejectionCount: state.rejectionCount\n * })\n * );\n *\n * // Example with custom state management and scheduling\n * const [items, setItems] = useState([]);\n *\n * const queue = useQueuer(\n * (item) => console.log('Processing:', item),\n * {\n * started: true, // Start processing immediately\n * wait: 1000, // Process one item every second\n * onItemsChange: (queue) => setItems(queue.peekAllItems()),\n * getPriority: (item) => item.priority // Process higher priority items first\n * }\n * );\n *\n * // Add items to process - they'll be handled automatically\n * queue.addItem('task1');\n * queue.addItem('task2');\n *\n * // Control the scheduler\n * queue.stop(); // Pause processing\n * queue.start(); // Resume processing\n *\n * // Access the selected state (will be empty object {} unless selector provided)\n * const { size, isRunning, executionCount } = queue.state;\n * ```\n */\nexport function useQueuer<TValue, TSelected = {}>(\n fn: (item: TValue) => void,\n options: PreactQueuerOptions<TValue, TSelected> = {},\n selector: (state: QueuerState<TValue>) => TSelected = () => ({}) as TSelected,\n): PreactQueuer<TValue, TSelected> {\n const mergedOptions = {\n ...useDefaultPacerOptions().queuer,\n ...options,\n } as PreactQueuerOptions<TValue, TSelected>\n\n const [queuer] = useState(() => {\n const queuerInstance = new Queuer<TValue>(\n fn,\n mergedOptions,\n ) as unknown as PreactQueuer<TValue, TSelected>\n\n queuerInstance.Subscribe = function Subscribe<TSelected>(props: {\n selector: (state: QueuerState<TValue>) => TSelected\n children: ((state: TSelected) => ComponentChildren) | ComponentChildren\n }) {\n const selected = useStore(queuerInstance.store, props.selector, {\n equal: shallow,\n })\n\n return typeof props.children === 'function'\n ? props.children(selected)\n : props.children\n }\n\n return queuerInstance\n })\n\n queuer.fn = fn\n queuer.setOptions(mergedOptions)\n\n /* eslint-disable react-hooks/exhaustive-deps -- cleanup only; runs on unmount */\n useEffect(() => {\n return () => {\n if (mergedOptions.onUnmount) {\n mergedOptions.onUnmount(queuer)\n } else {\n queuer.stop()\n }\n }\n }, [])\n /* eslint-enable react-hooks/exhaustive-deps */\n\n const state = useStore(queuer.store, selector, { equal: shallow })\n\n return useMemo(\n () =>\n ({\n ...queuer,\n state,\n }) as PreactQueuer<TValue, TSelected>, // omit `store` in favor of `state`\n [queuer, state],\n )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiMA,SAAgB,UACd,IACA,UAAkD,EAAE,EACpD,kBAA6D,EAAE,GAC9B;CACjC,MAAM,gBAAgB;EACpB,GAAGA,8CAAwB,CAAC;EAC5B,GAAG;EACJ;CAED,MAAM,CAAC,2CAAyB;EAC9B,MAAM,iBAAiB,IAAIC,8BACzB,IACA,cACD;AAED,iBAAe,YAAY,SAAS,UAAqB,OAGtD;GACD,MAAM,gDAAoB,eAAe,OAAO,MAAM,UAAU,EAC9D,OAAOC,gCACR,CAAC;AAEF,UAAO,OAAO,MAAM,aAAa,aAC7B,MAAM,SAAS,SAAS,GACxB,MAAM;;AAGZ,SAAO;GACP;AAEF,QAAO,KAAK;AACZ,QAAO,WAAW,cAAc;AAGhC,mCAAgB;AACd,eAAa;AACX,OAAI,cAAc,UAChB,eAAc,UAAU,OAAO;OAE/B,QAAO,MAAM;;IAGhB,EAAE,CAAC;CAGN,MAAM,6CAAiB,OAAO,OAAO,UAAU,EAAE,OAAOA,gCAAS,CAAC;AAElE,yCAEK;EACC,GAAG;EACH;EACD,GACH,CAAC,QAAQ,MAAM,CAChB"}