@okikio/observables 1.0.2

package/esm/helpers/operations/combination.js

@@ -0,0 +1,350 @@
+/**
+ * Operators that turn each source value into another stream and combine the
+ * results.
+ *
+ * This entrypoint covers the "flattening" family of operators such as
+ * `mergeMap`, `concatMap`, and `switchMap`. Use it when one input value needs
+ * to start follow-up async work, for example fetching related records, reading
+ * files, or switching to the latest search request.
+ *
+ * The operators in this module mainly differ in concurrency and cancellation
+ * behavior. `mergeMap` keeps multiple inner streams alive at once, `concatMap`
+ * preserves order by running one at a time, and `switchMap` cancels older work
+ * when a newer source value arrives.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+import { createStatefulOperator } from "../operators.js";
+import { isObservableError, ObservableError } from "../../error.js";
+import { pull } from "../../observable.js";
+/**
+ * Transforms each item into a new stream and merges their outputs, running
+ * them in parallel.
+ *
+ * Like `Promise.all(items.map(project))` but for streams, with control over
+ * concurrency. It's designed for high-throughput parallel processing.
+ *
+ * @example
+ * ```ts
+ * import { pipe, mergeMap, from } from "./helpers/mod.ts";
+ * import { of } from "../../observable.ts";
+ *
+ * // Promise.all behavior
+ * const ids = [1, 2, 3];
+ * const promises = ids.map(id => Promise.resolve(`User ${id}`));
+ * const users = await Promise.all(promises); // ["User 1", "User 2", "User 3"]
+ *
+ * // Stream behavior
+ * const idStream = from(ids);
+ * const userStream = pipe(
+ *   idStream,
+ *   mergeMap(id => of(`User ${id}`), 2) // Process 2 at a time
+ * );
+ *
+ * // Results may arrive in any order, e.g., "User 2", "User 1", "User 3"
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `mergeMap` to fetch data for multiple items concurrently. For example,
+ * given a stream of user IDs, you can fetch each user's profile in parallel.
+ * This is much faster than fetching them one by one.
+ *
+ * ## Key Insight
+ *
+ * `mergeMap` is for parallel, high-throughput operations where the order of
+ * results doesn't matter. It's the go-to for maximizing concurrency.
+ *
+ * @typeParam T - Type of values from the source Observable
+ * @typeParam R - Type of values in the result Observable
+ * @param project - Function that maps a source value to an Observable
+ * @param concurrent - Maximum number of inner Observables being subscribed
+ * to concurrently. Default is Infinity.
+ * @returns An operator function that maps and flattens values
+ */
+export function mergeMap(project, concurrent = Infinity) {
+    return createStatefulOperator({
+        name: "mergeMap",
+        // Initialize state
+        createState: () => ({
+            activeSubscriptions: new Map(),
+            buffer: [],
+            sourceCompleted: false,
+            index: 0,
+            activeCount: 0,
+        }),
+        // Process each incoming chunk
+        async transform(chunk, state, controller) {
+            // If we're under the concurrency limit, process immediately
+            if (state.activeCount < concurrent) {
+                await subscribeToProjection(chunk, state.index++);
+            }
+            else {
+                // Otherwise, buffer for later
+                state.buffer.push([chunk, state.index++]);
+            }
+            // Helper function to subscribe to inner Observable
+            async function subscribeToProjection(value, innerIndex) {
+                let innerObservable;
+                try {
+                    // Apply projection function to get inner Observable
+                    innerObservable = project(value, innerIndex);
+                }
+                catch (err) {
+                    // Forward any errors from the projection function
+                    controller.enqueue(ObservableError.from(err, "operator:stateful:mergeMap:project", value));
+                    return;
+                }
+                state.activeCount++;
+                // Use pull to iterate asynchronously
+                try {
+                    for await (const innerValue of pull(innerObservable, { throwError: false })) {
+                        controller.enqueue(innerValue);
+                    }
+                }
+                catch (err) {
+                    controller.enqueue(ObservableError.from(err, "operator:stateful:mergeMap:innerObservable", value));
+                }
+                finally {
+                    // Clean up after inner Observable completes
+                    state.activeSubscriptions.delete(innerIndex);
+                    state.activeCount--;
+                    // Process the buffer if we have space
+                    processBuffer();
+                }
+            }
+            // Helper function to process the buffer
+            async function processBuffer() {
+                // While we have room for more inner Observables and
+                // there are items in the buffer, subscribe to inner Observables
+                while (state.activeCount < concurrent && state.buffer.length > 0) {
+                    const [value, bufferIndex] = state.buffer.shift();
+                    await subscribeToProjection(value, bufferIndex);
+                }
+                // If the source is completed and we have no active inner
+                // subscriptions, complete the output stream
+                // Nothing more to do, transformation is complete
+            }
+        },
+        // Handle the end of the source stream
+        flush(state) {
+            // Mark the source as completed
+            state.sourceCompleted = true;
+            // If no active inner subscriptions, we're done
+            // Stream will close naturally
+            // Otherwise, let the active subscriptions complete
+        },
+        // Handle cancellation
+        cancel(state) {
+            // Clean up all inner subscriptions
+            for (const subscription of state.activeSubscriptions.values()) {
+                subscription.unsubscribe();
+            }
+            // Clear the buffer and state
+            state.buffer.length = 0;
+            state.activeSubscriptions.clear();
+            state.activeCount = 0;
+        },
+    });
+}
+/**
+ * Transforms each item into a new stream and runs them one after another, in
+ * strict order.
+ *
+ * Like a series of `await` calls in a `for...of` loop, this ensures that each
+ * new stream completes before the next one begins.
+ *
+ * @example
+ * ```ts
+ * import { pipe, concatMap, from } from "./helpers/mod.ts";
+ * import { of } from "../../observable.ts";
+ *
+ * // Sequential awaits in a loop
+ * async function processSequentially() {
+ *   const results = [];
+ *   for (const id of [1, 2, 3]) {
+ *     const result = await Promise.resolve(`Step ${id}`);
+ *     results.push(result);
+ *   }
+ *   return results; // ["Step 1", "Step 2", "Step 3"]
+ * }
+ *
+ * // Stream behavior
+ * const idStream = from([1, 2, 3]);
+ * const processStream = pipe(
+ *   idStream,
+ *   concatMap(id => of(`Step ${id}`))
+ * );
+ *
+ * // Results are guaranteed to be in order: "Step 1", "Step 2", "Step 3"
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `concatMap` for sequential operations where order matters, such as a
+ * multi-step process where each step depends on the previous one (e.g., create
+ * user, then create their profile, then send a welcome email).
+ *
+ * ## Key Insight
+ *
+ * `concatMap` guarantees order by waiting for each inner stream to complete
+ * before starting the next. It's perfect for sequential tasks but is slower
+ * than `mergeMap` because it doesn't run in parallel.
+ *
+ * @typeParam T - Type of values from the source Observable
+ * @typeParam R - Type of values in the result Observable
+ * @param project - Function that maps a source value to an Observable
+ * @returns An operator function that maps and concatenates values
+ */
+export function concatMap(project) {
+    // concatMap is just mergeMap with concurrency = 1
+    return mergeMap(project, 1);
+}
+/**
+ * Transforms items into new streams, but cancels the previous stream when a new
+ * item arrives.
+ *
+ * Like an auto-cancelling search input, it only cares about the latest value
+ * and discards any pending work from previous values.
+ *
+ * @example
+ * ```ts
+ * import { pipe, switchMap, from } from "./helpers/mod.ts";
+ * import { of } from "../../observable.ts";
+ *
+ * // No direct Array equivalent, as it's about handling events over time.
+ *
+ * // Stream behavior for a search input
+ * const queryStream = from(["cat", "cats", "cats rul"]);
+ *
+ * const searchResultStream = pipe(
+ *   queryStream,
+ *   switchMap(query => of(`Results for "${query}"`))
+ * );
+ *
+ * // Assuming each query arrives before the last one "completes":
+ * // The first two searches for "cat" and "cats" would be cancelled.
+ * // The final output would only be: 'Results for "cats rul"'
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * `switchMap` is essential for live search bars or any UI element that
+ * triggers frequent events. It ensures that only the results for the most
+ * recent event are processed, preventing outdated or out-of-order results.
+ *
+ * ## Key Insight
+ *
+ * `switchMap` is the operator of choice for handling rapid-fire events where
+ * only the latest matters. It prevents race conditions and keeps your UI
+ * responsive by cancelling stale, in-flight operations.
+ *
+ * @typeParam T - Type of values from the source Observable
+ * @typeParam R - Type of values in the result Observable
+ * @param project - Function that maps a source value to an Observable
+ * @returns An operator function that maps and switches between values
+ */
+export function switchMap(project) {
+    return createStatefulOperator({
+        name: "switchMap",
+        // Initialize state
+        createState: () => ({
+            currentController: null,
+            currentTask: null,
+            currentTaskToken: null,
+            sourceCompleted: false,
+            index: 0,
+        }),
+        // Process each incoming chunk
+        transform(chunk, state, controller) {
+            if (isObservableError(chunk)) {
+                // If the chunk is an error, we can immediately enqueue it
+                controller.enqueue(chunk);
+                return;
+            }
+            // Cancel any existing inner subscription
+            if (state.currentController) {
+                state.currentController.abort();
+                state.currentController = null;
+            }
+            let innerObservable;
+            try {
+                // Apply projection function to get inner Observable
+                innerObservable = project(chunk, state.index++);
+            }
+            catch (err) {
+                // Forward any errors from the projection function
+                controller.enqueue(ObservableError.from(err, "operator:stateful:switchMap:project", chunk));
+                return;
+            }
+            // Create a new abort controller for this inner subscription
+            const abortController = new AbortController();
+            state.currentController = abortController;
+            // Subscribe to the new inner Observable
+            const currentTaskToken = {};
+            const currentTask = (async () => {
+                const enqueueIfActive = (value) => {
+                    if (abortController.signal.aborted ||
+                        state.currentController !== abortController) {
+                        return;
+                    }
+                    try {
+                        controller.enqueue(value);
+                    }
+                    catch {
+                        abortController.abort();
+                    }
+                };
+                try {
+                    const iterator = pull(innerObservable, { throwError: false })[Symbol.asyncIterator]();
+                    while (!abortController.signal.aborted) {
+                        const { value, done } = await iterator.next();
+                        // If the controller is aborted or we're done, exit the loop
+                        if (abortController.signal.aborted || done)
+                            break;
+                        // Forward the value
+                        enqueueIfActive(value);
+                    }
+                }
+                catch (err) {
+                    if (!abortController.signal.aborted) {
+                        enqueueIfActive(ObservableError.from(err, "operator:stateful:switchMap:innerObservable", chunk));
+                    }
+                }
+                finally {
+                    if (state.currentTaskToken === currentTaskToken) {
+                        state.currentTask = null;
+                        state.currentTaskToken = null;
+                    }
+                    // Only handle completion if this is still the current controller
+                    if (state.currentController === abortController) {
+                        state.currentController = null;
+                        // If source is completed and we have no active inner, we're done
+                        // Stream will close naturally
+                    }
+                }
+            })();
+            state.currentTask = currentTask;
+            state.currentTaskToken = currentTaskToken;
+        },
+        // Handle the end of the source stream
+        async flush(state) {
+            // Mark the source as completed
+            state.sourceCompleted = true;
+            if (state.currentTask) {
+                await state.currentTask;
+            }
+        },
+        // Handle cancellation
+        cancel(state) {
+            // Cancel the current inner subscription
+            if (state.currentController) {
+                state.currentController.abort();
+                state.currentController = null;
+            }
+            state.currentTask = null;
+            state.currentTaskToken = null;
+        },
+    });
+}

package/esm/helpers/operations/conditional.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Predicate and decision-oriented operators for Observable streams.
+ *
+ * This entrypoint exports the operators that answer questions about a stream or
+ * gate values based on a condition. These are the Observable equivalents of
+ * array helpers such as `every()`, `some()`, and `find()`, plus utilities that
+ * stop early once a decision has been reached.
+ *
+ * Reach for this module when you care about whether a stream contains a match,
+ * whether every value passes a rule, or when processing should stop as soon as
+ * the answer is known.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+import type { ExcludeError, Operator } from "../_types.js";
+import type { ObservableError } from "../../error.js";
+/**
+ * Checks if every item in the stream passes a test.
+ *
+ * Like `Array.prototype.every()`, it stops and returns `false` on the first
+ * failure. If the stream completes without any failures, it returns `true`.
+ *
+ * @example
+ * ```ts
+ * import { pipe, every, from } from "./helpers/mod.ts";
+ *
+ * // Array behavior
+ * const allEven = [2, 4, 6].every(n => n % 2 === 0); // true
+ * const someOdd = [2, 4, 5].every(n => n % 2 === 0); // false
+ *
+ * // Stream behavior
+ * const allEvenStream = from([2, 4, 6]);
+ * const result1 = await pipe(allEvenStream, every(n => n % 2 === 0)).toPromise(); // true
+ *
+ * const someOddStream = from([2, 4, 5]);
+ * const result2 = await pipe(someOddStream, every(n => n % 2 === 0)).toPromise(); // false
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `every` to verify that all items in a stream meet a certain condition,
+ * such as ensuring all uploaded files are of the correct type or that all
+ * API responses were successful.
+ *
+ * ## Key Insight
+ *
+ * `every` provides a definitive boolean answer for the entire stream, making
+ * it a final, summary operation.
+ *
+ * @typeParam T - Type of values from the source stream
+ * @param predicate - Function to test each value
+ * @returns A stream operator that tests all values
+ */
+export declare function every<T>(predicate: (value: ExcludeError<T>, index: number) => boolean): Operator<T | ObservableError, boolean | ObservableError>;
+/**
+ * Checks if at least one item in the stream passes a test.
+ *
+ * Like `Array.prototype.some()`, it stops and returns `true` on the first
+ * success. If the stream completes without any successes, it returns `false`.
+ *
+ * @example
+ * ```ts
+ * import { pipe, some, from } from "./helpers/mod.ts";
+ *
+ * // Array behavior
+ * const hasEven = [1, 3, 4].some(n => n % 2 === 0); // true
+ * const noEven = [1, 3, 5].some(n => n % 2 === 0); // false
+ *
+ * // Stream behavior
+ * const hasEvenStream = from([1, 3, 4]);
+ * const result1 = await pipe(hasEvenStream, some(n => n % 2 === 0)).toPromise(); // true
+ *
+ * const noEvenStream = from([1, 3, 5]);
+ * const result2 = await pipe(noEvenStream, some(n => n % 2 === 0)).toPromise(); // false
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `some` to quickly determine if a condition is met by any item in a
+ * stream, such as checking for the existence of a specific user permission or
+ * detecting if any item in a batch has an error.
+ *
+ * ## Key Insight
+ *
+ * `some` is an efficient way to get a "yes" or "no" answer from a stream
+ * without processing all the items.
+ *
+ * @typeParam T - Type of values from the source stream
+ * @param predicate - Function to test each value
+ * @returns A stream operator that tests for any matching value
+ */
+export declare function some<T>(predicate: (value: ExcludeError<T>, index: number) => boolean): Operator<T | ObservableError, boolean | ObservableError>;
+/**
+ * Finds the first item in the stream that passes a test.
+ *
+ * Like `Array.prototype.find()`, it stops and emits the first matching item,
+ * then immediately completes the stream.
+ *
+ * @example
+ * ```ts
+ * import { pipe, find, from } from "./helpers/mod.ts";
+ *
+ * // Array behavior
+ * const firstEven = [1, 3, 4, 6].find(n => n % 2 === 0); // 4
+ *
+ * // Stream behavior
+ * const numberStream = from([1, 3, 4, 6]);
+ * const result = await pipe(numberStream, find(n => n % 2 === 0)).toPromise(); // 4
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `find` to locate a specific record or event in a stream without needing
+ * to process the entire dataset, such as finding the first available time slot
+ * or the first user to log in.
+ *
+ * ## Key Insight
+ *
+ * `find` is an efficient shortcut to get the first item you care about from a
+ * potentially long stream.
+ *
+ * @typeParam T - Type of values from the source stream
+ * @param predicate - Function to test each value
+ * @returns A stream operator that finds the first matching value
+ */
+export declare function find<T>(predicate: (value: ExcludeError<T>, index: number) => boolean): Operator<T | ObservableError, T | ObservableError>;
+/**
+ * Removes duplicate values from the stream, keeping only the first occurrence.
+ *
+ * Like creating a `new Set()` from an array, but for async streams. You can
+ * provide a `keySelector` to determine uniqueness based on an object property.
+ *
+ * @example
+ * ```ts
+ * import { pipe, unique, from } from "./helpers/mod.ts";
+ *
+ * // Array behavior
+ * const uniqueNumbers = [...new Set([1, 2, 2, 3, 1])]; // [1, 2, 3]
+ *
+ * // Stream behavior
+ * const numberStream = from([1, 2, 2, 3, 1]);
+ * const uniqueStream = pipe(numberStream, unique()); // Emits 1, 2, 3
+ *
+ * // With a key selector
+ * const users = [{ id: 1, name: 'A' }, { id: 2, name: 'B' }, { id: 1, name: 'C' }];
+ * const userStream = from(users);
+ * const uniqueUserStream = pipe(userStream, unique(user => user.id)); // Emits { id: 1, name: 'A' }, { id: 2, name: 'B' }
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `unique` to de-duplicate a stream of events or data, such as processing
+ * a list of user IDs where some may appear multiple times, or handling event
+ * streams that might emit the same event more than once.
+ *
+ * ## Key Insight
+ *
+ * `unique` simplifies de-duplication in asynchronous pipelines, ensuring that
+ * downstream operations only run once for each unique item.
+ *
+ * @typeParam T The type of items in the stream.
+ * @typeParam K The type of the key used for uniqueness checks.
+ * @param keySelector An optional function to extract a key for uniqueness comparison.
+ * @returns An operator that filters out duplicate values.
+ */
+export declare function unique<T, K = T>(keySelector?: (value: ExcludeError<T>) => K): Operator<T | ObservableError, ExcludeError<T> | ObservableError>;
+/**
+ * Emits an item only if it is different from the previous one.
+ *
+ * This is useful for streams where values can be emitted repeatedly, but you
+ * only care about the changes.
+ *
+ * @example
+ * ```ts
+ * import { pipe, changed, from } from "./helpers/mod.ts";
+ *
+ * // No direct Array equivalent, as it depends on sequence.
+ *
+ * // Stream behavior
+ * const valueStream = from([1, 1, 2, 2, 2, 1, 3]);
+ * const changedStream = pipe(valueStream, changed()); // Emits 1, 2, 1, 3
+ *
+ * // With a key selector
+ * const userStream = from([
+ *   { id: 1, status: 'active' },
+ *   { id: 1, status: 'active' },
+ *   { id: 1, status: 'inactive' }
+ * ]);
+ * const statusChangeStream = pipe(userStream, changed(user => user.status));
+ * // Emits { id: 1, status: 'active' }, { id: 1, status: 'inactive' }
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `changed` to monitor a stream of state updates and only react when the
+ * state actually changes. This is common in UI programming for tracking user
+ * input or state management.
+ *
+ * ## Key Insight
+ *
+ * `changed` filters out noise from repetitive values, allowing you to focus
+ * on the moments when something actually changes.
+ *
+ * @typeParam T The type of items in the stream.
+ * @typeParam K The type of the key used for comparison.
+ * @param keySelector An optional function to extract a key for comparison.
+ * @param compare An optional function to compare two keys for equality.
+ * @returns An operator that filters out consecutive duplicate values.
+ */
+//# sourceMappingURL=conditional.d.ts.map

package/esm/helpers/operations/conditional.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditional.d.ts","sourceRoot":"","sources":["../../../src/helpers/operations/conditional.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAItD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,KAAK,CAAC,CAAC,EACrB,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAC5D,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,OAAO,GAAG,eAAe,CAAC,CA2B1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACpB,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAC5D,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,OAAO,GAAG,eAAe,CAAC,CA2B1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACpB,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAC5D,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAcpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAC7B,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,GAC1C,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAqBlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG"}