@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,115 +0,0 @@
1
- const require_useRateLimiter = require('./useRateLimiter.cjs');
2
- let preact_hooks = require("preact/hooks");
3
-
4
- //#region src/rate-limiter/useRateLimitedState.ts
5
- /**
6
- * A Preact hook that creates a rate-limited state value that enforces a hard limit on state updates within a time window.
7
- * This hook combines Preact's useState with rate limiting functionality to provide controlled state updates.
8
- *
9
- * Rate limiting is a simple "hard limit" approach - it allows all updates until the limit is reached, then blocks
10
- * subsequent updates until the window resets. Unlike throttling or debouncing, it does not attempt to space out
11
- * or intelligently collapse updates. This can lead to bursts of rapid updates followed by periods of no updates.
12
- *
13
- * The rate limiter supports two types of windows:
14
- * - 'fixed': A strict window that resets after the window period. All updates within the window count
15
- * towards the limit, and the window resets completely after the period.
16
- * - 'sliding': A rolling window that allows updates as old ones expire. This provides a more
17
- * consistent rate of updates over time.
18
- *
19
- * For smoother update patterns, consider:
20
- * - useThrottledState: When you want consistent spacing between updates (e.g. UI changes)
21
- * - useDebouncedState: When you want to collapse rapid updates into a single update (e.g. search input)
22
- *
23
- * Rate limiting should primarily be used when you need to enforce strict limits, like API rate limits.
24
- *
25
- * The hook returns a tuple containing:
26
- * - The rate-limited state value
27
- * - A rate-limited setter function that respects the configured limits
28
- * - The rateLimiter instance for additional control
29
- *
30
- * For more direct control over rate limiting without state management,
31
- * consider using the lower-level useRateLimiter hook instead.
32
- *
33
- * ## State Management and Selector
34
- *
35
- * The hook uses TanStack Store for reactive state management via the underlying rate limiter instance.
36
- * The `selector` parameter allows you to specify which rate limiter state changes will trigger a re-render,
37
- * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.
38
- *
39
- * **By default, there will be no reactive state subscriptions** and you must opt-in to state
40
- * tracking by providing a selector function. This prevents unnecessary re-renders and gives you
41
- * full control over when your component updates. Only when you provide a selector will the
42
- * component re-render when the selected state values change.
43
- *
44
- * Available rate limiter state properties:
45
- * - `executionCount`: Number of function executions that have been completed
46
- * - `executionTimes`: Array of timestamps when executions occurred for rate limiting calculations
47
- * - `rejectionCount`: Number of function executions that have been rejected due to rate limiting
48
- *
49
- * @example
50
- * ```tsx
51
- * // Default behavior - no reactive state subscriptions
52
- * const [value, setValue, rateLimiter] = useRateLimitedState(0, {
53
- * limit: 5,
54
- * window: 60000,
55
- * windowType: 'sliding'
56
- * });
57
- *
58
- * // Opt-in to re-render when execution count changes (optimized for tracking successful updates)
59
- * const [value, setValue, rateLimiter] = useRateLimitedState(
60
- * 0,
61
- * { limit: 5, window: 60000, windowType: 'sliding' },
62
- * (state) => ({ executionCount: state.executionCount })
63
- * );
64
- *
65
- * // Opt-in to re-render when rejection count changes (optimized for tracking rate limit violations)
66
- * const [value, setValue, rateLimiter] = useRateLimitedState(
67
- * 0,
68
- * { limit: 5, window: 60000, windowType: 'sliding' },
69
- * (state) => ({ rejectionCount: state.rejectionCount })
70
- * );
71
- *
72
- * // Opt-in to re-render when execution times change (optimized for window calculations)
73
- * const [value, setValue, rateLimiter] = useRateLimitedState(
74
- * 0,
75
- * { limit: 5, window: 60000, windowType: 'sliding' },
76
- * (state) => ({ executionTimes: state.executionTimes })
77
- * );
78
- *
79
- * // With rejection callback and fixed window
80
- * const [value, setValue] = useRateLimitedState(0, {
81
- * limit: 3,
82
- * window: 5000,
83
- * windowType: 'fixed',
84
- * onReject: (rateLimiter) => {
85
- * alert(`Rate limit reached. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
86
- * }
87
- * });
88
- *
89
- * // Access rateLimiter methods if needed
90
- * const handleSubmit = () => {
91
- * const remaining = rateLimiter.getRemainingInWindow();
92
- * if (remaining > 0) {
93
- * setValue(newValue);
94
- * } else {
95
- * showRateLimitWarning();
96
- * }
97
- * };
98
- *
99
- * // Access the selected rate limiter state (will be empty object {} unless selector provided)
100
- * const { executionCount, rejectionCount } = rateLimiter.state;
101
- * ```
102
- */
103
- function useRateLimitedState(value, options, selector) {
104
- const [rateLimitedValue, setRateLimitedValue] = (0, preact_hooks.useState)(value);
105
- const rateLimiter = require_useRateLimiter.useRateLimiter(setRateLimitedValue, options, selector);
106
- return [
107
- rateLimitedValue,
108
- rateLimiter.maybeExecute,
109
- rateLimiter
110
- ];
111
- }
112
-
113
- //#endregion
114
- exports.useRateLimitedState = useRateLimitedState;
115
- //# sourceMappingURL=useRateLimitedState.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"useRateLimitedState.cjs","names":["useRateLimiter"],"sources":["../../src/rate-limiter/useRateLimitedState.ts"],"sourcesContent":["import { useState } from 'preact/hooks'\nimport { useRateLimiter } from './useRateLimiter'\nimport type {\n PreactRateLimiter,\n PreactRateLimiterOptions,\n} from './useRateLimiter'\nimport type { Dispatch, StateUpdater } from 'preact/hooks'\nimport type { RateLimiterState } from '@tanstack/pacer/rate-limiter'\n\n/**\n * A Preact hook that creates a rate-limited state value that enforces a hard limit on state updates within a time window.\n * This hook combines Preact's useState with rate limiting functionality to provide controlled state updates.\n *\n * Rate limiting is a simple \"hard limit\" approach - it allows all updates until the limit is reached, then blocks\n * subsequent updates until the window resets. Unlike throttling or debouncing, it does not attempt to space out\n * or intelligently collapse updates. This can lead to bursts of rapid updates followed by periods of no updates.\n *\n * The rate limiter supports two types of windows:\n * - 'fixed': A strict window that resets after the window period. All updates within the window count\n * towards the limit, and the window resets completely after the period.\n * - 'sliding': A rolling window that allows updates as old ones expire. This provides a more\n * consistent rate of updates over time.\n *\n * For smoother update patterns, consider:\n * - useThrottledState: When you want consistent spacing between updates (e.g. UI changes)\n * - useDebouncedState: When you want to collapse rapid updates into a single update (e.g. search input)\n *\n * Rate limiting should primarily be used when you need to enforce strict limits, like API rate limits.\n *\n * The hook returns a tuple containing:\n * - The rate-limited state value\n * - A rate-limited setter function that respects the configured limits\n * - The rateLimiter instance for additional control\n *\n * For more direct control over rate limiting without state management,\n * consider using the lower-level useRateLimiter hook instead.\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying rate limiter instance.\n * The `selector` parameter allows you to specify which rate limiter 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 rate limiter state properties:\n * - `executionCount`: Number of function executions that have been completed\n * - `executionTimes`: Array of timestamps when executions occurred for rate limiting calculations\n * - `rejectionCount`: Number of function executions that have been rejected due to rate limiting\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [value, setValue, rateLimiter] = useRateLimitedState(0, {\n * limit: 5,\n * window: 60000,\n * windowType: 'sliding'\n * });\n *\n * // Opt-in to re-render when execution count changes (optimized for tracking successful updates)\n * const [value, setValue, rateLimiter] = useRateLimitedState(\n * 0,\n * { limit: 5, window: 60000, windowType: 'sliding' },\n * (state) => ({ executionCount: state.executionCount })\n * );\n *\n * // Opt-in to re-render when rejection count changes (optimized for tracking rate limit violations)\n * const [value, setValue, rateLimiter] = useRateLimitedState(\n * 0,\n * { limit: 5, window: 60000, windowType: 'sliding' },\n * (state) => ({ rejectionCount: state.rejectionCount })\n * );\n *\n * // Opt-in to re-render when execution times change (optimized for window calculations)\n * const [value, setValue, rateLimiter] = useRateLimitedState(\n * 0,\n * { limit: 5, window: 60000, windowType: 'sliding' },\n * (state) => ({ executionTimes: state.executionTimes })\n * );\n *\n * // With rejection callback and fixed window\n * const [value, setValue] = useRateLimitedState(0, {\n * limit: 3,\n * window: 5000,\n * windowType: 'fixed',\n * onReject: (rateLimiter) => {\n * alert(`Rate limit reached. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);\n * }\n * });\n *\n * // Access rateLimiter methods if needed\n * const handleSubmit = () => {\n * const remaining = rateLimiter.getRemainingInWindow();\n * if (remaining > 0) {\n * setValue(newValue);\n * } else {\n * showRateLimitWarning();\n * }\n * };\n *\n * // Access the selected rate limiter state (will be empty object {} unless selector provided)\n * const { executionCount, rejectionCount } = rateLimiter.state;\n * ```\n */\nexport function useRateLimitedState<TValue, TSelected = RateLimiterState>(\n value: TValue,\n options: PreactRateLimiterOptions<Dispatch<StateUpdater<TValue>>, TSelected>,\n selector?: (state: RateLimiterState) => TSelected,\n): [\n TValue,\n Dispatch<StateUpdater<TValue>>,\n PreactRateLimiter<Dispatch<StateUpdater<TValue>>, TSelected>,\n] {\n const [rateLimitedValue, setRateLimitedValue] = useState(value)\n const rateLimiter = useRateLimiter(setRateLimitedValue, options, selector)\n return [\n rateLimitedValue,\n rateLimiter.maybeExecute as Dispatch<StateUpdater<TValue>>,\n rateLimiter,\n ]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2GA,SAAgB,oBACd,OACA,SACA,UAKA;CACA,MAAM,CAAC,kBAAkB,kDAAgC,MAAM;CAC/D,MAAM,cAAcA,sCAAe,qBAAqB,SAAS,SAAS;CAC1E,OAAO;EACL;EACA,YAAY;EACZ;EACD"}
@@ -1,107 +0,0 @@
1
- import { PreactRateLimiter, PreactRateLimiterOptions } from "./useRateLimiter.cjs";
2
- import { Dispatch, StateUpdater } from "preact/hooks";
3
- import { RateLimiterState } from "@tanstack/pacer/rate-limiter";
4
-
5
- //#region src/rate-limiter/useRateLimitedState.d.ts
6
- /**
7
- * A Preact hook that creates a rate-limited state value that enforces a hard limit on state updates within a time window.
8
- * This hook combines Preact's useState with rate limiting functionality to provide controlled state updates.
9
- *
10
- * Rate limiting is a simple "hard limit" approach - it allows all updates until the limit is reached, then blocks
11
- * subsequent updates until the window resets. Unlike throttling or debouncing, it does not attempt to space out
12
- * or intelligently collapse updates. This can lead to bursts of rapid updates followed by periods of no updates.
13
- *
14
- * The rate limiter supports two types of windows:
15
- * - 'fixed': A strict window that resets after the window period. All updates within the window count
16
- * towards the limit, and the window resets completely after the period.
17
- * - 'sliding': A rolling window that allows updates as old ones expire. This provides a more
18
- * consistent rate of updates over time.
19
- *
20
- * For smoother update patterns, consider:
21
- * - useThrottledState: When you want consistent spacing between updates (e.g. UI changes)
22
- * - useDebouncedState: When you want to collapse rapid updates into a single update (e.g. search input)
23
- *
24
- * Rate limiting should primarily be used when you need to enforce strict limits, like API rate limits.
25
- *
26
- * The hook returns a tuple containing:
27
- * - The rate-limited state value
28
- * - A rate-limited setter function that respects the configured limits
29
- * - The rateLimiter instance for additional control
30
- *
31
- * For more direct control over rate limiting without state management,
32
- * consider using the lower-level useRateLimiter hook instead.
33
- *
34
- * ## State Management and Selector
35
- *
36
- * The hook uses TanStack Store for reactive state management via the underlying rate limiter instance.
37
- * The `selector` parameter allows you to specify which rate limiter state changes will trigger a re-render,
38
- * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.
39
- *
40
- * **By default, there will be no reactive state subscriptions** and you must opt-in to state
41
- * tracking by providing a selector function. This prevents unnecessary re-renders and gives you
42
- * full control over when your component updates. Only when you provide a selector will the
43
- * component re-render when the selected state values change.
44
- *
45
- * Available rate limiter state properties:
46
- * - `executionCount`: Number of function executions that have been completed
47
- * - `executionTimes`: Array of timestamps when executions occurred for rate limiting calculations
48
- * - `rejectionCount`: Number of function executions that have been rejected due to rate limiting
49
- *
50
- * @example
51
- * ```tsx
52
- * // Default behavior - no reactive state subscriptions
53
- * const [value, setValue, rateLimiter] = useRateLimitedState(0, {
54
- * limit: 5,
55
- * window: 60000,
56
- * windowType: 'sliding'
57
- * });
58
- *
59
- * // Opt-in to re-render when execution count changes (optimized for tracking successful updates)
60
- * const [value, setValue, rateLimiter] = useRateLimitedState(
61
- * 0,
62
- * { limit: 5, window: 60000, windowType: 'sliding' },
63
- * (state) => ({ executionCount: state.executionCount })
64
- * );
65
- *
66
- * // Opt-in to re-render when rejection count changes (optimized for tracking rate limit violations)
67
- * const [value, setValue, rateLimiter] = useRateLimitedState(
68
- * 0,
69
- * { limit: 5, window: 60000, windowType: 'sliding' },
70
- * (state) => ({ rejectionCount: state.rejectionCount })
71
- * );
72
- *
73
- * // Opt-in to re-render when execution times change (optimized for window calculations)
74
- * const [value, setValue, rateLimiter] = useRateLimitedState(
75
- * 0,
76
- * { limit: 5, window: 60000, windowType: 'sliding' },
77
- * (state) => ({ executionTimes: state.executionTimes })
78
- * );
79
- *
80
- * // With rejection callback and fixed window
81
- * const [value, setValue] = useRateLimitedState(0, {
82
- * limit: 3,
83
- * window: 5000,
84
- * windowType: 'fixed',
85
- * onReject: (rateLimiter) => {
86
- * alert(`Rate limit reached. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
87
- * }
88
- * });
89
- *
90
- * // Access rateLimiter methods if needed
91
- * const handleSubmit = () => {
92
- * const remaining = rateLimiter.getRemainingInWindow();
93
- * if (remaining > 0) {
94
- * setValue(newValue);
95
- * } else {
96
- * showRateLimitWarning();
97
- * }
98
- * };
99
- *
100
- * // Access the selected rate limiter state (will be empty object {} unless selector provided)
101
- * const { executionCount, rejectionCount } = rateLimiter.state;
102
- * ```
103
- */
104
- declare function useRateLimitedState<TValue, TSelected = RateLimiterState>(value: TValue, options: PreactRateLimiterOptions<Dispatch<StateUpdater<TValue>>, TSelected>, selector?: (state: RateLimiterState) => TSelected): [TValue, Dispatch<StateUpdater<TValue>>, PreactRateLimiter<Dispatch<StateUpdater<TValue>>, TSelected>];
105
- //#endregion
106
- export { useRateLimitedState };
107
- //# sourceMappingURL=useRateLimitedState.d.cts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"useRateLimitedState.js","names":[],"sources":["../../src/rate-limiter/useRateLimitedState.ts"],"sourcesContent":["import { useState } from 'preact/hooks'\nimport { useRateLimiter } from './useRateLimiter'\nimport type {\n PreactRateLimiter,\n PreactRateLimiterOptions,\n} from './useRateLimiter'\nimport type { Dispatch, StateUpdater } from 'preact/hooks'\nimport type { RateLimiterState } from '@tanstack/pacer/rate-limiter'\n\n/**\n * A Preact hook that creates a rate-limited state value that enforces a hard limit on state updates within a time window.\n * This hook combines Preact's useState with rate limiting functionality to provide controlled state updates.\n *\n * Rate limiting is a simple \"hard limit\" approach - it allows all updates until the limit is reached, then blocks\n * subsequent updates until the window resets. Unlike throttling or debouncing, it does not attempt to space out\n * or intelligently collapse updates. This can lead to bursts of rapid updates followed by periods of no updates.\n *\n * The rate limiter supports two types of windows:\n * - 'fixed': A strict window that resets after the window period. All updates within the window count\n * towards the limit, and the window resets completely after the period.\n * - 'sliding': A rolling window that allows updates as old ones expire. This provides a more\n * consistent rate of updates over time.\n *\n * For smoother update patterns, consider:\n * - useThrottledState: When you want consistent spacing between updates (e.g. UI changes)\n * - useDebouncedState: When you want to collapse rapid updates into a single update (e.g. search input)\n *\n * Rate limiting should primarily be used when you need to enforce strict limits, like API rate limits.\n *\n * The hook returns a tuple containing:\n * - The rate-limited state value\n * - A rate-limited setter function that respects the configured limits\n * - The rateLimiter instance for additional control\n *\n * For more direct control over rate limiting without state management,\n * consider using the lower-level useRateLimiter hook instead.\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying rate limiter instance.\n * The `selector` parameter allows you to specify which rate limiter 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 rate limiter state properties:\n * - `executionCount`: Number of function executions that have been completed\n * - `executionTimes`: Array of timestamps when executions occurred for rate limiting calculations\n * - `rejectionCount`: Number of function executions that have been rejected due to rate limiting\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [value, setValue, rateLimiter] = useRateLimitedState(0, {\n * limit: 5,\n * window: 60000,\n * windowType: 'sliding'\n * });\n *\n * // Opt-in to re-render when execution count changes (optimized for tracking successful updates)\n * const [value, setValue, rateLimiter] = useRateLimitedState(\n * 0,\n * { limit: 5, window: 60000, windowType: 'sliding' },\n * (state) => ({ executionCount: state.executionCount })\n * );\n *\n * // Opt-in to re-render when rejection count changes (optimized for tracking rate limit violations)\n * const [value, setValue, rateLimiter] = useRateLimitedState(\n * 0,\n * { limit: 5, window: 60000, windowType: 'sliding' },\n * (state) => ({ rejectionCount: state.rejectionCount })\n * );\n *\n * // Opt-in to re-render when execution times change (optimized for window calculations)\n * const [value, setValue, rateLimiter] = useRateLimitedState(\n * 0,\n * { limit: 5, window: 60000, windowType: 'sliding' },\n * (state) => ({ executionTimes: state.executionTimes })\n * );\n *\n * // With rejection callback and fixed window\n * const [value, setValue] = useRateLimitedState(0, {\n * limit: 3,\n * window: 5000,\n * windowType: 'fixed',\n * onReject: (rateLimiter) => {\n * alert(`Rate limit reached. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);\n * }\n * });\n *\n * // Access rateLimiter methods if needed\n * const handleSubmit = () => {\n * const remaining = rateLimiter.getRemainingInWindow();\n * if (remaining > 0) {\n * setValue(newValue);\n * } else {\n * showRateLimitWarning();\n * }\n * };\n *\n * // Access the selected rate limiter state (will be empty object {} unless selector provided)\n * const { executionCount, rejectionCount } = rateLimiter.state;\n * ```\n */\nexport function useRateLimitedState<TValue, TSelected = RateLimiterState>(\n value: TValue,\n options: PreactRateLimiterOptions<Dispatch<StateUpdater<TValue>>, TSelected>,\n selector?: (state: RateLimiterState) => TSelected,\n): [\n TValue,\n Dispatch<StateUpdater<TValue>>,\n PreactRateLimiter<Dispatch<StateUpdater<TValue>>, TSelected>,\n] {\n const [rateLimitedValue, setRateLimitedValue] = useState(value)\n const rateLimiter = useRateLimiter(setRateLimitedValue, options, selector)\n return [\n rateLimitedValue,\n rateLimiter.maybeExecute as Dispatch<StateUpdater<TValue>>,\n rateLimiter,\n ]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2GA,SAAgB,oBACd,OACA,SACA,UAKA;CACA,MAAM,CAAC,kBAAkB,uBAAuB,SAAS,MAAM;CAC/D,MAAM,cAAc,eAAe,qBAAqB,SAAS,SAAS;CAC1E,OAAO;EACL;EACA,YAAY;EACZ;EACD"}
@@ -1,102 +0,0 @@
1
- const require_useRateLimitedState = require('./useRateLimitedState.cjs');
2
- let preact_hooks = require("preact/hooks");
3
-
4
- //#region src/rate-limiter/useRateLimitedValue.ts
5
- /**
6
- * A high-level Preact hook that creates a rate-limited version of a value that updates at most a certain number of times within a time window.
7
- * This hook uses Preact's useState internally to manage the rate-limited state.
8
- *
9
- * Rate limiting is a simple "hard limit" approach - it allows all updates until the limit is reached, then blocks
10
- * subsequent updates until the window resets. Unlike throttling or debouncing, it does not attempt to space out
11
- * or intelligently collapse updates. This can lead to bursts of rapid updates followed by periods of no updates.
12
- *
13
- * The rate limiter supports two types of windows:
14
- * - 'fixed': A strict window that resets after the window period. All updates within the window count
15
- * towards the limit, and the window resets completely after the period.
16
- * - 'sliding': A rolling window that allows updates as old ones expire. This provides a more
17
- * consistent rate of updates over time.
18
- *
19
- * For smoother update patterns, consider:
20
- * - useThrottledValue: When you want consistent spacing between updates (e.g. UI changes)
21
- * - useDebouncedValue: When you want to collapse rapid updates into a single update (e.g. search input)
22
- *
23
- * Rate limiting should primarily be used when you need to enforce strict limits, like API rate limits.
24
- *
25
- * The hook returns a tuple containing:
26
- * - The rate-limited value that updates according to the configured rate limit
27
- * - The rate limiter instance with control methods
28
- *
29
- * For more direct control over rate limiting behavior without Preact state management,
30
- * consider using the lower-level useRateLimiter hook instead.
31
- *
32
- * ## State Management and Selector
33
- *
34
- * The hook uses TanStack Store for reactive state management via the underlying rate limiter instance.
35
- * The `selector` parameter allows you to specify which rate limiter state changes will trigger a re-render,
36
- * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.
37
- *
38
- * **By default, there will be no reactive state subscriptions** and you must opt-in to state
39
- * tracking by providing a selector function. This prevents unnecessary re-renders and gives you
40
- * full control over when your component updates. Only when you provide a selector will the
41
- * component re-render when the selected state values change.
42
- *
43
- * Available rate limiter state properties:
44
- * - `executionCount`: Number of function executions that have been completed
45
- * - `executionTimes`: Array of timestamps when executions occurred for rate limiting calculations
46
- * - `rejectionCount`: Number of function executions that have been rejected due to rate limiting
47
- *
48
- * @example
49
- * ```tsx
50
- * // Default behavior - no reactive state subscriptions
51
- * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(rawValue, {
52
- * limit: 5,
53
- * window: 60000,
54
- * windowType: 'sliding'
55
- * });
56
- *
57
- * // Opt-in to re-render when execution count changes (optimized for tracking successful updates)
58
- * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(
59
- * rawValue,
60
- * { limit: 5, window: 60000, windowType: 'sliding' },
61
- * (state) => ({ executionCount: state.executionCount })
62
- * );
63
- *
64
- * // Opt-in to re-render when rejection count changes (optimized for tracking rate limit violations)
65
- * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(
66
- * rawValue,
67
- * { limit: 5, window: 60000, windowType: 'sliding' },
68
- * (state) => ({ rejectionCount: state.rejectionCount })
69
- * );
70
- *
71
- * // Opt-in to re-render when execution times change (optimized for window calculations)
72
- * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(
73
- * rawValue,
74
- * { limit: 5, window: 60000, windowType: 'sliding' },
75
- * (state) => ({ executionTimes: state.executionTimes })
76
- * );
77
- *
78
- * // With rejection callback and fixed window
79
- * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(rawValue, {
80
- * limit: 3,
81
- * window: 5000,
82
- * windowType: 'fixed',
83
- * onReject: (rateLimiter) => {
84
- * console.log(`Update rejected. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
85
- * }
86
- * });
87
- *
88
- * // Access the selected rate limiter state (will be empty object {} unless selector provided)
89
- * const { executionCount, rejectionCount } = rateLimiter.state;
90
- * ```
91
- */
92
- function useRateLimitedValue(value, options, selector) {
93
- const [rateLimitedValue, setRateLimitedValue, rateLimiter] = require_useRateLimitedState.useRateLimitedState(value, options, selector);
94
- (0, preact_hooks.useEffect)(() => {
95
- setRateLimitedValue(value);
96
- }, [value, setRateLimitedValue]);
97
- return [rateLimitedValue, rateLimiter];
98
- }
99
-
100
- //#endregion
101
- exports.useRateLimitedValue = useRateLimitedValue;
102
- //# sourceMappingURL=useRateLimitedValue.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"useRateLimitedValue.cjs","names":["useRateLimitedState"],"sources":["../../src/rate-limiter/useRateLimitedValue.ts"],"sourcesContent":["import { useEffect } from 'preact/hooks'\nimport { useRateLimitedState } from './useRateLimitedState'\nimport type {\n PreactRateLimiter,\n PreactRateLimiterOptions,\n} from './useRateLimiter'\nimport type { Dispatch, StateUpdater } from 'preact/hooks'\nimport type { RateLimiterState } from '@tanstack/pacer/rate-limiter'\n\n/**\n * A high-level Preact hook that creates a rate-limited version of a value that updates at most a certain number of times within a time window.\n * This hook uses Preact's useState internally to manage the rate-limited state.\n *\n * Rate limiting is a simple \"hard limit\" approach - it allows all updates until the limit is reached, then blocks\n * subsequent updates until the window resets. Unlike throttling or debouncing, it does not attempt to space out\n * or intelligently collapse updates. This can lead to bursts of rapid updates followed by periods of no updates.\n *\n * The rate limiter supports two types of windows:\n * - 'fixed': A strict window that resets after the window period. All updates within the window count\n * towards the limit, and the window resets completely after the period.\n * - 'sliding': A rolling window that allows updates as old ones expire. This provides a more\n * consistent rate of updates over time.\n *\n * For smoother update patterns, consider:\n * - useThrottledValue: When you want consistent spacing between updates (e.g. UI changes)\n * - useDebouncedValue: When you want to collapse rapid updates into a single update (e.g. search input)\n *\n * Rate limiting should primarily be used when you need to enforce strict limits, like API rate limits.\n *\n * The hook returns a tuple containing:\n * - The rate-limited value that updates according to the configured rate limit\n * - The rate limiter instance with control methods\n *\n * For more direct control over rate limiting behavior without Preact state management,\n * consider using the lower-level useRateLimiter hook instead.\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying rate limiter instance.\n * The `selector` parameter allows you to specify which rate limiter 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 rate limiter state properties:\n * - `executionCount`: Number of function executions that have been completed\n * - `executionTimes`: Array of timestamps when executions occurred for rate limiting calculations\n * - `rejectionCount`: Number of function executions that have been rejected due to rate limiting\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(rawValue, {\n * limit: 5,\n * window: 60000,\n * windowType: 'sliding'\n * });\n *\n * // Opt-in to re-render when execution count changes (optimized for tracking successful updates)\n * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(\n * rawValue,\n * { limit: 5, window: 60000, windowType: 'sliding' },\n * (state) => ({ executionCount: state.executionCount })\n * );\n *\n * // Opt-in to re-render when rejection count changes (optimized for tracking rate limit violations)\n * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(\n * rawValue,\n * { limit: 5, window: 60000, windowType: 'sliding' },\n * (state) => ({ rejectionCount: state.rejectionCount })\n * );\n *\n * // Opt-in to re-render when execution times change (optimized for window calculations)\n * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(\n * rawValue,\n * { limit: 5, window: 60000, windowType: 'sliding' },\n * (state) => ({ executionTimes: state.executionTimes })\n * );\n *\n * // With rejection callback and fixed window\n * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(rawValue, {\n * limit: 3,\n * window: 5000,\n * windowType: 'fixed',\n * onReject: (rateLimiter) => {\n * console.log(`Update rejected. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);\n * }\n * });\n *\n * // Access the selected rate limiter state (will be empty object {} unless selector provided)\n * const { executionCount, rejectionCount } = rateLimiter.state;\n * ```\n */\nexport function useRateLimitedValue<TValue, TSelected = RateLimiterState>(\n value: TValue,\n options: PreactRateLimiterOptions<Dispatch<StateUpdater<TValue>>, TSelected>,\n selector?: (state: RateLimiterState) => TSelected,\n): [TValue, PreactRateLimiter<Dispatch<StateUpdater<TValue>>, TSelected>] {\n const [rateLimitedValue, setRateLimitedValue, rateLimiter] =\n useRateLimitedState(value, options, selector)\n\n useEffect(() => {\n ;(setRateLimitedValue as (value: TValue) => void)(value)\n }, [value, setRateLimitedValue])\n\n return [rateLimitedValue, rateLimiter]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgGA,SAAgB,oBACd,OACA,SACA,UACwE;CACxE,MAAM,CAAC,kBAAkB,qBAAqB,eAC5CA,gDAAoB,OAAO,SAAS,SAAS;CAE/C,kCAAgB;EACb,AAAC,oBAAgD,MAAM;IACvD,CAAC,OAAO,oBAAoB,CAAC;CAEhC,OAAO,CAAC,kBAAkB,YAAY"}
@@ -1,96 +0,0 @@
1
- import { PreactRateLimiter, PreactRateLimiterOptions } from "./useRateLimiter.cjs";
2
- import { Dispatch, StateUpdater } from "preact/hooks";
3
- import { RateLimiterState } from "@tanstack/pacer/rate-limiter";
4
-
5
- //#region src/rate-limiter/useRateLimitedValue.d.ts
6
- /**
7
- * A high-level Preact hook that creates a rate-limited version of a value that updates at most a certain number of times within a time window.
8
- * This hook uses Preact's useState internally to manage the rate-limited state.
9
- *
10
- * Rate limiting is a simple "hard limit" approach - it allows all updates until the limit is reached, then blocks
11
- * subsequent updates until the window resets. Unlike throttling or debouncing, it does not attempt to space out
12
- * or intelligently collapse updates. This can lead to bursts of rapid updates followed by periods of no updates.
13
- *
14
- * The rate limiter supports two types of windows:
15
- * - 'fixed': A strict window that resets after the window period. All updates within the window count
16
- * towards the limit, and the window resets completely after the period.
17
- * - 'sliding': A rolling window that allows updates as old ones expire. This provides a more
18
- * consistent rate of updates over time.
19
- *
20
- * For smoother update patterns, consider:
21
- * - useThrottledValue: When you want consistent spacing between updates (e.g. UI changes)
22
- * - useDebouncedValue: When you want to collapse rapid updates into a single update (e.g. search input)
23
- *
24
- * Rate limiting should primarily be used when you need to enforce strict limits, like API rate limits.
25
- *
26
- * The hook returns a tuple containing:
27
- * - The rate-limited value that updates according to the configured rate limit
28
- * - The rate limiter instance with control methods
29
- *
30
- * For more direct control over rate limiting behavior without Preact state management,
31
- * consider using the lower-level useRateLimiter hook instead.
32
- *
33
- * ## State Management and Selector
34
- *
35
- * The hook uses TanStack Store for reactive state management via the underlying rate limiter instance.
36
- * The `selector` parameter allows you to specify which rate limiter state changes will trigger a re-render,
37
- * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.
38
- *
39
- * **By default, there will be no reactive state subscriptions** and you must opt-in to state
40
- * tracking by providing a selector function. This prevents unnecessary re-renders and gives you
41
- * full control over when your component updates. Only when you provide a selector will the
42
- * component re-render when the selected state values change.
43
- *
44
- * Available rate limiter state properties:
45
- * - `executionCount`: Number of function executions that have been completed
46
- * - `executionTimes`: Array of timestamps when executions occurred for rate limiting calculations
47
- * - `rejectionCount`: Number of function executions that have been rejected due to rate limiting
48
- *
49
- * @example
50
- * ```tsx
51
- * // Default behavior - no reactive state subscriptions
52
- * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(rawValue, {
53
- * limit: 5,
54
- * window: 60000,
55
- * windowType: 'sliding'
56
- * });
57
- *
58
- * // Opt-in to re-render when execution count changes (optimized for tracking successful updates)
59
- * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(
60
- * rawValue,
61
- * { limit: 5, window: 60000, windowType: 'sliding' },
62
- * (state) => ({ executionCount: state.executionCount })
63
- * );
64
- *
65
- * // Opt-in to re-render when rejection count changes (optimized for tracking rate limit violations)
66
- * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(
67
- * rawValue,
68
- * { limit: 5, window: 60000, windowType: 'sliding' },
69
- * (state) => ({ rejectionCount: state.rejectionCount })
70
- * );
71
- *
72
- * // Opt-in to re-render when execution times change (optimized for window calculations)
73
- * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(
74
- * rawValue,
75
- * { limit: 5, window: 60000, windowType: 'sliding' },
76
- * (state) => ({ executionTimes: state.executionTimes })
77
- * );
78
- *
79
- * // With rejection callback and fixed window
80
- * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(rawValue, {
81
- * limit: 3,
82
- * window: 5000,
83
- * windowType: 'fixed',
84
- * onReject: (rateLimiter) => {
85
- * console.log(`Update rejected. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
86
- * }
87
- * });
88
- *
89
- * // Access the selected rate limiter state (will be empty object {} unless selector provided)
90
- * const { executionCount, rejectionCount } = rateLimiter.state;
91
- * ```
92
- */
93
- declare function useRateLimitedValue<TValue, TSelected = RateLimiterState>(value: TValue, options: PreactRateLimiterOptions<Dispatch<StateUpdater<TValue>>, TSelected>, selector?: (state: RateLimiterState) => TSelected): [TValue, PreactRateLimiter<Dispatch<StateUpdater<TValue>>, TSelected>];
94
- //#endregion
95
- export { useRateLimitedValue };
96
- //# sourceMappingURL=useRateLimitedValue.d.cts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"useRateLimitedValue.js","names":[],"sources":["../../src/rate-limiter/useRateLimitedValue.ts"],"sourcesContent":["import { useEffect } from 'preact/hooks'\nimport { useRateLimitedState } from './useRateLimitedState'\nimport type {\n PreactRateLimiter,\n PreactRateLimiterOptions,\n} from './useRateLimiter'\nimport type { Dispatch, StateUpdater } from 'preact/hooks'\nimport type { RateLimiterState } from '@tanstack/pacer/rate-limiter'\n\n/**\n * A high-level Preact hook that creates a rate-limited version of a value that updates at most a certain number of times within a time window.\n * This hook uses Preact's useState internally to manage the rate-limited state.\n *\n * Rate limiting is a simple \"hard limit\" approach - it allows all updates until the limit is reached, then blocks\n * subsequent updates until the window resets. Unlike throttling or debouncing, it does not attempt to space out\n * or intelligently collapse updates. This can lead to bursts of rapid updates followed by periods of no updates.\n *\n * The rate limiter supports two types of windows:\n * - 'fixed': A strict window that resets after the window period. All updates within the window count\n * towards the limit, and the window resets completely after the period.\n * - 'sliding': A rolling window that allows updates as old ones expire. This provides a more\n * consistent rate of updates over time.\n *\n * For smoother update patterns, consider:\n * - useThrottledValue: When you want consistent spacing between updates (e.g. UI changes)\n * - useDebouncedValue: When you want to collapse rapid updates into a single update (e.g. search input)\n *\n * Rate limiting should primarily be used when you need to enforce strict limits, like API rate limits.\n *\n * The hook returns a tuple containing:\n * - The rate-limited value that updates according to the configured rate limit\n * - The rate limiter instance with control methods\n *\n * For more direct control over rate limiting behavior without Preact state management,\n * consider using the lower-level useRateLimiter hook instead.\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying rate limiter instance.\n * The `selector` parameter allows you to specify which rate limiter 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 rate limiter state properties:\n * - `executionCount`: Number of function executions that have been completed\n * - `executionTimes`: Array of timestamps when executions occurred for rate limiting calculations\n * - `rejectionCount`: Number of function executions that have been rejected due to rate limiting\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(rawValue, {\n * limit: 5,\n * window: 60000,\n * windowType: 'sliding'\n * });\n *\n * // Opt-in to re-render when execution count changes (optimized for tracking successful updates)\n * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(\n * rawValue,\n * { limit: 5, window: 60000, windowType: 'sliding' },\n * (state) => ({ executionCount: state.executionCount })\n * );\n *\n * // Opt-in to re-render when rejection count changes (optimized for tracking rate limit violations)\n * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(\n * rawValue,\n * { limit: 5, window: 60000, windowType: 'sliding' },\n * (state) => ({ rejectionCount: state.rejectionCount })\n * );\n *\n * // Opt-in to re-render when execution times change (optimized for window calculations)\n * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(\n * rawValue,\n * { limit: 5, window: 60000, windowType: 'sliding' },\n * (state) => ({ executionTimes: state.executionTimes })\n * );\n *\n * // With rejection callback and fixed window\n * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(rawValue, {\n * limit: 3,\n * window: 5000,\n * windowType: 'fixed',\n * onReject: (rateLimiter) => {\n * console.log(`Update rejected. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);\n * }\n * });\n *\n * // Access the selected rate limiter state (will be empty object {} unless selector provided)\n * const { executionCount, rejectionCount } = rateLimiter.state;\n * ```\n */\nexport function useRateLimitedValue<TValue, TSelected = RateLimiterState>(\n value: TValue,\n options: PreactRateLimiterOptions<Dispatch<StateUpdater<TValue>>, TSelected>,\n selector?: (state: RateLimiterState) => TSelected,\n): [TValue, PreactRateLimiter<Dispatch<StateUpdater<TValue>>, TSelected>] {\n const [rateLimitedValue, setRateLimitedValue, rateLimiter] =\n useRateLimitedState(value, options, selector)\n\n useEffect(() => {\n ;(setRateLimitedValue as (value: TValue) => void)(value)\n }, [value, setRateLimitedValue])\n\n return [rateLimitedValue, rateLimiter]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgGA,SAAgB,oBACd,OACA,SACA,UACwE;CACxE,MAAM,CAAC,kBAAkB,qBAAqB,eAC5C,oBAAoB,OAAO,SAAS,SAAS;CAE/C,gBAAgB;EACb,AAAC,oBAAgD,MAAM;IACvD,CAAC,OAAO,oBAAoB,CAAC;CAEhC,OAAO,CAAC,kBAAkB,YAAY"}
@@ -1,167 +0,0 @@
1
- const require_PacerProvider = require('../provider/PacerProvider.cjs');
2
- let preact_hooks = require("preact/hooks");
3
- let _tanstack_preact_store = require("@tanstack/preact-store");
4
- let _tanstack_pacer_rate_limiter = require("@tanstack/pacer/rate-limiter");
5
-
6
- //#region src/rate-limiter/useRateLimiter.ts
7
- /**
8
- * A low-level Preact hook that creates a `RateLimiter` instance to enforce rate limits on function execution.
9
- *
10
- * This hook is designed to be flexible and state-management agnostic - it simply returns a rate limiter instance that
11
- * you can integrate with any state management solution (useState, Redux, Zustand, Jotai, etc).
12
- *
13
- * Rate limiting is a simple "hard limit" approach that allows executions until a maximum count is reached within
14
- * a time window, then blocks all subsequent calls until the window resets. Unlike throttling or debouncing,
15
- * it does not attempt to space out or collapse executions intelligently.
16
- *
17
- * The rate limiter supports two types of windows:
18
- * - 'fixed': A strict window that resets after the window period. All executions within the window count
19
- * towards the limit, and the window resets completely after the period.
20
- * - 'sliding': A rolling window that allows executions as old ones expire. This provides a more
21
- * consistent rate of execution over time.
22
- *
23
- * For smoother execution patterns:
24
- * - Use throttling when you want consistent spacing between executions (e.g. UI updates)
25
- * - Use debouncing when you want to collapse rapid-fire events (e.g. search input)
26
- * - Use rate limiting only when you need to enforce hard limits (e.g. API rate limits)
27
- *
28
- * ## State Management and Selector
29
- *
30
- * The hook uses TanStack Store for reactive state management. You can subscribe to state changes
31
- * in two ways:
32
- *
33
- * **1. Using `rateLimiter.Subscribe` HOC (Recommended for component tree subscriptions)**
34
- *
35
- * Use the `Subscribe` HOC to subscribe to state changes deep in your component tree without
36
- * needing to pass a selector to the hook. This is ideal when you want to subscribe to state
37
- * in child components.
38
- *
39
- * **2. Using the `selector` parameter (For hook-level subscriptions)**
40
- *
41
- * The `selector` parameter allows you to specify which state changes will trigger a re-render
42
- * at the hook level, optimizing performance by preventing unnecessary re-renders when irrelevant
43
- * state changes occur.
44
- *
45
- * **By default, there will be no reactive state subscriptions** and you must opt-in to state
46
- * tracking by providing a selector function or using the `Subscribe` HOC. This prevents unnecessary
47
- * re-renders and gives you full control over when your component updates.
48
- *
49
- * Available state properties:
50
- * - `executionCount`: Number of function executions that have been completed
51
- * - `executionTimes`: Array of timestamps when executions occurred for rate limiting calculations
52
- * - `rejectionCount`: Number of function executions that have been rejected due to rate limiting
53
- *
54
- * The hook returns an object containing:
55
- * - maybeExecute: The rate-limited function that respects the configured limits
56
- * - getExecutionCount: Returns the number of successful executions
57
- * - getRejectionCount: Returns the number of rejected executions due to rate limiting
58
- * - getRemainingInWindow: Returns how many more executions are allowed in the current window
59
- * - reset: Resets the execution counts and window timing
60
- *
61
- * @example
62
- * ```tsx
63
- * // Default behavior - no reactive state subscriptions
64
- * const rateLimiter = useRateLimiter(apiCall, {
65
- * limit: 5,
66
- * window: 60000,
67
- * windowType: 'sliding',
68
- * });
69
- *
70
- * // Subscribe to state changes deep in component tree using Subscribe HOC
71
- * <rateLimiter.Subscribe selector={(state) => ({ rejectionCount: state.rejectionCount })}>
72
- * {({ rejectionCount }) => (
73
- * <div>Rejections: {rejectionCount}</div>
74
- * )}
75
- * </rateLimiter.Subscribe>
76
- *
77
- * // Opt-in to re-render when execution count changes at hook level (optimized for tracking successful executions)
78
- * const rateLimiter = useRateLimiter(
79
- * apiCall,
80
- * {
81
- * limit: 5,
82
- * window: 60000,
83
- * windowType: 'sliding',
84
- * },
85
- * (state) => ({ executionCount: state.executionCount })
86
- * );
87
- *
88
- * // Opt-in to re-render when rejection count changes (optimized for tracking rate limit violations)
89
- * const rateLimiter = useRateLimiter(
90
- * apiCall,
91
- * {
92
- * limit: 5,
93
- * window: 60000,
94
- * windowType: 'sliding',
95
- * },
96
- * (state) => ({ rejectionCount: state.rejectionCount })
97
- * );
98
- *
99
- * // Opt-in to re-render when execution times change (optimized for window calculations)
100
- * const rateLimiter = useRateLimiter(
101
- * apiCall,
102
- * {
103
- * limit: 5,
104
- * window: 60000,
105
- * windowType: 'sliding',
106
- * },
107
- * (state) => ({ executionTimes: state.executionTimes })
108
- * );
109
- *
110
- * // Multiple state properties - re-render when any of these change
111
- * const rateLimiter = useRateLimiter(
112
- * apiCall,
113
- * {
114
- * limit: 5,
115
- * window: 60000,
116
- * windowType: 'sliding',
117
- * },
118
- * (state) => ({
119
- * executionCount: state.executionCount,
120
- * rejectionCount: state.rejectionCount
121
- * })
122
- * );
123
- *
124
- * // Monitor rate limit status
125
- * const handleClick = () => {
126
- * const remaining = rateLimiter.getRemainingInWindow();
127
- * if (remaining > 0) {
128
- * rateLimiter.maybeExecute(data);
129
- * } else {
130
- * showRateLimitWarning();
131
- * }
132
- * };
133
- *
134
- * // Access the selected state (will be empty object {} unless selector provided)
135
- * const { executionCount, rejectionCount } = rateLimiter.state;
136
- * ```
137
- */
138
- function useRateLimiter(fn, options, selector = () => ({})) {
139
- const mergedOptions = {
140
- ...require_PacerProvider.useDefaultPacerOptions().rateLimiter,
141
- ...options
142
- };
143
- const [rateLimiter] = (0, preact_hooks.useState)(() => {
144
- const rateLimiterInstance = new _tanstack_pacer_rate_limiter.RateLimiter(fn, mergedOptions);
145
- rateLimiterInstance.Subscribe = function Subscribe(props) {
146
- const selected = (0, _tanstack_preact_store.useSelector)(rateLimiterInstance.store, props.selector, { compare: _tanstack_preact_store.shallow });
147
- return typeof props.children === "function" ? props.children(selected) : props.children;
148
- };
149
- return rateLimiterInstance;
150
- });
151
- rateLimiter.fn = fn;
152
- rateLimiter.setOptions(mergedOptions);
153
- (0, preact_hooks.useEffect)(() => {
154
- return () => {
155
- if (mergedOptions.onUnmount) mergedOptions.onUnmount(rateLimiter);
156
- };
157
- }, []);
158
- const state = (0, _tanstack_preact_store.useSelector)(rateLimiter.store, selector, { compare: _tanstack_preact_store.shallow });
159
- return (0, preact_hooks.useMemo)(() => ({
160
- ...rateLimiter,
161
- state
162
- }), [rateLimiter, state]);
163
- }
164
-
165
- //#endregion
166
- exports.useRateLimiter = useRateLimiter;
167
- //# sourceMappingURL=useRateLimiter.cjs.map