@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,90 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* High-level operator entrypoint for composing Observable pipelines.
|
|
3
|
+
*
|
|
4
|
+
* This is the ergonomic "import most things from one place" surface for the
|
|
5
|
+
* package. It re-exports the pipe/compose helpers, operator builders, utility
|
|
6
|
+
* helpers, and the built-in operator families so callers can build an entire
|
|
7
|
+
* pipeline without remembering which category module each operator lives in.
|
|
8
|
+
*
|
|
9
|
+
* The exports here fall into a few broad groups:
|
|
10
|
+
* - core transformation operators such as `map`, `filter`, `take`, and `scan`
|
|
11
|
+
* - timing operators such as `debounce`, `delay`, `throttle`, and `timeout`
|
|
12
|
+
* - combination operators such as `mergeMap`, `concatMap`, and `switchMap`
|
|
13
|
+
* - batching and error operators for collecting values or recovering from
|
|
14
|
+
* failures in a stream
|
|
15
|
+
*
|
|
16
|
+
* Everything shares the same Web Streams-based runtime, so backpressure,
|
|
17
|
+
* teardown, and error-mode behavior stay consistent from one operator to the
|
|
18
|
+
* next. Import from `./operations/*` only when you want a narrower entrypoint
|
|
19
|
+
* for discovery or tree-shaken docs. Import from this module when you want the
|
|
20
|
+
* familiar "just give me the operator toolbox" experience.
|
|
21
|
+
*
|
|
22
|
+
* ## Basic Usage
|
|
23
|
+
*
|
|
24
|
+
* @example
|
|
25
|
+
* ```ts
|
|
26
|
+
* import { pipe, map, filter, take } from "./helpers/mod.ts";
|
|
27
|
+
* import { Observable } from "./observable.ts";
|
|
28
|
+
*
|
|
29
|
+
* // Create an Observable with some data
|
|
30
|
+
* const source = new Observable(observer => {
|
|
31
|
+
* for (let i = 0; i < 10; i++) {
|
|
32
|
+
* observer.next(i);
|
|
33
|
+
* }
|
|
34
|
+
* observer.complete();
|
|
35
|
+
* });
|
|
36
|
+
*
|
|
37
|
+
* // Transform the Observable
|
|
38
|
+
* const result = pipe(
|
|
39
|
+
* source,
|
|
40
|
+
* filter(x => x % 2 === 0), // Keep even numbers
|
|
41
|
+
* map(x => x * 10), // Multiply by 10
|
|
42
|
+
* take(3) // Take only the first 3 values
|
|
43
|
+
* );
|
|
44
|
+
*
|
|
45
|
+
* // Subscribe to the result
|
|
46
|
+
* result.subscribe({
|
|
47
|
+
* next: value => console.log(value),
|
|
48
|
+
* complete: () => console.log('Done')
|
|
49
|
+
* });
|
|
50
|
+
* // Output: 0, 20, 40
|
|
51
|
+
* ```
|
|
52
|
+
*
|
|
53
|
+
* ## Advanced Composition
|
|
54
|
+
*
|
|
55
|
+
* For more complex pipelines, the `compose` function helps you group operators:
|
|
56
|
+
*
|
|
57
|
+
* @example
|
|
58
|
+
* ```ts
|
|
59
|
+
* import { pipe, compose, map, filter, take, tap } from "./helpers/mod.ts";
|
|
60
|
+
*
|
|
61
|
+
* // Use them in a pipeline
|
|
62
|
+
* const result = pipe(
|
|
63
|
+
* source,
|
|
64
|
+
*
|
|
65
|
+
* // Process numbers
|
|
66
|
+
* filter(x => x % 2 === 0),
|
|
67
|
+
* map(x => x * 10),
|
|
68
|
+
* tap(x => console.log('Processed:', x)),
|
|
69
|
+
*
|
|
70
|
+
* // Limit and format output
|
|
71
|
+
* take(3),
|
|
72
|
+
* map(x => `Result: ${x}`)
|
|
73
|
+
* );
|
|
74
|
+
* ```
|
|
75
|
+
*
|
|
76
|
+
* ## Limitations
|
|
77
|
+
*
|
|
78
|
+
* - Each pipeline is limited to 9 operators due to TypeScript's recursion limits
|
|
79
|
+
* - Use `compose` to group operators when you need more than 9
|
|
80
|
+
* - Composed operator groups are also limited to 9 operators
|
|
81
|
+
*
|
|
82
|
+
* @module
|
|
83
|
+
*/
|
|
84
|
+
import "../_dnt.polyfills.js";
|
|
85
|
+
export type * from "./_types.js";
|
|
86
|
+
export * from "./operations/mod.js";
|
|
87
|
+
export * from "./operators.js";
|
|
88
|
+
export * from "./pipe.js";
|
|
89
|
+
export * from "./utils.js";
|
|
90
|
+
//# sourceMappingURL=mod.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/helpers/mod.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AAGH,OAAO,sBAAsB,CAAC;AAE9B,mBAAmB,aAAa,CAAC;AAEjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
// @filename: helpers/mod.ts
|
|
2
|
+
/**
|
|
3
|
+
* High-level operator entrypoint for composing Observable pipelines.
|
|
4
|
+
*
|
|
5
|
+
* This is the ergonomic "import most things from one place" surface for the
|
|
6
|
+
* package. It re-exports the pipe/compose helpers, operator builders, utility
|
|
7
|
+
* helpers, and the built-in operator families so callers can build an entire
|
|
8
|
+
* pipeline without remembering which category module each operator lives in.
|
|
9
|
+
*
|
|
10
|
+
* The exports here fall into a few broad groups:
|
|
11
|
+
* - core transformation operators such as `map`, `filter`, `take`, and `scan`
|
|
12
|
+
* - timing operators such as `debounce`, `delay`, `throttle`, and `timeout`
|
|
13
|
+
* - combination operators such as `mergeMap`, `concatMap`, and `switchMap`
|
|
14
|
+
* - batching and error operators for collecting values or recovering from
|
|
15
|
+
* failures in a stream
|
|
16
|
+
*
|
|
17
|
+
* Everything shares the same Web Streams-based runtime, so backpressure,
|
|
18
|
+
* teardown, and error-mode behavior stay consistent from one operator to the
|
|
19
|
+
* next. Import from `./operations/*` only when you want a narrower entrypoint
|
|
20
|
+
* for discovery or tree-shaken docs. Import from this module when you want the
|
|
21
|
+
* familiar "just give me the operator toolbox" experience.
|
|
22
|
+
*
|
|
23
|
+
* ## Basic Usage
|
|
24
|
+
*
|
|
25
|
+
* @example
|
|
26
|
+
* ```ts
|
|
27
|
+
* import { pipe, map, filter, take } from "./helpers/mod.ts";
|
|
28
|
+
* import { Observable } from "./observable.ts";
|
|
29
|
+
*
|
|
30
|
+
* // Create an Observable with some data
|
|
31
|
+
* const source = new Observable(observer => {
|
|
32
|
+
* for (let i = 0; i < 10; i++) {
|
|
33
|
+
* observer.next(i);
|
|
34
|
+
* }
|
|
35
|
+
* observer.complete();
|
|
36
|
+
* });
|
|
37
|
+
*
|
|
38
|
+
* // Transform the Observable
|
|
39
|
+
* const result = pipe(
|
|
40
|
+
* source,
|
|
41
|
+
* filter(x => x % 2 === 0), // Keep even numbers
|
|
42
|
+
* map(x => x * 10), // Multiply by 10
|
|
43
|
+
* take(3) // Take only the first 3 values
|
|
44
|
+
* );
|
|
45
|
+
*
|
|
46
|
+
* // Subscribe to the result
|
|
47
|
+
* result.subscribe({
|
|
48
|
+
* next: value => console.log(value),
|
|
49
|
+
* complete: () => console.log('Done')
|
|
50
|
+
* });
|
|
51
|
+
* // Output: 0, 20, 40
|
|
52
|
+
* ```
|
|
53
|
+
*
|
|
54
|
+
* ## Advanced Composition
|
|
55
|
+
*
|
|
56
|
+
* For more complex pipelines, the `compose` function helps you group operators:
|
|
57
|
+
*
|
|
58
|
+
* @example
|
|
59
|
+
* ```ts
|
|
60
|
+
* import { pipe, compose, map, filter, take, tap } from "./helpers/mod.ts";
|
|
61
|
+
*
|
|
62
|
+
* // Use them in a pipeline
|
|
63
|
+
* const result = pipe(
|
|
64
|
+
* source,
|
|
65
|
+
*
|
|
66
|
+
* // Process numbers
|
|
67
|
+
* filter(x => x % 2 === 0),
|
|
68
|
+
* map(x => x * 10),
|
|
69
|
+
* tap(x => console.log('Processed:', x)),
|
|
70
|
+
*
|
|
71
|
+
* // Limit and format output
|
|
72
|
+
* take(3),
|
|
73
|
+
* map(x => `Result: ${x}`)
|
|
74
|
+
* );
|
|
75
|
+
* ```
|
|
76
|
+
*
|
|
77
|
+
* ## Limitations
|
|
78
|
+
*
|
|
79
|
+
* - Each pipeline is limited to 9 operators due to TypeScript's recursion limits
|
|
80
|
+
* - Use `compose` to group operators when you need more than 9
|
|
81
|
+
* - Composed operator groups are also limited to 9 operators
|
|
82
|
+
*
|
|
83
|
+
* @module
|
|
84
|
+
*/
|
|
85
|
+
// Re-export all operators from their respective modules
|
|
86
|
+
import "../_dnt.polyfills.js";
|
|
87
|
+
export * from "./operations/mod.js";
|
|
88
|
+
export * from "./operators.js";
|
|
89
|
+
export * from "./pipe.js";
|
|
90
|
+
export * from "./utils.js";
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Operators that collect multiple source values into grouped results.
|
|
3
|
+
*
|
|
4
|
+
* This entrypoint contains the batching side of the operator library. Use it
|
|
5
|
+
* when one output value should summarize several input values, such as turning
|
|
6
|
+
* a whole stream into a single array with `toArray()` or bundling incoming
|
|
7
|
+
* items into fixed-size chunks with `batch()`.
|
|
8
|
+
*
|
|
9
|
+
* These operators trade immediacy for aggregation. They usually hold on to some
|
|
10
|
+
* values until a batch fills or the source completes, so they are best for
|
|
11
|
+
* finite streams or bounded buffers where that extra memory is intentional.
|
|
12
|
+
*
|
|
13
|
+
* @module
|
|
14
|
+
*/
|
|
15
|
+
import "../../_dnt.polyfills.js";
|
|
16
|
+
import type { Operator } from "../_types.js";
|
|
17
|
+
import type { ObservableError } from "../../error.js";
|
|
18
|
+
/**
|
|
19
|
+
* Collects all values from the source stream and emits them as a single array
|
|
20
|
+
* when the source completes.
|
|
21
|
+
*
|
|
22
|
+
* Like `Array.prototype.slice()` for the whole stream, but delivered as a
|
|
23
|
+
* single chunk when the stream is done.
|
|
24
|
+
*
|
|
25
|
+
* @example
|
|
26
|
+
* ```ts
|
|
27
|
+
* import { pipe, toArray } from "../../mod.ts";
|
|
28
|
+
* import { from } from "../../../observable.ts";
|
|
29
|
+
*
|
|
30
|
+
* // Array behavior
|
|
31
|
+
* const fullArray = [1, 2, 3, 4, 5]; // [1, 2, 3, 4, 5]
|
|
32
|
+
*
|
|
33
|
+
* // Stream behavior
|
|
34
|
+
* const sourceStream = from([1, 2, 3, 4, 5]);
|
|
35
|
+
* const resultObservable = pipe(
|
|
36
|
+
* sourceStream,
|
|
37
|
+
* toArray()
|
|
38
|
+
* );
|
|
39
|
+
*
|
|
40
|
+
* for await (const result of resultObservable) {
|
|
41
|
+
* console.log(result); // [1, 2, 3, 4, 5]
|
|
42
|
+
* }
|
|
43
|
+
* ```
|
|
44
|
+
*
|
|
45
|
+
* ## Practical Use Case
|
|
46
|
+
*
|
|
47
|
+
* Use `toArray` when you need to gather all results from a stream before
|
|
48
|
+
* processing them, such as aggregating data for a final report or waiting for
|
|
49
|
+
* all parallel operations to complete.
|
|
50
|
+
*
|
|
51
|
+
* **Warning**: This operator should only be used with streams that are known
|
|
52
|
+
* to complete and emit a reasonable number of values to avoid memory issues.
|
|
53
|
+
*
|
|
54
|
+
* ## Key Insight
|
|
55
|
+
*
|
|
56
|
+
* `toArray` converts a stream back into a promise that resolves with an array,
|
|
57
|
+
* making it a bridge between asynchronous streams and synchronous array processing.
|
|
58
|
+
*
|
|
59
|
+
* @typeParam T - Type of values from the source stream
|
|
60
|
+
* @returns A stream operator that collects values into an array
|
|
61
|
+
*/
|
|
62
|
+
export declare function toArray<T>(): Operator<T | ObservableError, T[] | ObservableError>;
|
|
63
|
+
/**
|
|
64
|
+
* Batches values from the source stream into arrays of a specified size.
|
|
65
|
+
*
|
|
66
|
+
* Like a chunking utility, it groups items into fixed-size arrays, but for
|
|
67
|
+
* async streams. If the stream ends before a batch is full, it emits the
|
|
68
|
+
* partial batch.
|
|
69
|
+
*
|
|
70
|
+
* @example
|
|
71
|
+
* ```ts
|
|
72
|
+
* import { pipe, batch } from "../../mod.ts";
|
|
73
|
+
* import { from } from "../../../observable.ts";
|
|
74
|
+
*
|
|
75
|
+
* // No direct Array equivalent, but conceptually like chunking:
|
|
76
|
+
* const data = [1, 2, 3, 4, 5, 6, 7, 8];
|
|
77
|
+
* // Manual chunking: [[1, 2, 3], [4, 5, 6], [7, 8]]
|
|
78
|
+
*
|
|
79
|
+
* // Stream behavior
|
|
80
|
+
* const sourceStream = from(data);
|
|
81
|
+
* const batchedStream = pipe(
|
|
82
|
+
* sourceStream,
|
|
83
|
+
* batch(3)
|
|
84
|
+
* );
|
|
85
|
+
*
|
|
86
|
+
* for await (const result of batchedStream) {
|
|
87
|
+
* console.log(result);
|
|
88
|
+
* }
|
|
89
|
+
* // Resulting chunks: [1,2,3], [4,5,6], [7,8]
|
|
90
|
+
* ```
|
|
91
|
+
*
|
|
92
|
+
* ## Practical Use Case
|
|
93
|
+
*
|
|
94
|
+
* Use `batch` to process items in bulk, such as sending data to an API that
|
|
95
|
+
* accepts multiple records at once, or inserting records into a database in
|
|
96
|
+
* transactions. This is often more efficient than processing items one by one.
|
|
97
|
+
*
|
|
98
|
+
* ## Key Insight
|
|
99
|
+
*
|
|
100
|
+
* `batch` helps manage load on downstream systems by reducing the number of
|
|
101
|
+
* individual processing requests, turning a chatty stream into a more
|
|
102
|
+
* efficient, chunky one.
|
|
103
|
+
*
|
|
104
|
+
* @typeParam T - Type of values from the source stream
|
|
105
|
+
* @param size - The size of each batch
|
|
106
|
+
* @returns A stream operator that batches values
|
|
107
|
+
*/
|
|
108
|
+
export declare function batch<T>(size: number): Operator<T | ObservableError, T[] | ObservableError>;
|
|
109
|
+
//# sourceMappingURL=batch.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../../src/helpers/operations/batch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAgB,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAItD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,OAAO,CAAC,CAAC,KAAK,QAAQ,CACpC,CAAC,GAAG,eAAe,EACnB,CAAC,EAAE,GAAG,eAAe,CACtB,CAYA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,KAAK,CAAC,CAAC,EACrB,IAAI,EAAE,MAAM,GACX,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,EAAE,GAAG,eAAe,CAAC,CAuBtD"}
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Operators that collect multiple source values into grouped results.
|
|
3
|
+
*
|
|
4
|
+
* This entrypoint contains the batching side of the operator library. Use it
|
|
5
|
+
* when one output value should summarize several input values, such as turning
|
|
6
|
+
* a whole stream into a single array with `toArray()` or bundling incoming
|
|
7
|
+
* items into fixed-size chunks with `batch()`.
|
|
8
|
+
*
|
|
9
|
+
* These operators trade immediacy for aggregation. They usually hold on to some
|
|
10
|
+
* values until a batch fills or the source completes, so they are best for
|
|
11
|
+
* finite streams or bounded buffers where that extra memory is intentional.
|
|
12
|
+
*
|
|
13
|
+
* @module
|
|
14
|
+
*/
|
|
15
|
+
import "../../_dnt.polyfills.js";
|
|
16
|
+
import { createStatefulOperator } from "../operators.js";
|
|
17
|
+
/**
|
|
18
|
+
* Collects all values from the source stream and emits them as a single array
|
|
19
|
+
* when the source completes.
|
|
20
|
+
*
|
|
21
|
+
* Like `Array.prototype.slice()` for the whole stream, but delivered as a
|
|
22
|
+
* single chunk when the stream is done.
|
|
23
|
+
*
|
|
24
|
+
* @example
|
|
25
|
+
* ```ts
|
|
26
|
+
* import { pipe, toArray } from "../../mod.ts";
|
|
27
|
+
* import { from } from "../../../observable.ts";
|
|
28
|
+
*
|
|
29
|
+
* // Array behavior
|
|
30
|
+
* const fullArray = [1, 2, 3, 4, 5]; // [1, 2, 3, 4, 5]
|
|
31
|
+
*
|
|
32
|
+
* // Stream behavior
|
|
33
|
+
* const sourceStream = from([1, 2, 3, 4, 5]);
|
|
34
|
+
* const resultObservable = pipe(
|
|
35
|
+
* sourceStream,
|
|
36
|
+
* toArray()
|
|
37
|
+
* );
|
|
38
|
+
*
|
|
39
|
+
* for await (const result of resultObservable) {
|
|
40
|
+
* console.log(result); // [1, 2, 3, 4, 5]
|
|
41
|
+
* }
|
|
42
|
+
* ```
|
|
43
|
+
*
|
|
44
|
+
* ## Practical Use Case
|
|
45
|
+
*
|
|
46
|
+
* Use `toArray` when you need to gather all results from a stream before
|
|
47
|
+
* processing them, such as aggregating data for a final report or waiting for
|
|
48
|
+
* all parallel operations to complete.
|
|
49
|
+
*
|
|
50
|
+
* **Warning**: This operator should only be used with streams that are known
|
|
51
|
+
* to complete and emit a reasonable number of values to avoid memory issues.
|
|
52
|
+
*
|
|
53
|
+
* ## Key Insight
|
|
54
|
+
*
|
|
55
|
+
* `toArray` converts a stream back into a promise that resolves with an array,
|
|
56
|
+
* making it a bridge between asynchronous streams and synchronous array processing.
|
|
57
|
+
*
|
|
58
|
+
* @typeParam T - Type of values from the source stream
|
|
59
|
+
* @returns A stream operator that collects values into an array
|
|
60
|
+
*/
|
|
61
|
+
export function toArray() {
|
|
62
|
+
return createStatefulOperator({
|
|
63
|
+
name: "toArray",
|
|
64
|
+
createState: () => [],
|
|
65
|
+
transform(chunk, state) {
|
|
66
|
+
// If chunk is an error, we should not push it to the array
|
|
67
|
+
state.push(chunk); // Ensure chunk is not an error
|
|
68
|
+
},
|
|
69
|
+
flush(state, controller) {
|
|
70
|
+
controller.enqueue(state);
|
|
71
|
+
},
|
|
72
|
+
});
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Batches values from the source stream into arrays of a specified size.
|
|
76
|
+
*
|
|
77
|
+
* Like a chunking utility, it groups items into fixed-size arrays, but for
|
|
78
|
+
* async streams. If the stream ends before a batch is full, it emits the
|
|
79
|
+
* partial batch.
|
|
80
|
+
*
|
|
81
|
+
* @example
|
|
82
|
+
* ```ts
|
|
83
|
+
* import { pipe, batch } from "../../mod.ts";
|
|
84
|
+
* import { from } from "../../../observable.ts";
|
|
85
|
+
*
|
|
86
|
+
* // No direct Array equivalent, but conceptually like chunking:
|
|
87
|
+
* const data = [1, 2, 3, 4, 5, 6, 7, 8];
|
|
88
|
+
* // Manual chunking: [[1, 2, 3], [4, 5, 6], [7, 8]]
|
|
89
|
+
*
|
|
90
|
+
* // Stream behavior
|
|
91
|
+
* const sourceStream = from(data);
|
|
92
|
+
* const batchedStream = pipe(
|
|
93
|
+
* sourceStream,
|
|
94
|
+
* batch(3)
|
|
95
|
+
* );
|
|
96
|
+
*
|
|
97
|
+
* for await (const result of batchedStream) {
|
|
98
|
+
* console.log(result);
|
|
99
|
+
* }
|
|
100
|
+
* // Resulting chunks: [1,2,3], [4,5,6], [7,8]
|
|
101
|
+
* ```
|
|
102
|
+
*
|
|
103
|
+
* ## Practical Use Case
|
|
104
|
+
*
|
|
105
|
+
* Use `batch` to process items in bulk, such as sending data to an API that
|
|
106
|
+
* accepts multiple records at once, or inserting records into a database in
|
|
107
|
+
* transactions. This is often more efficient than processing items one by one.
|
|
108
|
+
*
|
|
109
|
+
* ## Key Insight
|
|
110
|
+
*
|
|
111
|
+
* `batch` helps manage load on downstream systems by reducing the number of
|
|
112
|
+
* individual processing requests, turning a chatty stream into a more
|
|
113
|
+
* efficient, chunky one.
|
|
114
|
+
*
|
|
115
|
+
* @typeParam T - Type of values from the source stream
|
|
116
|
+
* @param size - The size of each batch
|
|
117
|
+
* @returns A stream operator that batches values
|
|
118
|
+
*/
|
|
119
|
+
export function batch(size) {
|
|
120
|
+
if (size <= 0) {
|
|
121
|
+
throw new Error("batch: size must be greater than 0");
|
|
122
|
+
}
|
|
123
|
+
return createStatefulOperator({
|
|
124
|
+
name: "batch",
|
|
125
|
+
createState: () => [],
|
|
126
|
+
transform(chunk, buffer, controller) {
|
|
127
|
+
// If chunk is an error, we should not push it to the buffer
|
|
128
|
+
buffer.push(chunk); // Ensure chunk is not an error
|
|
129
|
+
if (buffer.length >= size) {
|
|
130
|
+
controller.enqueue(Array.from(buffer));
|
|
131
|
+
buffer.length = 0;
|
|
132
|
+
}
|
|
133
|
+
},
|
|
134
|
+
flush(buffer, controller) {
|
|
135
|
+
if (buffer.length > 0) {
|
|
136
|
+
controller.enqueue(Array.from(buffer));
|
|
137
|
+
}
|
|
138
|
+
},
|
|
139
|
+
});
|
|
140
|
+
}
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Operators that turn each source value into another stream and combine the
|
|
3
|
+
* results.
|
|
4
|
+
*
|
|
5
|
+
* This entrypoint covers the "flattening" family of operators such as
|
|
6
|
+
* `mergeMap`, `concatMap`, and `switchMap`. Use it when one input value needs
|
|
7
|
+
* to start follow-up async work, for example fetching related records, reading
|
|
8
|
+
* files, or switching to the latest search request.
|
|
9
|
+
*
|
|
10
|
+
* The operators in this module mainly differ in concurrency and cancellation
|
|
11
|
+
* behavior. `mergeMap` keeps multiple inner streams alive at once, `concatMap`
|
|
12
|
+
* preserves order by running one at a time, and `switchMap` cancels older work
|
|
13
|
+
* when a newer source value arrives.
|
|
14
|
+
*
|
|
15
|
+
* @module
|
|
16
|
+
*/
|
|
17
|
+
import "../../_dnt.polyfills.js";
|
|
18
|
+
import type { SpecObservable } from "../../_spec.js";
|
|
19
|
+
import type { ExcludeError, Operator } from "../_types.js";
|
|
20
|
+
import { ObservableError } from "../../error.js";
|
|
21
|
+
/**
|
|
22
|
+
* Transforms each item into a new stream and merges their outputs, running
|
|
23
|
+
* them in parallel.
|
|
24
|
+
*
|
|
25
|
+
* Like `Promise.all(items.map(project))` but for streams, with control over
|
|
26
|
+
* concurrency. It's designed for high-throughput parallel processing.
|
|
27
|
+
*
|
|
28
|
+
* @example
|
|
29
|
+
* ```ts
|
|
30
|
+
* import { pipe, mergeMap, from } from "./helpers/mod.ts";
|
|
31
|
+
* import { of } from "../../observable.ts";
|
|
32
|
+
*
|
|
33
|
+
* // Promise.all behavior
|
|
34
|
+
* const ids = [1, 2, 3];
|
|
35
|
+
* const promises = ids.map(id => Promise.resolve(`User ${id}`));
|
|
36
|
+
* const users = await Promise.all(promises); // ["User 1", "User 2", "User 3"]
|
|
37
|
+
*
|
|
38
|
+
* // Stream behavior
|
|
39
|
+
* const idStream = from(ids);
|
|
40
|
+
* const userStream = pipe(
|
|
41
|
+
* idStream,
|
|
42
|
+
* mergeMap(id => of(`User ${id}`), 2) // Process 2 at a time
|
|
43
|
+
* );
|
|
44
|
+
*
|
|
45
|
+
* // Results may arrive in any order, e.g., "User 2", "User 1", "User 3"
|
|
46
|
+
* ```
|
|
47
|
+
*
|
|
48
|
+
* ## Practical Use Case
|
|
49
|
+
*
|
|
50
|
+
* Use `mergeMap` to fetch data for multiple items concurrently. For example,
|
|
51
|
+
* given a stream of user IDs, you can fetch each user's profile in parallel.
|
|
52
|
+
* This is much faster than fetching them one by one.
|
|
53
|
+
*
|
|
54
|
+
* ## Key Insight
|
|
55
|
+
*
|
|
56
|
+
* `mergeMap` is for parallel, high-throughput operations where the order of
|
|
57
|
+
* results doesn't matter. It's the go-to for maximizing concurrency.
|
|
58
|
+
*
|
|
59
|
+
* @typeParam T - Type of values from the source Observable
|
|
60
|
+
* @typeParam R - Type of values in the result Observable
|
|
61
|
+
* @param project - Function that maps a source value to an Observable
|
|
62
|
+
* @param concurrent - Maximum number of inner Observables being subscribed
|
|
63
|
+
* to concurrently. Default is Infinity.
|
|
64
|
+
* @returns An operator function that maps and flattens values
|
|
65
|
+
*/
|
|
66
|
+
export declare function mergeMap<T, R>(project: (value: ExcludeError<T>, index: number) => SpecObservable<R>, concurrent?: number): Operator<T | ObservableError, R | ObservableError>;
|
|
67
|
+
/**
|
|
68
|
+
* Transforms each item into a new stream and runs them one after another, in
|
|
69
|
+
* strict order.
|
|
70
|
+
*
|
|
71
|
+
* Like a series of `await` calls in a `for...of` loop, this ensures that each
|
|
72
|
+
* new stream completes before the next one begins.
|
|
73
|
+
*
|
|
74
|
+
* @example
|
|
75
|
+
* ```ts
|
|
76
|
+
* import { pipe, concatMap, from } from "./helpers/mod.ts";
|
|
77
|
+
* import { of } from "../../observable.ts";
|
|
78
|
+
*
|
|
79
|
+
* // Sequential awaits in a loop
|
|
80
|
+
* async function processSequentially() {
|
|
81
|
+
* const results = [];
|
|
82
|
+
* for (const id of [1, 2, 3]) {
|
|
83
|
+
* const result = await Promise.resolve(`Step ${id}`);
|
|
84
|
+
* results.push(result);
|
|
85
|
+
* }
|
|
86
|
+
* return results; // ["Step 1", "Step 2", "Step 3"]
|
|
87
|
+
* }
|
|
88
|
+
*
|
|
89
|
+
* // Stream behavior
|
|
90
|
+
* const idStream = from([1, 2, 3]);
|
|
91
|
+
* const processStream = pipe(
|
|
92
|
+
* idStream,
|
|
93
|
+
* concatMap(id => of(`Step ${id}`))
|
|
94
|
+
* );
|
|
95
|
+
*
|
|
96
|
+
* // Results are guaranteed to be in order: "Step 1", "Step 2", "Step 3"
|
|
97
|
+
* ```
|
|
98
|
+
*
|
|
99
|
+
* ## Practical Use Case
|
|
100
|
+
*
|
|
101
|
+
* Use `concatMap` for sequential operations where order matters, such as a
|
|
102
|
+
* multi-step process where each step depends on the previous one (e.g., create
|
|
103
|
+
* user, then create their profile, then send a welcome email).
|
|
104
|
+
*
|
|
105
|
+
* ## Key Insight
|
|
106
|
+
*
|
|
107
|
+
* `concatMap` guarantees order by waiting for each inner stream to complete
|
|
108
|
+
* before starting the next. It's perfect for sequential tasks but is slower
|
|
109
|
+
* than `mergeMap` because it doesn't run in parallel.
|
|
110
|
+
*
|
|
111
|
+
* @typeParam T - Type of values from the source Observable
|
|
112
|
+
* @typeParam R - Type of values in the result Observable
|
|
113
|
+
* @param project - Function that maps a source value to an Observable
|
|
114
|
+
* @returns An operator function that maps and concatenates values
|
|
115
|
+
*/
|
|
116
|
+
export declare function concatMap<T, R>(project: (value: ExcludeError<T>, index: number) => SpecObservable<R>): Operator<T | ObservableError, R | ObservableError>;
|
|
117
|
+
/**
|
|
118
|
+
* Transforms items into new streams, but cancels the previous stream when a new
|
|
119
|
+
* item arrives.
|
|
120
|
+
*
|
|
121
|
+
* Like an auto-cancelling search input, it only cares about the latest value
|
|
122
|
+
* and discards any pending work from previous values.
|
|
123
|
+
*
|
|
124
|
+
* @example
|
|
125
|
+
* ```ts
|
|
126
|
+
* import { pipe, switchMap, from } from "./helpers/mod.ts";
|
|
127
|
+
* import { of } from "../../observable.ts";
|
|
128
|
+
*
|
|
129
|
+
* // No direct Array equivalent, as it's about handling events over time.
|
|
130
|
+
*
|
|
131
|
+
* // Stream behavior for a search input
|
|
132
|
+
* const queryStream = from(["cat", "cats", "cats rul"]);
|
|
133
|
+
*
|
|
134
|
+
* const searchResultStream = pipe(
|
|
135
|
+
* queryStream,
|
|
136
|
+
* switchMap(query => of(`Results for "${query}"`))
|
|
137
|
+
* );
|
|
138
|
+
*
|
|
139
|
+
* // Assuming each query arrives before the last one "completes":
|
|
140
|
+
* // The first two searches for "cat" and "cats" would be cancelled.
|
|
141
|
+
* // The final output would only be: 'Results for "cats rul"'
|
|
142
|
+
* ```
|
|
143
|
+
*
|
|
144
|
+
* ## Practical Use Case
|
|
145
|
+
*
|
|
146
|
+
* `switchMap` is essential for live search bars or any UI element that
|
|
147
|
+
* triggers frequent events. It ensures that only the results for the most
|
|
148
|
+
* recent event are processed, preventing outdated or out-of-order results.
|
|
149
|
+
*
|
|
150
|
+
* ## Key Insight
|
|
151
|
+
*
|
|
152
|
+
* `switchMap` is the operator of choice for handling rapid-fire events where
|
|
153
|
+
* only the latest matters. It prevents race conditions and keeps your UI
|
|
154
|
+
* responsive by cancelling stale, in-flight operations.
|
|
155
|
+
*
|
|
156
|
+
* @typeParam T - Type of values from the source Observable
|
|
157
|
+
* @typeParam R - Type of values in the result Observable
|
|
158
|
+
* @param project - Function that maps a source value to an Observable
|
|
159
|
+
* @returns An operator function that maps and switches between values
|
|
160
|
+
*/
|
|
161
|
+
export declare function switchMap<T, R>(project: (value: ExcludeError<T>, index: number) => SpecObservable<R>): Operator<T | ObservableError, R | ObservableError>;
|
|
162
|
+
//# sourceMappingURL=combination.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"combination.d.ts","sourceRoot":"","sources":["../../../src/helpers/operations/combination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,yBAAyB,CAAC;AAGjC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAG3D,OAAO,EAAqB,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAC3B,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,cAAc,CAAC,CAAC,CAAC,EACrE,UAAU,GAAE,MAAiB,GAC5B,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAkHpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,EAC5B,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,cAAc,CAAC,CAAC,CAAC,GACpE,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAGpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,EAC5B,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,cAAc,CAAC,CAAC,CAAC,GACpE,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAyIpD"}
|