@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,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"}