@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,387 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.ignoreErrors = ignoreErrors;
4
+ exports.catchErrors = catchErrors;
5
+ exports.mapErrors = mapErrors;
6
+ exports.onlyErrors = onlyErrors;
7
+ exports.summarizeErrors = summarizeErrors;
8
+ exports.tapError = tapError;
9
+ exports.throwErrors = throwErrors;
10
+ /**
11
+ * Error-focused operators for recovering from or reshaping stream failures.
12
+ *
13
+ * This entrypoint is for pipelines that expect some work to fail and want to
14
+ * keep going. It exports helpers for dropping wrapped errors, mapping them to
15
+ * fallback values, logging them, or converting them into a shape that fits the
16
+ * rest of the pipeline.
17
+ *
18
+ * These operators are most useful with the library's pass-through error mode,
19
+ * where failures travel as `ObservableError` values instead of immediately
20
+ * terminating the whole stream.
21
+ *
22
+ * @module
23
+ */
24
+ require("../../_dnt.polyfills.js");
25
+ const error_js_1 = require("../../error.js");
26
+ const operators_js_1 = require("../operators.js");
27
+ /**
28
+ * Removes all errors from the stream, keeping only successful data.
29
+ *
30
+ * Like a filter that only allows non-error values to pass. It's a simple way
31
+ * to clean up a stream when you don't need to handle failures.
32
+ *
33
+ * @example
34
+ * ```ts
35
+ * import { pipe, ignoreErrors, from } from "./helpers/mod.ts";
36
+ *
37
+ * // Array behavior (conceptual)
38
+ * const mixedData = [1, new Error("fail"), 2, 3];
39
+ * const goodData = mixedData.filter(item => !(item instanceof Error)); // [1, 2, 3]
40
+ *
41
+ * // Stream behavior
42
+ * const sourceStream = from([1, new ObservableError("fail"), 2, 3]);
43
+ * const cleanStream = pipe(sourceStream, ignoreErrors()); // Emits 1, 2, 3
44
+ * ```
45
+ *
46
+ * ## Practical Use Case
47
+ *
48
+ * Use `ignoreErrors` when processing a batch of items where some failures are
49
+ * expected and acceptable. For example, fetching a list of URLs where some
50
+ * might be broken. You only want to process the ones that work.
51
+ *
52
+ * ## Key Insight
53
+ *
54
+ * `ignoreErrors` provides a "fire-and-forget" approach to error handling. It's
55
+ * useful for non-critical tasks or when partial success is sufficient.
56
+ *
57
+ * @template T The type of good data in your stream
58
+ * @returns A stream operator that silently removes all errors
59
+ */
60
+ function ignoreErrors() {
61
+ return (0, operators_js_1.createOperator)({
62
+ name: "ignoreErrors",
63
+ errorMode: "ignore",
64
+ transform(chunk, controller) {
65
+ controller.enqueue(chunk);
66
+ // Errors are silently dropped
67
+ },
68
+ });
69
+ }
70
+ /**
71
+ * Replaces any error in the stream with a fallback value.
72
+ *
73
+ * Like a `try...catch` block for each item in a stream, but instead of just
74
+ * handling the error, you provide a default value to take its place.
75
+ *
76
+ * @example
77
+ * ```ts
78
+ * import { pipe, catchErrors, from } from "./helpers/mod.ts";
79
+ *
80
+ * // Conceptual equivalent
81
+ * function process(item) {
82
+ * try {
83
+ * if (item instanceof Error) throw item;
84
+ * return item;
85
+ * } catch {
86
+ * return "default";
87
+ * }
88
+ * }
89
+ * const results = [1, new Error("fail")].map(process); // [1, "default"]
90
+ *
91
+ * // Stream behavior
92
+ * const sourceStream = from([1, new ObservableError("fail")]);
93
+ * const safeStream = pipe(sourceStream, catchErrors("default")); // Emits 1, "default"
94
+ * ```
95
+ *
96
+ * ## Practical Use Case
97
+ *
98
+ * Use `catchErrors` to provide a default state or value when an operation
99
+ * fails. For example, if fetching a user's profile fails, you could return a
100
+ * default "Guest" profile instead of letting the error propagate.
101
+ *
102
+ * ## Key Insight
103
+ *
104
+ * `catchErrors` ensures your stream continues with a predictable structure,
105
+ * even when individual operations fail. It maintains the flow of data by
106
+ * substituting errors with safe, default values.
107
+ *
108
+ * @template T The type of data in your stream.
109
+ * @template R The type of the fallback value.
110
+ * @param fallback The value to use whenever an error occurs.
111
+ * @returns A stream operator that replaces errors with a fallback value.
112
+ */
113
+ function catchErrors(fallback) {
114
+ return (0, operators_js_1.createOperator)({
115
+ name: "catchErrors",
116
+ errorMode: "manual",
117
+ transform(chunk, controller) {
118
+ if ((0, error_js_1.isObservableError)(chunk)) {
119
+ controller.enqueue(fallback);
120
+ }
121
+ else {
122
+ controller.enqueue(chunk);
123
+ }
124
+ },
125
+ });
126
+ }
127
+ /**
128
+ * Transforms errors into custom values using a mapping function.
129
+ *
130
+ * This is a more powerful version of `catchErrors`. Instead of a single
131
+ * fallback, you can inspect each error and decide what to replace it with.
132
+ *
133
+ * @example
134
+ * ```ts
135
+ * import { pipe, mapErrors, from } from "./helpers/mod.ts";
136
+ *
137
+ * // Stream behavior
138
+ * const sourceStream = from([
139
+ * 1,
140
+ * new ObservableError("Not Found"),
141
+ * new ObservableError("Server Error")
142
+ * ]);
143
+ *
144
+ * const handledStream = pipe(
145
+ * sourceStream,
146
+ * mapErrors(err => {
147
+ * if (err.message === "Not Found") return { status: 404 };
148
+ * return { status: 500 };
149
+ * })
150
+ * );
151
+ * // Emits 1, { status: 404 }, { status: 500 }
152
+ * ```
153
+ *
154
+ * ## Practical Use Case
155
+ *
156
+ * Use `mapErrors` to convert different types of errors into meaningful data.
157
+ * For example, a "Not Found" error could be mapped to `null`, while a "Server
158
+ * Error" could be mapped to an object that triggers a retry mechanism.
159
+ *
160
+ * ## Key Insight
161
+ *
162
+ * `mapErrors` treats errors as data. It allows you to create a resilient
163
+ * stream that can intelligently respond to different failure modes without
164
+ * stopping.
165
+ *
166
+ * @template T The type of successful data in your stream.
167
+ * @template E The type your errors will be mapped to.
168
+ * @param errorMapper A function that receives an error and returns a new value.
169
+ * @returns A stream operator that transforms errors.
170
+ */
171
+ function mapErrors(errorMapper) {
172
+ return (0, operators_js_1.createOperator)({
173
+ name: "mapErrors",
174
+ errorMode: "manual",
175
+ transform(chunk, controller) {
176
+ if ((0, error_js_1.isObservableError)(chunk)) {
177
+ try {
178
+ const mappedError = errorMapper(chunk);
179
+ controller.enqueue(mappedError);
180
+ }
181
+ catch (mapperError) {
182
+ controller.error(new error_js_1.ObservableError([mapperError, chunk], `Your error mapper function threw an error: ${mapperError}`, {
183
+ operator: "operator:mapErrors:mapper",
184
+ value: mapperError,
185
+ cause: chunk,
186
+ tip: "The function passed to mapErrors threw an error. Check its implementation.",
187
+ }));
188
+ }
189
+ }
190
+ else {
191
+ controller.enqueue(chunk);
192
+ }
193
+ },
194
+ });
195
+ }
196
+ /**
197
+ * Keeps only the errors from the stream, discarding successful data.
198
+ *
199
+ * This is the inverse of `ignoreErrors`. It's useful for creating a dedicated
200
+ * error-handling pipeline.
201
+ *
202
+ * @example
203
+ * ```ts
204
+ * import { pipe, onlyErrors, from } from "./helpers/mod.ts";
205
+ *
206
+ * // Stream behavior
207
+ * const sourceStream = from([1, new ObservableError("fail"), 2]);
208
+ * const errorStream = pipe(sourceStream, onlyErrors()); // Emits ObservableError("fail")
209
+ * ```
210
+ *
211
+ * ## Practical Use Case
212
+ *
213
+ * Use `onlyErrors` to separate the error stream from the data stream. You can
214
+ * then log these errors, send them to a monitoring service, or trigger alerts
215
+ * without interfering with the main data processing flow.
216
+ *
217
+ * ## Key Insight
218
+ *
219
+ * `onlyErrors` allows you to create a side-channel for failures, enabling
220
+ * robust monitoring and debugging.
221
+ *
222
+ * @template T The type of data in the source stream.
223
+ * @returns An operator that filters for errors.
224
+ */
225
+ function onlyErrors() {
226
+ return (0, operators_js_1.createOperator)({
227
+ name: "onlyErrors",
228
+ errorMode: "manual",
229
+ transform(chunk, controller) {
230
+ if ((0, error_js_1.isObservableError)(chunk)) {
231
+ controller.enqueue(chunk);
232
+ }
233
+ // Good data is discarded
234
+ },
235
+ });
236
+ }
237
+ /**
238
+ * Summarizes the stream into a final count of successes and errors.
239
+ *
240
+ * This operator waits for the stream to complete and then emits a single
241
+ * object with the total counts.
242
+ *
243
+ * @example
244
+ * ```ts
245
+ * import { pipe, summarizeErrors, from } from "./helpers/mod.ts";
246
+ *
247
+ * // Stream behavior
248
+ * const sourceStream = from([1, new ObservableError("fail"), 2, 3]);
249
+ * const summary = await pipe(sourceStream, summarizeErrors()).toPromise();
250
+ * // { successCount: 3, errorCount: 1, totalProcessed: 4, successRate: 0.75 }
251
+ * ```
252
+ *
253
+ * ## Practical Use Case
254
+ *
255
+ * Use `summarizeErrors` at the end of a batch processing job to get a report
256
+ * on how many items were processed successfully and how many failed. This is
257
+
258
+ * useful for logging, monitoring, and generating reports.
259
+ *
260
+ * ## Key Insight
261
+ *
262
+ * `summarizeErrors` is a terminal operator that provides a high-level overview
263
+ * of a stream's health and completeness.
264
+ *
265
+ * @template T The type of data in the source stream.
266
+ * @returns An operator that emits a summary of successes and errors.
267
+ */
268
+ function summarizeErrors() {
269
+ return (0, operators_js_1.createStatefulOperator)({
270
+ name: "summarizeErrors",
271
+ errorMode: "manual",
272
+ createState: () => ({ successCount: 0, errorCount: 0 }),
273
+ transform(chunk, state) {
274
+ if ((0, error_js_1.isObservableError)(chunk)) {
275
+ state.errorCount++;
276
+ }
277
+ else {
278
+ state.successCount++;
279
+ }
280
+ },
281
+ flush(state, controller) {
282
+ const total = state.successCount + state.errorCount;
283
+ controller.enqueue({
284
+ successCount: state.successCount,
285
+ errorCount: state.errorCount,
286
+ totalProcessed: total,
287
+ successRate: total > 0 ? state.successCount / total : 0,
288
+ });
289
+ },
290
+ });
291
+ }
292
+ /**
293
+ * Performs a side effect for each error without modifying the stream.
294
+ *
295
+ * Like `Array.prototype.forEach` but only for errors. It's useful for logging
296
+ * or debugging without altering the data flow.
297
+ *
298
+ * @example
299
+ * ```ts
300
+ * import { pipe, tapError, from } from "./helpers/mod.ts";
301
+ *
302
+ * // Stream behavior
303
+ * const sourceStream = from([1, new ObservableError("fail")]);
304
+ * const tappedStream = pipe(
305
+ * sourceStream,
306
+ * tapError(err => console.error("Found an error:", err))
307
+ * );
308
+ * // Logs the error, then emits 1 and the error object.
309
+ * ```
310
+ *
311
+ * ## Practical Use Case
312
+ *
313
+ * Use `tapError` to log errors to the console or a monitoring service as they
314
+ * happen, without stopping or changing the stream. This is invaluable for
315
+ * real-time debugging.
316
+ *
317
+ * ## Key Insight
318
+ *
319
+ * `tapError` gives you a window into the stream's errors without affecting the
320
+ * stream itself.
321
+ *
322
+ * @template T The type of data in the stream.
323
+ * @param sideEffect A function to call for each error.
324
+ * @returns An operator that performs a side effect on errors.
325
+ */
326
+ function tapError(sideEffect) {
327
+ return (0, operators_js_1.createOperator)({
328
+ name: "tapError",
329
+ errorMode: "manual",
330
+ transform(chunk, controller) {
331
+ try {
332
+ if ((0, error_js_1.isObservableError)(chunk)) {
333
+ sideEffect(chunk);
334
+ }
335
+ }
336
+ catch (_) {
337
+ /* no empty */
338
+ }
339
+ finally {
340
+ controller.enqueue(chunk);
341
+ }
342
+ },
343
+ });
344
+ }
345
+ /**
346
+ * Throws an error if it encounters one in the stream.
347
+ *
348
+ * This operator is useful for enforcing strict error handling. If an error is
349
+ * encountered, it will throw immediately, stopping the iteration.
350
+ *
351
+ * @example
352
+ * ```ts
353
+ * import { pipe, throwErrors, from } from "./helpers/mod.ts";
354
+ *
355
+ * // Stream behavior
356
+ * const sourceStream = from([1, new ObservableError("fail"), 2]);
357
+ * const throwingStream = pipe(sourceStream, throwErrors());
358
+ *
359
+ * for await (const item of throwingStream) {
360
+ * console.log(item); // Will log 1, then throw on "fail"
361
+ * }
362
+ * ```
363
+ *
364
+ * ## Practical Use Case
365
+ *
366
+ * Use `throwErrors` when you want to ensure that any error in the stream is
367
+ * treated as a critical failure. This is useful in scenarios where errors must
368
+ * be handled immediately and cannot be ignored.
369
+ *
370
+ * ## Key Insight
371
+ *
372
+ * `throwErrors` provides a way to enforce strict error handling in streams,
373
+ * ensuring that no errors go unnoticed.
374
+ *
375
+ * @template T The type of data in the stream.
376
+ * @returns An operator that throws on errors.
377
+ */
378
+ function throwErrors() {
379
+ return (0, operators_js_1.createOperator)({
380
+ name: "throwErrors",
381
+ errorMode: "throw",
382
+ transform(chunk, controller) {
383
+ // If it's an error, this will automatically throw due to errorMode: "throw"
384
+ controller.enqueue(chunk);
385
+ },
386
+ });
387
+ }
@@ -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,41 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
+ for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
+ };
16
+ Object.defineProperty(exports, "__esModule", { value: true });
17
+ /**
18
+ * Category-level entrypoint for the built-in Observable operations.
19
+ *
20
+ * This module gathers every operator category that powers the higher-level
21
+ * `./operators` entrypoint. It is useful when you want a focused import path
22
+ * for documentation and discovery, but still want access to the full built-in
23
+ * operator set from one module.
24
+ *
25
+ * The re-exports are grouped by job:
26
+ * - `./core` covers the array-like transformations and terminal operators
27
+ * - `./timing` covers time-based coordination such as debounce and timeout
28
+ * - `./combination` covers flattening and concurrency helpers such as
29
+ * `mergeMap`, `concatMap`, and `switchMap`
30
+ * - `./batch`, `./conditional`, and `./errors` cover collection, predicate, and
31
+ * recovery-focused utilities
32
+ *
33
+ * @module
34
+ */
35
+ require("../../_dnt.polyfills.js");
36
+ __exportStar(require("./batch.js"), exports);
37
+ __exportStar(require("./combination.js"), exports);
38
+ __exportStar(require("./conditional.js"), exports);
39
+ __exportStar(require("./core.js"), exports);
40
+ __exportStar(require("./errors.js"), exports);
41
+ __exportStar(require("./timing.js"), exports);
@@ -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"}