@tanstack/preact-pacer 0.22.1 → 0.24.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 (243) hide show
  1. package/README.md +17 -2
  2. package/dist/async-batcher/useAsyncBatchedCallback.d.ts +2 -5
  3. package/dist/async-batcher/useAsyncBatchedCallback.js +1 -2
  4. package/dist/async-batcher/useAsyncBatcher.d.ts +4 -8
  5. package/dist/async-batcher/useAsyncBatcher.js +1 -3
  6. package/dist/async-debouncer/useAsyncDebouncedCallback.d.ts +6 -7
  7. package/dist/async-debouncer/useAsyncDebouncedCallback.js +5 -4
  8. package/dist/async-debouncer/useAsyncDebouncer.d.ts +4 -7
  9. package/dist/async-debouncer/useAsyncDebouncer.js +1 -2
  10. package/dist/async-queuer/useAsyncQueuedState.d.ts +4 -7
  11. package/dist/async-queuer/useAsyncQueuedState.js +3 -4
  12. package/dist/async-queuer/useAsyncQueuer.d.ts +6 -9
  13. package/dist/async-queuer/useAsyncQueuer.js +3 -4
  14. package/dist/async-rate-limiter/useAsyncRateLimitedCallback.d.ts +2 -5
  15. package/dist/async-rate-limiter/useAsyncRateLimitedCallback.js +1 -2
  16. package/dist/async-rate-limiter/useAsyncRateLimiter.d.ts +4 -7
  17. package/dist/async-rate-limiter/useAsyncRateLimiter.js +1 -2
  18. package/dist/async-throttler/useAsyncThrottledCallback.d.ts +7 -9
  19. package/dist/async-throttler/useAsyncThrottledCallback.js +6 -6
  20. package/dist/async-throttler/useAsyncThrottler.d.ts +4 -7
  21. package/dist/async-throttler/useAsyncThrottler.js +1 -2
  22. package/dist/batcher/useBatchedCallback.d.ts +2 -5
  23. package/dist/batcher/useBatchedCallback.js +1 -2
  24. package/dist/batcher/useBatcher.d.ts +6 -11
  25. package/dist/batcher/useBatcher.js +3 -6
  26. package/dist/debouncer/useDebouncedCallback.d.ts +2 -5
  27. package/dist/debouncer/useDebouncedCallback.js +1 -2
  28. package/dist/debouncer/useDebouncedState.d.ts +2 -5
  29. package/dist/debouncer/useDebouncedState.js +1 -2
  30. package/dist/debouncer/useDebouncedValue.d.ts +2 -5
  31. package/dist/debouncer/useDebouncedValue.js +1 -2
  32. package/dist/debouncer/useDebouncer.d.ts +4 -7
  33. package/dist/debouncer/useDebouncer.js +1 -2
  34. package/dist/provider/PacerProvider.d.ts +6 -13
  35. package/dist/provider/PacerProvider.js +1 -2
  36. package/dist/queuer/useQueuedState.d.ts +2 -5
  37. package/dist/queuer/useQueuedState.js +1 -2
  38. package/dist/queuer/useQueuedValue.d.ts +2 -5
  39. package/dist/queuer/useQueuedValue.js +1 -2
  40. package/dist/queuer/useQueuer.d.ts +4 -7
  41. package/dist/queuer/useQueuer.js +1 -2
  42. package/dist/rate-limiter/useRateLimitedCallback.d.ts +2 -5
  43. package/dist/rate-limiter/useRateLimitedCallback.js +1 -2
  44. package/dist/rate-limiter/useRateLimitedState.d.ts +2 -5
  45. package/dist/rate-limiter/useRateLimitedState.js +1 -2
  46. package/dist/rate-limiter/useRateLimitedValue.d.ts +2 -5
  47. package/dist/rate-limiter/useRateLimitedValue.js +1 -2
  48. package/dist/rate-limiter/useRateLimiter.d.ts +4 -7
  49. package/dist/rate-limiter/useRateLimiter.js +1 -2
  50. package/dist/throttler/useThrottledCallback.d.ts +2 -5
  51. package/dist/throttler/useThrottledCallback.js +1 -2
  52. package/dist/throttler/useThrottledState.d.ts +2 -5
  53. package/dist/throttler/useThrottledState.js +1 -2
  54. package/dist/throttler/useThrottledValue.d.ts +2 -5
  55. package/dist/throttler/useThrottledValue.js +1 -2
  56. package/dist/throttler/useThrottler.d.ts +4 -7
  57. package/dist/throttler/useThrottler.js +1 -2
  58. package/package.json +24 -72
  59. package/dist/async-batcher/index.cjs +0 -13
  60. package/dist/async-batcher/index.d.cts +0 -4
  61. package/dist/async-batcher/useAsyncBatchedCallback.cjs +0 -51
  62. package/dist/async-batcher/useAsyncBatchedCallback.cjs.map +0 -1
  63. package/dist/async-batcher/useAsyncBatchedCallback.d.cts +0 -44
  64. package/dist/async-batcher/useAsyncBatchedCallback.js.map +0 -1
  65. package/dist/async-batcher/useAsyncBatcher.cjs +0 -217
  66. package/dist/async-batcher/useAsyncBatcher.cjs.map +0 -1
  67. package/dist/async-batcher/useAsyncBatcher.d.cts +0 -224
  68. package/dist/async-batcher/useAsyncBatcher.js.map +0 -1
  69. package/dist/async-debouncer/index.cjs +0 -13
  70. package/dist/async-debouncer/index.d.cts +0 -4
  71. package/dist/async-debouncer/useAsyncDebouncedCallback.cjs +0 -50
  72. package/dist/async-debouncer/useAsyncDebouncedCallback.cjs.map +0 -1
  73. package/dist/async-debouncer/useAsyncDebouncedCallback.d.cts +0 -46
  74. package/dist/async-debouncer/useAsyncDebouncedCallback.js.map +0 -1
  75. package/dist/async-debouncer/useAsyncDebouncer.cjs +0 -195
  76. package/dist/async-debouncer/useAsyncDebouncer.cjs.map +0 -1
  77. package/dist/async-debouncer/useAsyncDebouncer.d.cts +0 -203
  78. package/dist/async-debouncer/useAsyncDebouncer.js.map +0 -1
  79. package/dist/async-queuer/index.cjs +0 -13
  80. package/dist/async-queuer/index.d.cts +0 -4
  81. package/dist/async-queuer/useAsyncQueuedState.cjs +0 -154
  82. package/dist/async-queuer/useAsyncQueuedState.cjs.map +0 -1
  83. package/dist/async-queuer/useAsyncQueuedState.d.cts +0 -151
  84. package/dist/async-queuer/useAsyncQueuedState.js.map +0 -1
  85. package/dist/async-queuer/useAsyncQueuer.cjs +0 -217
  86. package/dist/async-queuer/useAsyncQueuer.cjs.map +0 -1
  87. package/dist/async-queuer/useAsyncQueuer.d.cts +0 -224
  88. package/dist/async-queuer/useAsyncQueuer.js.map +0 -1
  89. package/dist/async-rate-limiter/index.cjs +0 -13
  90. package/dist/async-rate-limiter/index.d.cts +0 -4
  91. package/dist/async-rate-limiter/useAsyncRateLimitedCallback.cjs +0 -65
  92. package/dist/async-rate-limiter/useAsyncRateLimitedCallback.cjs.map +0 -1
  93. package/dist/async-rate-limiter/useAsyncRateLimitedCallback.d.cts +0 -61
  94. package/dist/async-rate-limiter/useAsyncRateLimitedCallback.js.map +0 -1
  95. package/dist/async-rate-limiter/useAsyncRateLimiter.cjs +0 -209
  96. package/dist/async-rate-limiter/useAsyncRateLimiter.cjs.map +0 -1
  97. package/dist/async-rate-limiter/useAsyncRateLimiter.d.cts +0 -220
  98. package/dist/async-rate-limiter/useAsyncRateLimiter.js.map +0 -1
  99. package/dist/async-retryer/index.cjs +0 -9
  100. package/dist/async-retryer/index.d.cts +0 -1
  101. package/dist/async-throttler/index.cjs +0 -13
  102. package/dist/async-throttler/index.d.cts +0 -4
  103. package/dist/async-throttler/useAsyncThrottledCallback.cjs +0 -48
  104. package/dist/async-throttler/useAsyncThrottledCallback.cjs.map +0 -1
  105. package/dist/async-throttler/useAsyncThrottledCallback.d.cts +0 -44
  106. package/dist/async-throttler/useAsyncThrottledCallback.js.map +0 -1
  107. package/dist/async-throttler/useAsyncThrottler.cjs +0 -206
  108. package/dist/async-throttler/useAsyncThrottler.cjs.map +0 -1
  109. package/dist/async-throttler/useAsyncThrottler.d.cts +0 -214
  110. package/dist/async-throttler/useAsyncThrottler.js.map +0 -1
  111. package/dist/batcher/index.cjs +0 -13
  112. package/dist/batcher/index.d.cts +0 -4
  113. package/dist/batcher/useBatchedCallback.cjs +0 -47
  114. package/dist/batcher/useBatchedCallback.cjs.map +0 -1
  115. package/dist/batcher/useBatchedCallback.d.cts +0 -42
  116. package/dist/batcher/useBatchedCallback.js.map +0 -1
  117. package/dist/batcher/useBatcher.cjs +0 -165
  118. package/dist/batcher/useBatcher.cjs.map +0 -1
  119. package/dist/batcher/useBatcher.d.cts +0 -175
  120. package/dist/batcher/useBatcher.js.map +0 -1
  121. package/dist/debouncer/index.cjs +0 -17
  122. package/dist/debouncer/index.d.cts +0 -6
  123. package/dist/debouncer/useDebouncedCallback.cjs +0 -48
  124. package/dist/debouncer/useDebouncedCallback.cjs.map +0 -1
  125. package/dist/debouncer/useDebouncedCallback.d.cts +0 -44
  126. package/dist/debouncer/useDebouncedCallback.js.map +0 -1
  127. package/dist/debouncer/useDebouncedState.cjs +0 -89
  128. package/dist/debouncer/useDebouncedState.cjs.map +0 -1
  129. package/dist/debouncer/useDebouncedState.d.cts +0 -81
  130. package/dist/debouncer/useDebouncedState.js.map +0 -1
  131. package/dist/debouncer/useDebouncedValue.cjs +0 -96
  132. package/dist/debouncer/useDebouncedValue.cjs.map +0 -1
  133. package/dist/debouncer/useDebouncedValue.d.cts +0 -90
  134. package/dist/debouncer/useDebouncedValue.js.map +0 -1
  135. package/dist/debouncer/useDebouncer.cjs +0 -141
  136. package/dist/debouncer/useDebouncer.cjs.map +0 -1
  137. package/dist/debouncer/useDebouncer.d.cts +0 -152
  138. package/dist/debouncer/useDebouncer.js.map +0 -1
  139. package/dist/index.cjs +0 -67
  140. package/dist/index.d.cts +0 -30
  141. package/dist/provider/PacerProvider.cjs +0 -26
  142. package/dist/provider/PacerProvider.cjs.map +0 -1
  143. package/dist/provider/PacerProvider.d.cts +0 -33
  144. package/dist/provider/PacerProvider.js.map +0 -1
  145. package/dist/provider/index.cjs +0 -6
  146. package/dist/provider/index.d.cts +0 -2
  147. package/dist/queuer/index.cjs +0 -15
  148. package/dist/queuer/index.d.cts +0 -5
  149. package/dist/queuer/useQueuedState.cjs +0 -129
  150. package/dist/queuer/useQueuedState.cjs.map +0 -1
  151. package/dist/queuer/useQueuedState.d.cts +0 -122
  152. package/dist/queuer/useQueuedState.js.map +0 -1
  153. package/dist/queuer/useQueuedValue.cjs +0 -115
  154. package/dist/queuer/useQueuedValue.cjs.map +0 -1
  155. package/dist/queuer/useQueuedValue.d.cts +0 -105
  156. package/dist/queuer/useQueuedValue.js.map +0 -1
  157. package/dist/queuer/useQueuer.cjs +0 -176
  158. package/dist/queuer/useQueuer.cjs.map +0 -1
  159. package/dist/queuer/useQueuer.d.cts +0 -186
  160. package/dist/queuer/useQueuer.js.map +0 -1
  161. package/dist/rate-limiter/index.cjs +0 -17
  162. package/dist/rate-limiter/index.d.cts +0 -6
  163. package/dist/rate-limiter/useRateLimitedCallback.cjs +0 -65
  164. package/dist/rate-limiter/useRateLimitedCallback.cjs.map +0 -1
  165. package/dist/rate-limiter/useRateLimitedCallback.d.cts +0 -61
  166. package/dist/rate-limiter/useRateLimitedCallback.js.map +0 -1
  167. package/dist/rate-limiter/useRateLimitedState.cjs +0 -115
  168. package/dist/rate-limiter/useRateLimitedState.cjs.map +0 -1
  169. package/dist/rate-limiter/useRateLimitedState.d.cts +0 -107
  170. package/dist/rate-limiter/useRateLimitedState.js.map +0 -1
  171. package/dist/rate-limiter/useRateLimitedValue.cjs +0 -102
  172. package/dist/rate-limiter/useRateLimitedValue.cjs.map +0 -1
  173. package/dist/rate-limiter/useRateLimitedValue.d.cts +0 -96
  174. package/dist/rate-limiter/useRateLimitedValue.js.map +0 -1
  175. package/dist/rate-limiter/useRateLimiter.cjs +0 -167
  176. package/dist/rate-limiter/useRateLimiter.cjs.map +0 -1
  177. package/dist/rate-limiter/useRateLimiter.d.cts +0 -179
  178. package/dist/rate-limiter/useRateLimiter.js.map +0 -1
  179. package/dist/throttler/index.cjs +0 -17
  180. package/dist/throttler/index.d.cts +0 -6
  181. package/dist/throttler/useThrottledCallback.cjs +0 -49
  182. package/dist/throttler/useThrottledCallback.cjs.map +0 -1
  183. package/dist/throttler/useThrottledCallback.d.cts +0 -45
  184. package/dist/throttler/useThrottledCallback.js.map +0 -1
  185. package/dist/throttler/useThrottledState.cjs +0 -100
  186. package/dist/throttler/useThrottledState.cjs.map +0 -1
  187. package/dist/throttler/useThrottledState.d.cts +0 -92
  188. package/dist/throttler/useThrottledState.js.map +0 -1
  189. package/dist/throttler/useThrottledValue.cjs +0 -91
  190. package/dist/throttler/useThrottledValue.cjs.map +0 -1
  191. package/dist/throttler/useThrottledValue.d.cts +0 -85
  192. package/dist/throttler/useThrottledValue.js.map +0 -1
  193. package/dist/throttler/useThrottler.cjs +0 -146
  194. package/dist/throttler/useThrottler.cjs.map +0 -1
  195. package/dist/throttler/useThrottler.d.cts +0 -157
  196. package/dist/throttler/useThrottler.js.map +0 -1
  197. package/dist/types/index.cjs +0 -9
  198. package/dist/types/index.d.cts +0 -1
  199. package/dist/utils/index.cjs +0 -9
  200. package/dist/utils/index.d.cts +0 -1
  201. package/src/async-batcher/index.ts +0 -4
  202. package/src/async-batcher/useAsyncBatchedCallback.ts +0 -53
  203. package/src/async-batcher/useAsyncBatcher.ts +0 -293
  204. package/src/async-debouncer/index.ts +0 -5
  205. package/src/async-debouncer/useAsyncDebouncedCallback.ts +0 -54
  206. package/src/async-debouncer/useAsyncDebouncer.ts +0 -274
  207. package/src/async-queuer/index.ts +0 -4
  208. package/src/async-queuer/useAsyncQueuedState.ts +0 -165
  209. package/src/async-queuer/useAsyncQueuer.ts +0 -293
  210. package/src/async-rate-limiter/index.ts +0 -5
  211. package/src/async-rate-limiter/useAsyncRateLimitedCallback.ts +0 -69
  212. package/src/async-rate-limiter/useAsyncRateLimiter.ts +0 -294
  213. package/src/async-retryer/index.ts +0 -2
  214. package/src/async-throttler/index.ts +0 -5
  215. package/src/async-throttler/useAsyncThrottledCallback.ts +0 -52
  216. package/src/async-throttler/useAsyncThrottler.ts +0 -285
  217. package/src/batcher/index.ts +0 -4
  218. package/src/batcher/useBatchedCallback.ts +0 -46
  219. package/src/batcher/useBatcher.ts +0 -241
  220. package/src/debouncer/index.ts +0 -7
  221. package/src/debouncer/useDebouncedCallback.ts +0 -51
  222. package/src/debouncer/useDebouncedState.ts +0 -106
  223. package/src/debouncer/useDebouncedValue.ts +0 -109
  224. package/src/debouncer/useDebouncer.ts +0 -219
  225. package/src/index.ts +0 -56
  226. package/src/provider/PacerProvider.tsx +0 -70
  227. package/src/provider/index.ts +0 -1
  228. package/src/queuer/index.ts +0 -5
  229. package/src/queuer/useQueuedState.ts +0 -133
  230. package/src/queuer/useQueuedValue.ts +0 -129
  231. package/src/queuer/useQueuer.ts +0 -251
  232. package/src/rate-limiter/index.ts +0 -6
  233. package/src/rate-limiter/useRateLimitedCallback.ts +0 -68
  234. package/src/rate-limiter/useRateLimitedState.ts +0 -124
  235. package/src/rate-limiter/useRateLimitedValue.ts +0 -110
  236. package/src/rate-limiter/useRateLimiter.ts +0 -244
  237. package/src/throttler/index.ts +0 -7
  238. package/src/throttler/useThrottledCallback.ts +0 -52
  239. package/src/throttler/useThrottledState.ts +0 -118
  240. package/src/throttler/useThrottledValue.ts +0 -104
  241. package/src/throttler/useThrottler.ts +0 -224
  242. package/src/types/index.ts +0 -1
  243. package/src/utils/index.ts +0 -1
@@ -1,293 +0,0 @@
1
- import { useEffect, useMemo, useState } from 'preact/hooks'
2
- import { AsyncBatcher } from '@tanstack/pacer/async-batcher'
3
- import { shallow, useSelector } from '@tanstack/preact-store'
4
- import { useDefaultPacerOptions } from '../provider/PacerProvider'
5
- import type { Store } from '@tanstack/preact-store'
6
- import type {
7
- AsyncBatcherOptions,
8
- AsyncBatcherState,
9
- } from '@tanstack/pacer/async-batcher'
10
- import type { ComponentChildren } from 'preact'
11
-
12
- export interface PreactAsyncBatcherOptions<
13
- TValue,
14
- TSelected = {},
15
- > extends AsyncBatcherOptions<TValue> {
16
- /**
17
- * Optional callback invoked when the component unmounts. Receives the batcher instance.
18
- * When provided, replaces the default cleanup (cancel + abort); use it to call flush(), reset(), cancel(), add logging, etc.
19
- */
20
- onUnmount?: (batcher: PreactAsyncBatcher<TValue, TSelected>) => void
21
- }
22
-
23
- export interface PreactAsyncBatcher<TValue, TSelected = {}> extends Omit<
24
- AsyncBatcher<TValue>,
25
- 'store'
26
- > {
27
- /**
28
- * A Preact HOC (Higher Order Component) that allows you to subscribe to the async batcher state.
29
- *
30
- * This is useful for opting into state re-renders for specific parts of the batcher state
31
- * deep in your component tree without needing to pass a selector to the hook.
32
- *
33
- * @example
34
- * <batcher.Subscribe selector={(state) => ({ size: state.size })}>
35
- * {({ size }) => (
36
- * <div>Batch Size: {size}</div>
37
- * )}
38
- * </batcher.Subscribe>
39
- */
40
- Subscribe: <TSelected>(props: {
41
- selector: (state: AsyncBatcherState<TValue>) => TSelected
42
- children: ((state: TSelected) => ComponentChildren) | ComponentChildren
43
- }) => ComponentChildren
44
- /**
45
- * Reactive state that will be updated and re-rendered when the batcher state changes
46
- *
47
- * Use this instead of `batcher.store.state`
48
- */
49
- readonly state: Readonly<TSelected>
50
- /**
51
- * @deprecated Use `batcher.state` instead of `batcher.store.state` if you want to read reactive state.
52
- * The state on the store object is not reactive, as it has not been wrapped in a `useSelector` hook internally.
53
- * Although, you can make the state reactive by using the `useSelector` in your own usage.
54
- */
55
- readonly store: Store<Readonly<AsyncBatcherState<TValue>>>
56
- }
57
-
58
- /**
59
- * A Preact hook that creates an `AsyncBatcher` instance for managing asynchronous batches of items.
60
- *
61
- * This is the async version of the useBatcher hook. Unlike the sync version, this async batcher:
62
- * - Handles promises and returns results from batch executions
63
- * - Provides error handling with configurable error behavior
64
- * - Tracks success, error, and settle counts separately
65
- * - Has state tracking for when batches are executing
66
- * - Returns the result of the batch function execution
67
- *
68
- * Features:
69
- * - Configurable batch size and wait time
70
- * - Custom batch processing logic via getShouldExecute
71
- * - Event callbacks for monitoring batch operations
72
- * - Error handling for failed batch operations
73
- * - Automatic or manual batch processing
74
- *
75
- * The batcher collects items and processes them in batches based on:
76
- * - Maximum batch size (number of items per batch)
77
- * - Time-based batching (process after X milliseconds)
78
- * - Custom batch processing logic via getShouldExecute
79
- *
80
- * Error Handling:
81
- * - If an `onError` handler is provided, it will be called with the error and batcher instance
82
- * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
83
- * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
84
- * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
85
- * - The error state can be checked using the underlying AsyncBatcher instance
86
- *
87
- * ## State Management and Selector
88
- *
89
- * The hook uses TanStack Store for reactive state management. You can subscribe to state changes
90
- * in two ways:
91
- *
92
- * **1. Using `batcher.Subscribe` HOC (Recommended for component tree subscriptions)**
93
- *
94
- * Use the `Subscribe` HOC to subscribe to state changes deep in your component tree without
95
- * needing to pass a selector to the hook. This is ideal when you want to subscribe to state
96
- * in child components.
97
- *
98
- * **2. Using the `selector` parameter (For hook-level subscriptions)**
99
- *
100
- * The `selector` parameter allows you to specify which state changes will trigger a re-render
101
- * at the hook level, optimizing performance by preventing unnecessary re-renders when irrelevant
102
- * state changes occur.
103
- *
104
- * **By default, there will be no reactive state subscriptions** and you must opt-in to state
105
- * tracking by providing a selector function or using the `Subscribe` HOC. This prevents unnecessary
106
- * re-renders and gives you full control over when your component updates.
107
- *
108
- * Available state properties:
109
- * - `errorCount`: Number of batch executions that have resulted in errors
110
- * - `failedItems`: Array of items that failed during batch processing
111
- * - `isEmpty`: Whether the batcher has no items to process
112
- * - `isExecuting`: Whether a batch is currently being processed asynchronously
113
- * - `isPending`: Whether the batcher is waiting for the timeout to trigger batch processing
114
- * - `isRunning`: Whether the batcher is active and will process items automatically
115
- * - `items`: Array of items currently queued for batch processing
116
- * - `lastResult`: The result from the most recent batch execution
117
- * - `settleCount`: Number of batch executions that have completed (success or error)
118
- * - `size`: Number of items currently in the batch queue
119
- * - `status`: Current processing status ('idle' | 'pending' | 'executing' | 'populated')
120
- * - `successCount`: Number of batch executions that have completed successfully
121
- * - `totalItemsProcessed`: Total number of items processed across all batches
122
- * - `totalItemsFailed`: Total number of items that have failed processing
123
- *
124
- * ## Unmount behavior
125
- *
126
- * By default, the hook cancels any pending batch and aborts any in-flight execution when the component unmounts.
127
- * Abort only cancels underlying operations (e.g. fetch) when the abort signal from `getAbortSignal()` is passed to them.
128
- * Use the `onUnmount` option to customize this. For example, to flush pending work instead:
129
- *
130
- * ```tsx
131
- * const batcher = useAsyncBatcher(fn, {
132
- * maxSize: 10,
133
- * wait: 2000,
134
- * onUnmount: (b) => b.flush()
135
- * });
136
- * ```
137
- *
138
- * Note: For async utils, `flush()` returns a Promise and runs fire-and-forget in the cleanup.
139
- * If your batch function updates Preact state, those updates may run after the component has
140
- * unmounted, which can cause "setState on unmounted component" warnings. Guard your callbacks
141
- * accordingly when using onUnmount with flush.
142
- *
143
- * @example
144
- * ```tsx
145
- * // Basic async batcher for API requests - no reactive state subscriptions
146
- * const asyncBatcher = useAsyncBatcher(
147
- * async (items) => {
148
- * const results = await Promise.all(items.map(item => processItem(item)));
149
- * return results;
150
- * },
151
- * { maxSize: 10, wait: 2000 }
152
- * );
153
- *
154
- * // Subscribe to state changes deep in component tree using Subscribe HOC
155
- * <asyncBatcher.Subscribe selector={(state) => ({ size: state.size })}>
156
- * {({ size }) => (
157
- * <div>Batch Size: {size}</div>
158
- * )}
159
- * </asyncBatcher.Subscribe>
160
- *
161
- * // Opt-in to re-render when execution state changes at hook level (optimized for loading indicators)
162
- * const asyncBatcher = useAsyncBatcher(
163
- * async (items) => {
164
- * const results = await Promise.all(items.map(item => processItem(item)));
165
- * return results;
166
- * },
167
- * { maxSize: 10, wait: 2000 },
168
- * (state) => ({
169
- * isExecuting: state.isExecuting,
170
- * isPending: state.isPending,
171
- * status: state.status
172
- * })
173
- * );
174
- *
175
- * // Opt-in to re-render when results are available (optimized for data display)
176
- * const asyncBatcher = useAsyncBatcher(
177
- * async (items) => {
178
- * const results = await Promise.all(items.map(item => processItem(item)));
179
- * return results;
180
- * },
181
- * { maxSize: 10, wait: 2000 },
182
- * (state) => ({
183
- * lastResult: state.lastResult,
184
- * successCount: state.successCount,
185
- * totalItemsProcessed: state.totalItemsProcessed
186
- * })
187
- * );
188
- *
189
- * // Opt-in to re-render when error state changes (optimized for error handling)
190
- * const asyncBatcher = useAsyncBatcher(
191
- * async (items) => {
192
- * const results = await Promise.all(items.map(item => processItem(item)));
193
- * return results;
194
- * },
195
- * {
196
- * maxSize: 10,
197
- * wait: 2000,
198
- * onError: (error) => console.error('Batch processing failed:', error)
199
- * },
200
- * (state) => ({
201
- * errorCount: state.errorCount,
202
- * failedItems: state.failedItems,
203
- * totalItemsFailed: state.totalItemsFailed
204
- * })
205
- * );
206
- *
207
- * // Complete example with all callbacks
208
- * const asyncBatcher = useAsyncBatcher(
209
- * async (items) => {
210
- * const results = await Promise.all(items.map(item => processItem(item)));
211
- * return results;
212
- * },
213
- * {
214
- * maxSize: 10,
215
- * wait: 2000,
216
- * onSuccess: (result) => {
217
- * console.log('Batch processed successfully:', result);
218
- * },
219
- * onError: (error) => {
220
- * console.error('Batch processing failed:', error);
221
- * }
222
- * }
223
- * );
224
- *
225
- * // Add items to batch
226
- * asyncBatcher.addItem(newItem);
227
- *
228
- * // Manually execute batch
229
- * const result = await asyncBatcher.execute();
230
- *
231
- * // Access the selected state (will be empty object {} unless selector provided)
232
- * const { isExecuting, lastResult, size } = asyncBatcher.state;
233
- * ```
234
- */
235
- export function useAsyncBatcher<TValue, TSelected = {}>(
236
- fn: (items: Array<TValue>) => Promise<any>,
237
- options: PreactAsyncBatcherOptions<TValue, TSelected> = {},
238
- selector: (state: AsyncBatcherState<TValue>) => TSelected = () =>
239
- ({}) as TSelected,
240
- ): PreactAsyncBatcher<TValue, TSelected> {
241
- const mergedOptions = {
242
- ...useDefaultPacerOptions().asyncBatcher,
243
- ...options,
244
- } as PreactAsyncBatcherOptions<TValue, TSelected>
245
- const [asyncBatcher] = useState(() => {
246
- const batcherInstance = new AsyncBatcher<TValue>(
247
- fn,
248
- mergedOptions,
249
- ) as unknown as PreactAsyncBatcher<TValue, TSelected>
250
-
251
- batcherInstance.Subscribe = function Subscribe<TSelected>(props: {
252
- selector: (state: AsyncBatcherState<TValue>) => TSelected
253
- children: ((state: TSelected) => ComponentChildren) | ComponentChildren
254
- }) {
255
- const selected = useSelector(batcherInstance.store, props.selector, {
256
- compare: shallow,
257
- })
258
-
259
- return typeof props.children === 'function'
260
- ? props.children(selected)
261
- : props.children
262
- }
263
-
264
- return batcherInstance
265
- })
266
-
267
- asyncBatcher.fn = fn
268
- asyncBatcher.setOptions(mergedOptions)
269
-
270
- /* eslint-disable react-hooks/exhaustive-deps -- cleanup only; runs on unmount */
271
- useEffect(() => {
272
- return () => {
273
- if (mergedOptions.onUnmount) {
274
- mergedOptions.onUnmount(asyncBatcher)
275
- } else {
276
- asyncBatcher.cancel()
277
- asyncBatcher.abort()
278
- }
279
- }
280
- }, [])
281
- /* eslint-enable react-hooks/exhaustive-deps */
282
-
283
- const state = useSelector(asyncBatcher.store, selector, { compare: shallow })
284
-
285
- return useMemo(
286
- () =>
287
- ({
288
- ...asyncBatcher,
289
- state,
290
- }) as PreactAsyncBatcher<TValue, TSelected>, // omit `store` in favor of `state`
291
- [asyncBatcher, state],
292
- )
293
- }
@@ -1,5 +0,0 @@
1
- // re-export everything from the core pacer package, BUT ONLY from the async-debouncer module
2
- export * from '@tanstack/pacer/async-debouncer'
3
-
4
- export * from './useAsyncDebouncer'
5
- export * from './useAsyncDebouncedCallback'
@@ -1,54 +0,0 @@
1
- import { useCallback } from 'preact/hooks'
2
- import { useAsyncDebouncer } from './useAsyncDebouncer'
3
- import type { PreactAsyncDebouncerOptions } from './useAsyncDebouncer'
4
- import type { AnyAsyncFunction } from '@tanstack/pacer/types'
5
-
6
- /**
7
- * A Preact hook that creates a debounced version of an async callback function.
8
- * This hook is a convenient wrapper around the `useAsyncDebouncer` hook,
9
- * providing a stable, debounced async function reference for use in Preact components.
10
- *
11
- * The debounced async function will only execute after the specified wait time has elapsed
12
- * since its last invocation. If called again before the wait time expires, the timer
13
- * resets and starts waiting again. The returned function always returns a promise
14
- * that resolves or rejects with the result of the original async function.
15
- *
16
- * This hook provides a simpler API compared to `useAsyncDebouncer`, making it ideal for basic
17
- * async debouncing needs. However, it does not expose the underlying AsyncDebouncer instance.
18
- *
19
- * For advanced usage requiring features like:
20
- * - Manual cancellation
21
- * - Access to execution/error state
22
- * - Custom useCallback dependencies
23
- *
24
- * Consider using the `useAsyncDebouncer` hook instead.
25
- *
26
- *
27
- * @example
28
- * ```tsx
29
- * // Debounce an async search handler
30
- * const handleSearch = useAsyncDebouncedCallback(async (query: string) => {
31
- * const results = await fetchSearchResults(query);
32
- * return results;
33
- * }, {
34
- * wait: 500 // Wait 500ms between executions
35
- * });
36
- *
37
- * // Use in an input
38
- * <input
39
- * type="search"
40
- * onChange={e => handleSearch(e.target.value)}
41
- * />
42
- * ```
43
- */
44
- export function useAsyncDebouncedCallback<TFn extends AnyAsyncFunction>(
45
- fn: TFn,
46
- options: PreactAsyncDebouncerOptions<TFn, {}>,
47
- ): (...args: Parameters<TFn>) => Promise<ReturnType<TFn>> {
48
- const asyncDebouncedFn = useAsyncDebouncer(fn, options).maybeExecute
49
- return useCallback(
50
- (...args: Parameters<TFn>) =>
51
- asyncDebouncedFn(...args) as Promise<ReturnType<TFn>>,
52
- [asyncDebouncedFn],
53
- )
54
- }
@@ -1,274 +0,0 @@
1
- import { useEffect, useMemo, useState } from 'preact/hooks'
2
- import { AsyncDebouncer } from '@tanstack/pacer/async-debouncer'
3
- import { shallow, useSelector } from '@tanstack/preact-store'
4
- import { useDefaultPacerOptions } from '../provider/PacerProvider'
5
- import type { Store } from '@tanstack/preact-store'
6
- import type { AnyAsyncFunction } from '@tanstack/pacer/types'
7
- import type {
8
- AsyncDebouncerOptions,
9
- AsyncDebouncerState,
10
- } from '@tanstack/pacer/async-debouncer'
11
- import type { ComponentChildren } from 'preact'
12
-
13
- export interface PreactAsyncDebouncerOptions<
14
- TFn extends AnyAsyncFunction,
15
- TSelected = {},
16
- > extends AsyncDebouncerOptions<TFn> {
17
- /**
18
- * Optional callback invoked when the component unmounts. Receives the debouncer instance.
19
- * When provided, replaces the default cleanup (cancel + abort); use it to call flush(), reset(), cancel(), add logging, etc.
20
- */
21
- onUnmount?: (debouncer: PreactAsyncDebouncer<TFn, TSelected>) => void
22
- }
23
-
24
- export interface PreactAsyncDebouncer<
25
- TFn extends AnyAsyncFunction,
26
- TSelected = {},
27
- > extends Omit<AsyncDebouncer<TFn>, 'store'> {
28
- /**
29
- * A Preact HOC (Higher Order Component) that allows you to subscribe to the async debouncer state.
30
- *
31
- * This is useful for opting into state re-renders for specific parts of the debouncer state
32
- * deep in your component tree without needing to pass a selector to the hook.
33
- *
34
- * @example
35
- * <debouncer.Subscribe selector={(state) => ({ isPending: state.isPending })}>
36
- * {({ isPending }) => (
37
- * <div>{isPending ? 'Loading...' : 'Ready'}</div>
38
- * )}
39
- * </debouncer.Subscribe>
40
- */
41
- Subscribe: <TSelected>(props: {
42
- selector: (state: AsyncDebouncerState<TFn>) => TSelected
43
- children: ((state: TSelected) => ComponentChildren) | ComponentChildren
44
- }) => ComponentChildren
45
- /**
46
- * Reactive state that will be updated and re-rendered when the debouncer state changes
47
- *
48
- * Use this instead of `debouncer.store.state`
49
- */
50
- readonly state: Readonly<TSelected>
51
- /**
52
- * @deprecated Use `debouncer.state` instead of `debouncer.store.state` if you want to read reactive state.
53
- * The state on the store object is not reactive, as it has not been wrapped in a `useSelector` hook internally.
54
- * Although, you can make the state reactive by using the `useSelector` in your own usage.
55
- */
56
- readonly store: Store<Readonly<AsyncDebouncerState<TFn>>>
57
- }
58
-
59
- /**
60
- * A low-level Preact hook that creates an `AsyncDebouncer` instance to delay execution of an async function.
61
- *
62
- * This hook is designed to be flexible and state-management agnostic - it simply returns a debouncer instance that
63
- * you can integrate with any state management solution (useState, Redux, Zustand, Jotai, etc).
64
- *
65
- * Async debouncing ensures that an async function only executes after a specified delay has passed since its last invocation.
66
- * Each new invocation resets the delay timer. This is useful for handling frequent events like window resizing
67
- * or input changes where you only want to execute the handler after the events have stopped occurring.
68
- *
69
- * Unlike throttling which allows execution at regular intervals, debouncing prevents any execution until
70
- * the function stops being called for the specified delay period.
71
- *
72
- * Unlike the non-async Debouncer, this async version supports returning values from the debounced function,
73
- * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call
74
- * instead of setting the result on a state variable from within the debounced function.
75
- *
76
- * Error Handling:
77
- * - If an `onError` handler is provided, it will be called with the error and debouncer instance
78
- * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
79
- * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
80
- * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
81
- * - The error state can be checked using the underlying AsyncDebouncer instance
82
- *
83
- * ## State Management and Selector
84
- *
85
- * The hook uses TanStack Store for reactive state management. You can subscribe to state changes
86
- * in two ways:
87
- *
88
- * **1. Using `debouncer.Subscribe` HOC (Recommended for component tree subscriptions)**
89
- *
90
- * Use the `Subscribe` HOC to subscribe to state changes deep in your component tree without
91
- * needing to pass a selector to the hook. This is ideal when you want to subscribe to state
92
- * in child components.
93
- *
94
- * **2. Using the `selector` parameter (For hook-level subscriptions)**
95
- *
96
- * The `selector` parameter allows you to specify which state changes will trigger a re-render
97
- * at the hook level, optimizing performance by preventing unnecessary re-renders when irrelevant
98
- * state changes occur.
99
- *
100
- * **By default, there will be no reactive state subscriptions** and you must opt-in to state
101
- * tracking by providing a selector function or using the `Subscribe` HOC. This prevents unnecessary
102
- * re-renders and gives you full control over when your component updates.
103
- *
104
- * Available state properties:
105
- * - `canLeadingExecute`: Whether the debouncer can execute on the leading edge
106
- * - `errorCount`: Number of function executions that have resulted in errors
107
- * - `isExecuting`: Whether the debounced function is currently executing asynchronously
108
- * - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution
109
- * - `lastArgs`: The arguments from the most recent call to maybeExecute
110
- * - `lastResult`: The result from the most recent successful function execution
111
- * - `settleCount`: Number of function executions that have completed (success or error)
112
- * - `status`: Current execution status ('disabled' | 'idle' | 'pending' | 'executing' | 'settled')
113
- * - `successCount`: Number of function executions that have completed successfully
114
- *
115
- * ## Unmount behavior
116
- *
117
- * By default, the hook cancels any pending execution and aborts any in-flight execution when the component unmounts.
118
- * Abort only cancels underlying operations (e.g. fetch) when the abort signal from `getAbortSignal()` is passed to them.
119
- * Use the `onUnmount` option to customize this. For example, to flush pending work instead:
120
- *
121
- * ```tsx
122
- * const debouncer = useAsyncDebouncer(fn, {
123
- * wait: 500,
124
- * onUnmount: (d) => d.flush()
125
- * });
126
- * ```
127
- *
128
- * Note: For async utils, `flush()` returns a Promise and runs fire-and-forget in the cleanup.
129
- * If your debounced function updates Preact state, those updates may run after the component has
130
- * unmounted, which can cause "setState on unmounted component" warnings. Guard your callbacks
131
- * accordingly when using onUnmount with flush.
132
- *
133
- * @example
134
- * ```tsx
135
- * // Default behavior - no reactive state subscriptions
136
- * const searchDebouncer = useAsyncDebouncer(
137
- * async (query: string) => {
138
- * const results = await api.search(query);
139
- * return results;
140
- * },
141
- * { wait: 500 }
142
- * );
143
- *
144
- * // Subscribe to state changes deep in component tree using Subscribe HOC
145
- * <searchDebouncer.Subscribe selector={(state) => ({ isPending: state.isPending })}>
146
- * {({ isPending }) => (
147
- * <div>{isPending ? 'Searching...' : 'Ready'}</div>
148
- * )}
149
- * </searchDebouncer.Subscribe>
150
- *
151
- * // Opt-in to re-render when execution state changes at hook level (optimized for loading indicators)
152
- * const searchDebouncer = useAsyncDebouncer(
153
- * async (query: string) => {
154
- * const results = await api.search(query);
155
- * return results;
156
- * },
157
- * { wait: 500 },
158
- * (state) => ({
159
- * isExecuting: state.isExecuting,
160
- * isPending: state.isPending
161
- * })
162
- * );
163
- *
164
- * // Opt-in to re-render when results are available (optimized for data display)
165
- * const searchDebouncer = useAsyncDebouncer(
166
- * async (query: string) => {
167
- * const results = await api.search(query);
168
- * return results;
169
- * },
170
- * { wait: 500 },
171
- * (state) => ({
172
- * lastResult: state.lastResult,
173
- * successCount: state.successCount
174
- * })
175
- * );
176
- *
177
- * // Opt-in to re-render when error state changes (optimized for error handling)
178
- * const searchDebouncer = useAsyncDebouncer(
179
- * async (query: string) => {
180
- * const results = await api.search(query);
181
- * return results;
182
- * },
183
- * {
184
- * wait: 500,
185
- * onError: (error) => console.error('Search failed:', error)
186
- * },
187
- * (state) => ({
188
- * errorCount: state.errorCount,
189
- * status: state.status
190
- * })
191
- * );
192
- *
193
- * // With state management
194
- * const [results, setResults] = useState([]);
195
- * const { maybeExecute, state } = useAsyncDebouncer(
196
- * async (searchTerm) => {
197
- * const data = await searchAPI(searchTerm);
198
- * setResults(data);
199
- * },
200
- * {
201
- * wait: 300,
202
- * leading: true, // Execute immediately on first call
203
- * trailing: false, // Skip trailing edge updates
204
- * onError: (error) => {
205
- * console.error('API call failed:', error);
206
- * }
207
- * }
208
- * );
209
- *
210
- * // Access the selected state (will be empty object {} unless selector provided)
211
- * const { isExecuting, lastResult } = state;
212
- * ```
213
- */
214
- export function useAsyncDebouncer<TFn extends AnyAsyncFunction, TSelected = {}>(
215
- fn: TFn,
216
- options: PreactAsyncDebouncerOptions<TFn, TSelected>,
217
- selector: (state: AsyncDebouncerState<TFn>) => TSelected = () =>
218
- ({}) as TSelected,
219
- ): PreactAsyncDebouncer<TFn, TSelected> {
220
- const mergedOptions = {
221
- ...useDefaultPacerOptions().asyncDebouncer,
222
- ...options,
223
- } as PreactAsyncDebouncerOptions<TFn, TSelected>
224
- const [asyncDebouncer] = useState(() => {
225
- const debouncerInstance = new AsyncDebouncer<TFn>(
226
- fn,
227
- mergedOptions,
228
- ) as unknown as PreactAsyncDebouncer<TFn, TSelected>
229
-
230
- debouncerInstance.Subscribe = function Subscribe<TSelected>(props: {
231
- selector: (state: AsyncDebouncerState<TFn>) => TSelected
232
- children: ((state: TSelected) => ComponentChildren) | ComponentChildren
233
- }) {
234
- const selected = useSelector(debouncerInstance.store, props.selector, {
235
- compare: shallow,
236
- })
237
-
238
- return typeof props.children === 'function'
239
- ? props.children(selected)
240
- : props.children
241
- }
242
-
243
- return debouncerInstance
244
- })
245
-
246
- asyncDebouncer.fn = fn
247
- asyncDebouncer.setOptions(mergedOptions)
248
-
249
- const state = useSelector(asyncDebouncer.store, selector, {
250
- compare: shallow,
251
- })
252
-
253
- /* eslint-disable react-hooks/exhaustive-deps -- cleanup only; runs on unmount */
254
- useEffect(() => {
255
- return () => {
256
- if (mergedOptions.onUnmount) {
257
- mergedOptions.onUnmount(asyncDebouncer)
258
- } else {
259
- asyncDebouncer.cancel()
260
- asyncDebouncer.abort()
261
- }
262
- }
263
- }, [])
264
- /* eslint-enable react-hooks/exhaustive-deps */
265
-
266
- return useMemo(
267
- () =>
268
- ({
269
- ...asyncDebouncer,
270
- state,
271
- }) as PreactAsyncDebouncer<TFn, TSelected>, // omit `store` in favor of `state`
272
- [asyncDebouncer, state],
273
- )
274
- }
@@ -1,4 +0,0 @@
1
- export * from '@tanstack/pacer/async-queuer'
2
-
3
- export * from './useAsyncQueuer'
4
- export * from './useAsyncQueuedState'