@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.
- package/LICENSE +21 -0
- package/README.md +578 -0
- package/esm/_dnt.polyfills.d.ts +20 -0
- package/esm/_dnt.polyfills.d.ts.map +1 -0
- package/esm/_dnt.polyfills.js +12 -0
- package/esm/_spec.d.ts +260 -0
- package/esm/_spec.d.ts.map +1 -0
- package/esm/_spec.js +1 -0
- package/esm/_types.d.ts +141 -0
- package/esm/_types.d.ts.map +1 -0
- package/esm/_types.js +20 -0
- package/esm/error.d.ts +331 -0
- package/esm/error.d.ts.map +1 -0
- package/esm/error.js +408 -0
- package/esm/events.d.ts +320 -0
- package/esm/events.d.ts.map +1 -0
- package/esm/events.js +451 -0
- package/esm/helpers/_types.d.ts +188 -0
- package/esm/helpers/_types.d.ts.map +1 -0
- package/esm/helpers/_types.js +1 -0
- package/esm/helpers/mod.d.ts +90 -0
- package/esm/helpers/mod.d.ts.map +1 -0
- package/esm/helpers/mod.js +90 -0
- package/esm/helpers/operations/batch.d.ts +109 -0
- package/esm/helpers/operations/batch.d.ts.map +1 -0
- package/esm/helpers/operations/batch.js +140 -0
- package/esm/helpers/operations/combination.d.ts +162 -0
- package/esm/helpers/operations/combination.d.ts.map +1 -0
- package/esm/helpers/operations/combination.js +350 -0
- package/esm/helpers/operations/conditional.d.ts +211 -0
- package/esm/helpers/operations/conditional.d.ts.map +1 -0
- package/esm/helpers/operations/conditional.js +280 -0
- package/esm/helpers/operations/core.d.ts +198 -0
- package/esm/helpers/operations/core.d.ts.map +1 -0
- package/esm/helpers/operations/core.js +264 -0
- package/esm/helpers/operations/errors.d.ts +277 -0
- package/esm/helpers/operations/errors.d.ts.map +1 -0
- package/esm/helpers/operations/errors.js +378 -0
- package/esm/helpers/operations/mod.d.ts +26 -0
- package/esm/helpers/operations/mod.d.ts.map +1 -0
- package/esm/helpers/operations/mod.js +25 -0
- package/esm/helpers/operations/timing.d.ts +206 -0
- package/esm/helpers/operations/timing.d.ts.map +1 -0
- package/esm/helpers/operations/timing.js +457 -0
- package/esm/helpers/operators.d.ts +520 -0
- package/esm/helpers/operators.d.ts.map +1 -0
- package/esm/helpers/operators.js +563 -0
- package/esm/helpers/pipe.d.ts +118 -0
- package/esm/helpers/pipe.d.ts.map +1 -0
- package/esm/helpers/pipe.js +129 -0
- package/esm/helpers/utils.d.ts +142 -0
- package/esm/helpers/utils.d.ts.map +1 -0
- package/esm/helpers/utils.js +193 -0
- package/esm/mod.d.ts +863 -0
- package/esm/mod.d.ts.map +1 -0
- package/esm/mod.js +861 -0
- package/esm/observable.d.ts +1610 -0
- package/esm/observable.d.ts.map +1 -0
- package/esm/observable.js +1970 -0
- package/esm/package.json +3 -0
- package/esm/queue.d.ts +201 -0
- package/esm/queue.d.ts.map +1 -0
- package/esm/queue.js +273 -0
- package/esm/symbol.d.ts +60 -0
- package/esm/symbol.d.ts.map +1 -0
- package/esm/symbol.js +132 -0
- package/package.json +96 -0
- package/script/_dnt.polyfills.d.ts +20 -0
- package/script/_dnt.polyfills.d.ts.map +1 -0
- package/script/_dnt.polyfills.js +13 -0
- package/script/_spec.d.ts +260 -0
- package/script/_spec.d.ts.map +1 -0
- package/script/_spec.js +2 -0
- package/script/_types.d.ts +141 -0
- package/script/_types.d.ts.map +1 -0
- package/script/_types.js +22 -0
- package/script/error.d.ts +331 -0
- package/script/error.d.ts.map +1 -0
- package/script/error.js +414 -0
- package/script/events.d.ts +320 -0
- package/script/events.d.ts.map +1 -0
- package/script/events.js +458 -0
- package/script/helpers/_types.d.ts +188 -0
- package/script/helpers/_types.d.ts.map +1 -0
- package/script/helpers/_types.js +2 -0
- package/script/helpers/mod.d.ts +90 -0
- package/script/helpers/mod.d.ts.map +1 -0
- package/script/helpers/mod.js +106 -0
- package/script/helpers/operations/batch.d.ts +109 -0
- package/script/helpers/operations/batch.d.ts.map +1 -0
- package/script/helpers/operations/batch.js +144 -0
- package/script/helpers/operations/combination.d.ts +162 -0
- package/script/helpers/operations/combination.d.ts.map +1 -0
- package/script/helpers/operations/combination.js +355 -0
- package/script/helpers/operations/conditional.d.ts +211 -0
- package/script/helpers/operations/conditional.d.ts.map +1 -0
- package/script/helpers/operations/conditional.js +286 -0
- package/script/helpers/operations/core.d.ts +198 -0
- package/script/helpers/operations/core.d.ts.map +1 -0
- package/script/helpers/operations/core.js +272 -0
- package/script/helpers/operations/errors.d.ts +277 -0
- package/script/helpers/operations/errors.d.ts.map +1 -0
- package/script/helpers/operations/errors.js +387 -0
- package/script/helpers/operations/mod.d.ts +26 -0
- package/script/helpers/operations/mod.d.ts.map +1 -0
- package/script/helpers/operations/mod.js +41 -0
- package/script/helpers/operations/timing.d.ts +206 -0
- package/script/helpers/operations/timing.d.ts.map +1 -0
- package/script/helpers/operations/timing.js +464 -0
- package/script/helpers/operators.d.ts +520 -0
- package/script/helpers/operators.d.ts.map +1 -0
- package/script/helpers/operators.js +570 -0
- package/script/helpers/pipe.d.ts +118 -0
- package/script/helpers/pipe.d.ts.map +1 -0
- package/script/helpers/pipe.js +132 -0
- package/script/helpers/utils.d.ts +142 -0
- package/script/helpers/utils.d.ts.map +1 -0
- package/script/helpers/utils.js +200 -0
- package/script/mod.d.ts +863 -0
- package/script/mod.d.ts.map +1 -0
- package/script/mod.js +877 -0
- package/script/observable.d.ts +1610 -0
- package/script/observable.d.ts.map +1 -0
- package/script/observable.js +1984 -0
- package/script/package.json +3 -0
- package/script/queue.d.ts +201 -0
- package/script/queue.d.ts.map +1 -0
- package/script/queue.js +286 -0
- package/script/symbol.d.ts +60 -0
- package/script/symbol.d.ts.map +1 -0
- 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"}
|