@okikio/observables 1.0.2

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 (131) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +578 -0
  3. package/esm/_dnt.polyfills.d.ts +20 -0
  4. package/esm/_dnt.polyfills.d.ts.map +1 -0
  5. package/esm/_dnt.polyfills.js +12 -0
  6. package/esm/_spec.d.ts +260 -0
  7. package/esm/_spec.d.ts.map +1 -0
  8. package/esm/_spec.js +1 -0
  9. package/esm/_types.d.ts +141 -0
  10. package/esm/_types.d.ts.map +1 -0
  11. package/esm/_types.js +20 -0
  12. package/esm/error.d.ts +331 -0
  13. package/esm/error.d.ts.map +1 -0
  14. package/esm/error.js +408 -0
  15. package/esm/events.d.ts +320 -0
  16. package/esm/events.d.ts.map +1 -0
  17. package/esm/events.js +451 -0
  18. package/esm/helpers/_types.d.ts +188 -0
  19. package/esm/helpers/_types.d.ts.map +1 -0
  20. package/esm/helpers/_types.js +1 -0
  21. package/esm/helpers/mod.d.ts +90 -0
  22. package/esm/helpers/mod.d.ts.map +1 -0
  23. package/esm/helpers/mod.js +90 -0
  24. package/esm/helpers/operations/batch.d.ts +109 -0
  25. package/esm/helpers/operations/batch.d.ts.map +1 -0
  26. package/esm/helpers/operations/batch.js +140 -0
  27. package/esm/helpers/operations/combination.d.ts +162 -0
  28. package/esm/helpers/operations/combination.d.ts.map +1 -0
  29. package/esm/helpers/operations/combination.js +350 -0
  30. package/esm/helpers/operations/conditional.d.ts +211 -0
  31. package/esm/helpers/operations/conditional.d.ts.map +1 -0
  32. package/esm/helpers/operations/conditional.js +280 -0
  33. package/esm/helpers/operations/core.d.ts +198 -0
  34. package/esm/helpers/operations/core.d.ts.map +1 -0
  35. package/esm/helpers/operations/core.js +264 -0
  36. package/esm/helpers/operations/errors.d.ts +277 -0
  37. package/esm/helpers/operations/errors.d.ts.map +1 -0
  38. package/esm/helpers/operations/errors.js +378 -0
  39. package/esm/helpers/operations/mod.d.ts +26 -0
  40. package/esm/helpers/operations/mod.d.ts.map +1 -0
  41. package/esm/helpers/operations/mod.js +25 -0
  42. package/esm/helpers/operations/timing.d.ts +206 -0
  43. package/esm/helpers/operations/timing.d.ts.map +1 -0
  44. package/esm/helpers/operations/timing.js +457 -0
  45. package/esm/helpers/operators.d.ts +520 -0
  46. package/esm/helpers/operators.d.ts.map +1 -0
  47. package/esm/helpers/operators.js +563 -0
  48. package/esm/helpers/pipe.d.ts +118 -0
  49. package/esm/helpers/pipe.d.ts.map +1 -0
  50. package/esm/helpers/pipe.js +129 -0
  51. package/esm/helpers/utils.d.ts +142 -0
  52. package/esm/helpers/utils.d.ts.map +1 -0
  53. package/esm/helpers/utils.js +193 -0
  54. package/esm/mod.d.ts +863 -0
  55. package/esm/mod.d.ts.map +1 -0
  56. package/esm/mod.js +861 -0
  57. package/esm/observable.d.ts +1610 -0
  58. package/esm/observable.d.ts.map +1 -0
  59. package/esm/observable.js +1970 -0
  60. package/esm/package.json +3 -0
  61. package/esm/queue.d.ts +201 -0
  62. package/esm/queue.d.ts.map +1 -0
  63. package/esm/queue.js +273 -0
  64. package/esm/symbol.d.ts +60 -0
  65. package/esm/symbol.d.ts.map +1 -0
  66. package/esm/symbol.js +132 -0
  67. package/package.json +96 -0
  68. package/script/_dnt.polyfills.d.ts +20 -0
  69. package/script/_dnt.polyfills.d.ts.map +1 -0
  70. package/script/_dnt.polyfills.js +13 -0
  71. package/script/_spec.d.ts +260 -0
  72. package/script/_spec.d.ts.map +1 -0
  73. package/script/_spec.js +2 -0
  74. package/script/_types.d.ts +141 -0
  75. package/script/_types.d.ts.map +1 -0
  76. package/script/_types.js +22 -0
  77. package/script/error.d.ts +331 -0
  78. package/script/error.d.ts.map +1 -0
  79. package/script/error.js +414 -0
  80. package/script/events.d.ts +320 -0
  81. package/script/events.d.ts.map +1 -0
  82. package/script/events.js +458 -0
  83. package/script/helpers/_types.d.ts +188 -0
  84. package/script/helpers/_types.d.ts.map +1 -0
  85. package/script/helpers/_types.js +2 -0
  86. package/script/helpers/mod.d.ts +90 -0
  87. package/script/helpers/mod.d.ts.map +1 -0
  88. package/script/helpers/mod.js +106 -0
  89. package/script/helpers/operations/batch.d.ts +109 -0
  90. package/script/helpers/operations/batch.d.ts.map +1 -0
  91. package/script/helpers/operations/batch.js +144 -0
  92. package/script/helpers/operations/combination.d.ts +162 -0
  93. package/script/helpers/operations/combination.d.ts.map +1 -0
  94. package/script/helpers/operations/combination.js +355 -0
  95. package/script/helpers/operations/conditional.d.ts +211 -0
  96. package/script/helpers/operations/conditional.d.ts.map +1 -0
  97. package/script/helpers/operations/conditional.js +286 -0
  98. package/script/helpers/operations/core.d.ts +198 -0
  99. package/script/helpers/operations/core.d.ts.map +1 -0
  100. package/script/helpers/operations/core.js +272 -0
  101. package/script/helpers/operations/errors.d.ts +277 -0
  102. package/script/helpers/operations/errors.d.ts.map +1 -0
  103. package/script/helpers/operations/errors.js +387 -0
  104. package/script/helpers/operations/mod.d.ts +26 -0
  105. package/script/helpers/operations/mod.d.ts.map +1 -0
  106. package/script/helpers/operations/mod.js +41 -0
  107. package/script/helpers/operations/timing.d.ts +206 -0
  108. package/script/helpers/operations/timing.d.ts.map +1 -0
  109. package/script/helpers/operations/timing.js +464 -0
  110. package/script/helpers/operators.d.ts +520 -0
  111. package/script/helpers/operators.d.ts.map +1 -0
  112. package/script/helpers/operators.js +570 -0
  113. package/script/helpers/pipe.d.ts +118 -0
  114. package/script/helpers/pipe.d.ts.map +1 -0
  115. package/script/helpers/pipe.js +132 -0
  116. package/script/helpers/utils.d.ts +142 -0
  117. package/script/helpers/utils.d.ts.map +1 -0
  118. package/script/helpers/utils.js +200 -0
  119. package/script/mod.d.ts +863 -0
  120. package/script/mod.d.ts.map +1 -0
  121. package/script/mod.js +877 -0
  122. package/script/observable.d.ts +1610 -0
  123. package/script/observable.d.ts.map +1 -0
  124. package/script/observable.js +1984 -0
  125. package/script/package.json +3 -0
  126. package/script/queue.d.ts +201 -0
  127. package/script/queue.d.ts.map +1 -0
  128. package/script/queue.js +286 -0
  129. package/script/symbol.d.ts +60 -0
  130. package/script/symbol.d.ts.map +1 -0
  131. package/script/symbol.js +135 -0
@@ -0,0 +1,378 @@
1
+ /**
2
+ * Error-focused operators for recovering from or reshaping stream failures.
3
+ *
4
+ * This entrypoint is for pipelines that expect some work to fail and want to
5
+ * keep going. It exports helpers for dropping wrapped errors, mapping them to
6
+ * fallback values, logging them, or converting them into a shape that fits the
7
+ * rest of the pipeline.
8
+ *
9
+ * These operators are most useful with the library's pass-through error mode,
10
+ * where failures travel as `ObservableError` values instead of immediately
11
+ * terminating the whole stream.
12
+ *
13
+ * @module
14
+ */
15
+ import "../../_dnt.polyfills.js";
16
+ import { isObservableError, ObservableError } from "../../error.js";
17
+ import { createOperator, createStatefulOperator } from "../operators.js";
18
+ /**
19
+ * Removes all errors from the stream, keeping only successful data.
20
+ *
21
+ * Like a filter that only allows non-error values to pass. It's a simple way
22
+ * to clean up a stream when you don't need to handle failures.
23
+ *
24
+ * @example
25
+ * ```ts
26
+ * import { pipe, ignoreErrors, from } from "./helpers/mod.ts";
27
+ *
28
+ * // Array behavior (conceptual)
29
+ * const mixedData = [1, new Error("fail"), 2, 3];
30
+ * const goodData = mixedData.filter(item => !(item instanceof Error)); // [1, 2, 3]
31
+ *
32
+ * // Stream behavior
33
+ * const sourceStream = from([1, new ObservableError("fail"), 2, 3]);
34
+ * const cleanStream = pipe(sourceStream, ignoreErrors()); // Emits 1, 2, 3
35
+ * ```
36
+ *
37
+ * ## Practical Use Case
38
+ *
39
+ * Use `ignoreErrors` when processing a batch of items where some failures are
40
+ * expected and acceptable. For example, fetching a list of URLs where some
41
+ * might be broken. You only want to process the ones that work.
42
+ *
43
+ * ## Key Insight
44
+ *
45
+ * `ignoreErrors` provides a "fire-and-forget" approach to error handling. It's
46
+ * useful for non-critical tasks or when partial success is sufficient.
47
+ *
48
+ * @template T The type of good data in your stream
49
+ * @returns A stream operator that silently removes all errors
50
+ */
51
+ export function ignoreErrors() {
52
+ return createOperator({
53
+ name: "ignoreErrors",
54
+ errorMode: "ignore",
55
+ transform(chunk, controller) {
56
+ controller.enqueue(chunk);
57
+ // Errors are silently dropped
58
+ },
59
+ });
60
+ }
61
+ /**
62
+ * Replaces any error in the stream with a fallback value.
63
+ *
64
+ * Like a `try...catch` block for each item in a stream, but instead of just
65
+ * handling the error, you provide a default value to take its place.
66
+ *
67
+ * @example
68
+ * ```ts
69
+ * import { pipe, catchErrors, from } from "./helpers/mod.ts";
70
+ *
71
+ * // Conceptual equivalent
72
+ * function process(item) {
73
+ * try {
74
+ * if (item instanceof Error) throw item;
75
+ * return item;
76
+ * } catch {
77
+ * return "default";
78
+ * }
79
+ * }
80
+ * const results = [1, new Error("fail")].map(process); // [1, "default"]
81
+ *
82
+ * // Stream behavior
83
+ * const sourceStream = from([1, new ObservableError("fail")]);
84
+ * const safeStream = pipe(sourceStream, catchErrors("default")); // Emits 1, "default"
85
+ * ```
86
+ *
87
+ * ## Practical Use Case
88
+ *
89
+ * Use `catchErrors` to provide a default state or value when an operation
90
+ * fails. For example, if fetching a user's profile fails, you could return a
91
+ * default "Guest" profile instead of letting the error propagate.
92
+ *
93
+ * ## Key Insight
94
+ *
95
+ * `catchErrors` ensures your stream continues with a predictable structure,
96
+ * even when individual operations fail. It maintains the flow of data by
97
+ * substituting errors with safe, default values.
98
+ *
99
+ * @template T The type of data in your stream.
100
+ * @template R The type of the fallback value.
101
+ * @param fallback The value to use whenever an error occurs.
102
+ * @returns A stream operator that replaces errors with a fallback value.
103
+ */
104
+ export function catchErrors(fallback) {
105
+ return createOperator({
106
+ name: "catchErrors",
107
+ errorMode: "manual",
108
+ transform(chunk, controller) {
109
+ if (isObservableError(chunk)) {
110
+ controller.enqueue(fallback);
111
+ }
112
+ else {
113
+ controller.enqueue(chunk);
114
+ }
115
+ },
116
+ });
117
+ }
118
+ /**
119
+ * Transforms errors into custom values using a mapping function.
120
+ *
121
+ * This is a more powerful version of `catchErrors`. Instead of a single
122
+ * fallback, you can inspect each error and decide what to replace it with.
123
+ *
124
+ * @example
125
+ * ```ts
126
+ * import { pipe, mapErrors, from } from "./helpers/mod.ts";
127
+ *
128
+ * // Stream behavior
129
+ * const sourceStream = from([
130
+ * 1,
131
+ * new ObservableError("Not Found"),
132
+ * new ObservableError("Server Error")
133
+ * ]);
134
+ *
135
+ * const handledStream = pipe(
136
+ * sourceStream,
137
+ * mapErrors(err => {
138
+ * if (err.message === "Not Found") return { status: 404 };
139
+ * return { status: 500 };
140
+ * })
141
+ * );
142
+ * // Emits 1, { status: 404 }, { status: 500 }
143
+ * ```
144
+ *
145
+ * ## Practical Use Case
146
+ *
147
+ * Use `mapErrors` to convert different types of errors into meaningful data.
148
+ * For example, a "Not Found" error could be mapped to `null`, while a "Server
149
+ * Error" could be mapped to an object that triggers a retry mechanism.
150
+ *
151
+ * ## Key Insight
152
+ *
153
+ * `mapErrors` treats errors as data. It allows you to create a resilient
154
+ * stream that can intelligently respond to different failure modes without
155
+ * stopping.
156
+ *
157
+ * @template T The type of successful data in your stream.
158
+ * @template E The type your errors will be mapped to.
159
+ * @param errorMapper A function that receives an error and returns a new value.
160
+ * @returns A stream operator that transforms errors.
161
+ */
162
+ export function mapErrors(errorMapper) {
163
+ return createOperator({
164
+ name: "mapErrors",
165
+ errorMode: "manual",
166
+ transform(chunk, controller) {
167
+ if (isObservableError(chunk)) {
168
+ try {
169
+ const mappedError = errorMapper(chunk);
170
+ controller.enqueue(mappedError);
171
+ }
172
+ catch (mapperError) {
173
+ controller.error(new ObservableError([mapperError, chunk], `Your error mapper function threw an error: ${mapperError}`, {
174
+ operator: "operator:mapErrors:mapper",
175
+ value: mapperError,
176
+ cause: chunk,
177
+ tip: "The function passed to mapErrors threw an error. Check its implementation.",
178
+ }));
179
+ }
180
+ }
181
+ else {
182
+ controller.enqueue(chunk);
183
+ }
184
+ },
185
+ });
186
+ }
187
+ /**
188
+ * Keeps only the errors from the stream, discarding successful data.
189
+ *
190
+ * This is the inverse of `ignoreErrors`. It's useful for creating a dedicated
191
+ * error-handling pipeline.
192
+ *
193
+ * @example
194
+ * ```ts
195
+ * import { pipe, onlyErrors, from } from "./helpers/mod.ts";
196
+ *
197
+ * // Stream behavior
198
+ * const sourceStream = from([1, new ObservableError("fail"), 2]);
199
+ * const errorStream = pipe(sourceStream, onlyErrors()); // Emits ObservableError("fail")
200
+ * ```
201
+ *
202
+ * ## Practical Use Case
203
+ *
204
+ * Use `onlyErrors` to separate the error stream from the data stream. You can
205
+ * then log these errors, send them to a monitoring service, or trigger alerts
206
+ * without interfering with the main data processing flow.
207
+ *
208
+ * ## Key Insight
209
+ *
210
+ * `onlyErrors` allows you to create a side-channel for failures, enabling
211
+ * robust monitoring and debugging.
212
+ *
213
+ * @template T The type of data in the source stream.
214
+ * @returns An operator that filters for errors.
215
+ */
216
+ export function onlyErrors() {
217
+ return createOperator({
218
+ name: "onlyErrors",
219
+ errorMode: "manual",
220
+ transform(chunk, controller) {
221
+ if (isObservableError(chunk)) {
222
+ controller.enqueue(chunk);
223
+ }
224
+ // Good data is discarded
225
+ },
226
+ });
227
+ }
228
+ /**
229
+ * Summarizes the stream into a final count of successes and errors.
230
+ *
231
+ * This operator waits for the stream to complete and then emits a single
232
+ * object with the total counts.
233
+ *
234
+ * @example
235
+ * ```ts
236
+ * import { pipe, summarizeErrors, from } from "./helpers/mod.ts";
237
+ *
238
+ * // Stream behavior
239
+ * const sourceStream = from([1, new ObservableError("fail"), 2, 3]);
240
+ * const summary = await pipe(sourceStream, summarizeErrors()).toPromise();
241
+ * // { successCount: 3, errorCount: 1, totalProcessed: 4, successRate: 0.75 }
242
+ * ```
243
+ *
244
+ * ## Practical Use Case
245
+ *
246
+ * Use `summarizeErrors` at the end of a batch processing job to get a report
247
+ * on how many items were processed successfully and how many failed. This is
248
+
249
+ * useful for logging, monitoring, and generating reports.
250
+ *
251
+ * ## Key Insight
252
+ *
253
+ * `summarizeErrors` is a terminal operator that provides a high-level overview
254
+ * of a stream's health and completeness.
255
+ *
256
+ * @template T The type of data in the source stream.
257
+ * @returns An operator that emits a summary of successes and errors.
258
+ */
259
+ export function summarizeErrors() {
260
+ return createStatefulOperator({
261
+ name: "summarizeErrors",
262
+ errorMode: "manual",
263
+ createState: () => ({ successCount: 0, errorCount: 0 }),
264
+ transform(chunk, state) {
265
+ if (isObservableError(chunk)) {
266
+ state.errorCount++;
267
+ }
268
+ else {
269
+ state.successCount++;
270
+ }
271
+ },
272
+ flush(state, controller) {
273
+ const total = state.successCount + state.errorCount;
274
+ controller.enqueue({
275
+ successCount: state.successCount,
276
+ errorCount: state.errorCount,
277
+ totalProcessed: total,
278
+ successRate: total > 0 ? state.successCount / total : 0,
279
+ });
280
+ },
281
+ });
282
+ }
283
+ /**
284
+ * Performs a side effect for each error without modifying the stream.
285
+ *
286
+ * Like `Array.prototype.forEach` but only for errors. It's useful for logging
287
+ * or debugging without altering the data flow.
288
+ *
289
+ * @example
290
+ * ```ts
291
+ * import { pipe, tapError, from } from "./helpers/mod.ts";
292
+ *
293
+ * // Stream behavior
294
+ * const sourceStream = from([1, new ObservableError("fail")]);
295
+ * const tappedStream = pipe(
296
+ * sourceStream,
297
+ * tapError(err => console.error("Found an error:", err))
298
+ * );
299
+ * // Logs the error, then emits 1 and the error object.
300
+ * ```
301
+ *
302
+ * ## Practical Use Case
303
+ *
304
+ * Use `tapError` to log errors to the console or a monitoring service as they
305
+ * happen, without stopping or changing the stream. This is invaluable for
306
+ * real-time debugging.
307
+ *
308
+ * ## Key Insight
309
+ *
310
+ * `tapError` gives you a window into the stream's errors without affecting the
311
+ * stream itself.
312
+ *
313
+ * @template T The type of data in the stream.
314
+ * @param sideEffect A function to call for each error.
315
+ * @returns An operator that performs a side effect on errors.
316
+ */
317
+ export function tapError(sideEffect) {
318
+ return createOperator({
319
+ name: "tapError",
320
+ errorMode: "manual",
321
+ transform(chunk, controller) {
322
+ try {
323
+ if (isObservableError(chunk)) {
324
+ sideEffect(chunk);
325
+ }
326
+ }
327
+ catch (_) {
328
+ /* no empty */
329
+ }
330
+ finally {
331
+ controller.enqueue(chunk);
332
+ }
333
+ },
334
+ });
335
+ }
336
+ /**
337
+ * Throws an error if it encounters one in the stream.
338
+ *
339
+ * This operator is useful for enforcing strict error handling. If an error is
340
+ * encountered, it will throw immediately, stopping the iteration.
341
+ *
342
+ * @example
343
+ * ```ts
344
+ * import { pipe, throwErrors, from } from "./helpers/mod.ts";
345
+ *
346
+ * // Stream behavior
347
+ * const sourceStream = from([1, new ObservableError("fail"), 2]);
348
+ * const throwingStream = pipe(sourceStream, throwErrors());
349
+ *
350
+ * for await (const item of throwingStream) {
351
+ * console.log(item); // Will log 1, then throw on "fail"
352
+ * }
353
+ * ```
354
+ *
355
+ * ## Practical Use Case
356
+ *
357
+ * Use `throwErrors` when you want to ensure that any error in the stream is
358
+ * treated as a critical failure. This is useful in scenarios where errors must
359
+ * be handled immediately and cannot be ignored.
360
+ *
361
+ * ## Key Insight
362
+ *
363
+ * `throwErrors` provides a way to enforce strict error handling in streams,
364
+ * ensuring that no errors go unnoticed.
365
+ *
366
+ * @template T The type of data in the stream.
367
+ * @returns An operator that throws on errors.
368
+ */
369
+ export function throwErrors() {
370
+ return createOperator({
371
+ name: "throwErrors",
372
+ errorMode: "throw",
373
+ transform(chunk, controller) {
374
+ // If it's an error, this will automatically throw due to errorMode: "throw"
375
+ controller.enqueue(chunk);
376
+ },
377
+ });
378
+ }
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Category-level entrypoint for the built-in Observable operations.
3
+ *
4
+ * This module gathers every operator category that powers the higher-level
5
+ * `./operators` entrypoint. It is useful when you want a focused import path
6
+ * for documentation and discovery, but still want access to the full built-in
7
+ * operator set from one module.
8
+ *
9
+ * The re-exports are grouped by job:
10
+ * - `./core` covers the array-like transformations and terminal operators
11
+ * - `./timing` covers time-based coordination such as debounce and timeout
12
+ * - `./combination` covers flattening and concurrency helpers such as
13
+ * `mergeMap`, `concatMap`, and `switchMap`
14
+ * - `./batch`, `./conditional`, and `./errors` cover collection, predicate, and
15
+ * recovery-focused utilities
16
+ *
17
+ * @module
18
+ */
19
+ import "../../_dnt.polyfills.js";
20
+ export * from "./batch.js";
21
+ export * from "./combination.js";
22
+ export * from "./conditional.js";
23
+ export * from "./core.js";
24
+ export * from "./errors.js";
25
+ export * from "./timing.js";
26
+ //# sourceMappingURL=mod.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../src/helpers/operations/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,yBAAyB,CAAC;AAEjC,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Category-level entrypoint for the built-in Observable operations.
3
+ *
4
+ * This module gathers every operator category that powers the higher-level
5
+ * `./operators` entrypoint. It is useful when you want a focused import path
6
+ * for documentation and discovery, but still want access to the full built-in
7
+ * operator set from one module.
8
+ *
9
+ * The re-exports are grouped by job:
10
+ * - `./core` covers the array-like transformations and terminal operators
11
+ * - `./timing` covers time-based coordination such as debounce and timeout
12
+ * - `./combination` covers flattening and concurrency helpers such as
13
+ * `mergeMap`, `concatMap`, and `switchMap`
14
+ * - `./batch`, `./conditional`, and `./errors` cover collection, predicate, and
15
+ * recovery-focused utilities
16
+ *
17
+ * @module
18
+ */
19
+ import "../../_dnt.polyfills.js";
20
+ export * from "./batch.js";
21
+ export * from "./combination.js";
22
+ export * from "./conditional.js";
23
+ export * from "./core.js";
24
+ export * from "./errors.js";
25
+ export * from "./timing.js";
@@ -0,0 +1,206 @@
1
+ /**
2
+ * Time-based operators for spacing, delaying, and expiring stream values.
3
+ *
4
+ * This entrypoint groups the operators that make time part of your pipeline's
5
+ * behavior. Use it for UI patterns such as debouncing search input, throttling
6
+ * bursty events, delaying retries, or timing out work that takes too long.
7
+ *
8
+ * Timing operators do not just change values; they change when work is allowed
9
+ * to move downstream. That makes them especially important for coordinating
10
+ * async side effects without piling up stale requests or overwhelming slower
11
+ * consumers.
12
+ *
13
+ * @module
14
+ */
15
+ import "../../_dnt.polyfills.js";
16
+ import type { Operator } from "../_types.js";
17
+ import { ObservableError } from "../../error.js";
18
+ /**
19
+ * Delays each item in the stream by a specified number of milliseconds.
20
+ *
21
+ * This operator shifts the entire stream of events forward in time, preserving
22
+ * the relative time between them.
23
+ *
24
+ * > Note: This does not delay error emissions. If an error occurs, it will
25
+ * > be emitted immediately, regardless of the delay.
26
+ *
27
+ * @example
28
+ * ```ts
29
+ * import { pipe, delay, from } from "./helpers/mod.ts";
30
+ *
31
+ * // No direct Array equivalent, as it's about timing.
32
+ *
33
+ * // Stream behavior
34
+ * const sourceStream = from([1, 2, 3]);
35
+ * const delayedStream = pipe(sourceStream, delay(1000));
36
+ * // Emits 1 (after 1s), then 2 (immediately after), then 3 (immediately after).
37
+ * ```
38
+ *
39
+ * ## Practical Use Case
40
+ *
41
+ * Use `delay` to simulate network latency in tests, or to introduce a small
42
+ * pause in a UI animation sequence to make it feel more natural.
43
+ *
44
+ * ## Key Insight
45
+ *
46
+ * `delay` is about shifting the timeline of events, not about pausing between
47
+ * them. It's a simple way to control when a stream begins to emit its values.
48
+ *
49
+ * @typeParam T - Type of values from the source stream
50
+ * @param ms - The delay duration in milliseconds
51
+ * @returns A stream operator that delays each value
52
+ */
53
+ export declare function delay<T>(ms: number): Operator<T | ObservableError, T | ObservableError>;
54
+ /**
55
+ * Delays each individual item by a specified number of milliseconds.
56
+ *
57
+ * This operator delays every item independently, preserving the relative
58
+ * spacing between them while shifting each one forward by the same amount.
59
+ * Think of it as "adding X milliseconds to each item's timestamp."
60
+ *
61
+ * > Note: This does not delay error emissions. If an error occurs, it will
62
+ * > be emitted immediately, regardless of the delay.
63
+ *
64
+ * @example
65
+ * ```ts
66
+ * import { pipe, delayEach, from } from "./helpers/mod.ts";
67
+ *
68
+ * // Stream behavior
69
+ * const sourceStream = from([1, 2, 3]); // Items at T+0, T+100, T+200
70
+ * const delayedStream = pipe(sourceStream, delayEach(1000));
71
+ * // Emits 1 (at T+1000), 2 (at T+1100), 3 (at T+1200)
72
+ * ```
73
+ *
74
+ * ## Practical Use Case
75
+ *
76
+ * Use `delayEach` to simulate processing time for each item, or to add
77
+ * consistent lag to every operation (useful for testing race conditions
78
+ * or simulating network latency per request).
79
+ *
80
+ * ## Key Insight
81
+ *
82
+ * `delayEach` maintains the original spacing between items while shifting
83
+ * each one. For delaying the entire stream timeline, use `delay` instead.
84
+ *
85
+ * @typeParam T - Type of values from the source stream
86
+ * @param ms - The delay duration in milliseconds for each item
87
+ * @returns A stream operator that delays each value individually
88
+ */
89
+ export declare function delayEach<T>(ms: number): Operator<T | ObservableError, T | ObservableError>;
90
+ /**
91
+ * Emits only the latest item after a specified period of inactivity.
92
+ *
93
+ * This is the "search bar" operator. It waits for the user to stop typing
94
+ * before firing off a search query.
95
+ *
96
+ * > Note: This operator does not delay error emissions. If an error occurs,
97
+ * > it will be emitted immediately, regardless of the debounce period.
98
+ *
99
+ * @example
100
+ * ```ts
101
+ * import { pipe, debounce, from } from "./helpers/mod.ts";
102
+ *
103
+ * // No direct Array equivalent.
104
+ *
105
+ * // Stream behavior
106
+ * const inputStream = from(["a", "ab", "abc"]); // User typing quickly
107
+ * const debouncedStream = pipe(inputStream, debounce(300));
108
+ * // After 300ms of no new input, it will emit "abc".
109
+ * ```
110
+ *
111
+ * ## Practical Use Case
112
+ *
113
+ * Use `debounce` for any event that fires rapidly, but you only care about the
114
+ * final value, such as search inputs, window resize events, or auto-saving
115
+ * form fields.
116
+ *
117
+ * ## Key Insight
118
+ *
119
+ * `debounce` filters out noise from rapid-fire events, ensuring that expensive
120
+ * operations (like API calls) are only triggered when necessary.
121
+ *
122
+ * @typeParam T - Type of values from the source stream
123
+ * @param ms - The debounce duration in milliseconds
124
+ * @returns A stream operator that debounces values
125
+ */
126
+ export declare function debounce<T>(ms: number): Operator<T | ObservableError, T | ObservableError>;
127
+ /**
128
+ * Limits the stream to emit at most one item per specified time interval.
129
+ *
130
+ * This is the "scroll event" operator. It ensures that even if an event fires
131
+ * hundreds of times per second, you only handle it at a manageable rate.
132
+ *
133
+ * @example
134
+ * ```ts
135
+ * import { pipe, throttle, from } from "./helpers/mod.ts";
136
+ *
137
+ * // No direct Array equivalent.
138
+ *
139
+ * // Stream behavior
140
+ * const scrollStream = from([10, 20, 50, 100, 150]); // Scroll events
141
+ * const throttledStream = pipe(scrollStream, throttle(100));
142
+ * // Emits 10 immediately, then waits 100ms before being able to emit again.
143
+ * // If 150 is the last value, it will be emitted after the throttle window.
144
+ * ```
145
+ *
146
+ * ## Practical Use Case
147
+ *
148
+ * Use `throttle` for high-frequency events where you need to guarantee a
149
+ * regular sampling of the data, such as scroll position tracking, mouse
150
+ * movement, or real-time data visualization.
151
+ *
152
+ * ## Key Insight
153
+ *
154
+ * `throttle` guarantees a steady flow of data, unlike `debounce` which waits
155
+ * for silence. It's about rate-limiting, not just handling the final value.
156
+ *
157
+ * @typeParam T - Type of values from the source stream
158
+ * @param ms - The throttle duration in milliseconds
159
+ * @returns A stream operator that throttles values
160
+ */
161
+ export declare function throttle<T>(ms: number): Operator<T | ObservableError, T | ObservableError>;
162
+ /**
163
+ * Errors if an item takes too long to be processed.
164
+ *
165
+ * This operator passes normal synchronous values through immediately, but when
166
+ * an upstream operator emits a promise-like chunk it waits for that chunk to
167
+ * settle and races it against a timer. If the promise-like chunk does not
168
+ * resolve before the timer finishes, it emits an `ObservableError` instead.
169
+ *
170
+ * The implementation uses an async transform so Web Streams backpressure keeps
171
+ * later chunks from overtaking the timed chunk. In practice that means operator
172
+ * chains still stay ordered: each promise-like chunk either resolves to a value
173
+ * or times out before the next chunk is processed.
174
+ *
175
+ * @example
176
+ * ```ts
177
+ * import { pipe, timeout, from } from "./helpers/mod.ts";
178
+ *
179
+ * // Stream behavior
180
+ * const sourceStream = from([
181
+ * new Promise(res => setTimeout(() => res(1), 100)),
182
+ * new Promise(res => setTimeout(() => res(2), 2000))
183
+ * ]);
184
+ *
185
+ * const timedStream = pipe(sourceStream, timeout(1000));
186
+ * // Emits 1, then emits an error because the second promise took too long.
187
+ * ```
188
+ *
189
+ * ## Practical Use Case
190
+ *
191
+ * Use `timeout` to enforce Service Level Agreements (SLAs) on asynchronous
192
+ * operations, such as API calls. If a request takes too long, you can gracefully
193
+ * handle the timeout instead of letting your application hang.
194
+ *
195
+ * ## Key Insight
196
+ *
197
+ * `timeout` is a crucial tool for building resilient systems that can handle
198
+ * slow or unresponsive dependencies. It turns an indefinite wait into a
199
+ * predictable failure.
200
+ *
201
+ * @typeParam T The type of data in the stream.
202
+ * @param ms The timeout duration in milliseconds.
203
+ * @returns An operator that enforces a timeout on each item.
204
+ */
205
+ export declare function timeout<T>(ms: number): Operator<T | PromiseLike<T> | ObservableError, T | ObservableError>;
206
+ //# sourceMappingURL=timing.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../../../src/helpers/operations/timing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAgB,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,EAAqB,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,KAAK,CAAC,CAAC,EACrB,EAAE,EAAE,MAAM,GACT,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAiFpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,EAAE,EAAE,MAAM,GACT,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAmDpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,EAAE,EAAE,MAAM,GACT,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CA6DpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,EAAE,EAAE,MAAM,GACT,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CA8EpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,EAAE,EAAE,MAAM,GACT,QAAQ,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAiDrE"}