@okikio/observables 1.0.2 → 1.3.0

package/esm/helpers/operations/combination.js

@@ -18,6 +18,77 @@ import "../../_dnt.polyfills.js";
 import { createStatefulOperator } from "../operators.js";
 import { isObservableError, ObservableError } from "../../error.js";
 import { pull } from "../../observable.js";
+import { createQueue, dequeue, enqueue, getSize, isFull, toArray, } from "../../queue.js";
+/**
+ * Cancels an iterator if it exposes `return()`.
+ *
+ * Most iterators created through `pull()` do expose `return()`, and calling it
+ * is the Observable equivalent of saying "the consumer is done, release any
+ * held resources now".
+ */
+async function cancelIterator(iterator) {
+    if (iterator?.return) {
+        await iterator.return();
+    }
+}
+/**
+ * Rebuilds the strongly typed tuple returned by the combination operators.
+ *
+ * The runtime data is stored in mutable `unknown[]` buffers because values are
+ * filled over time. This helper isolates the final cast to one place, and the
+ * cast is sound because every caller preserves the exact length and ordering of
+ * the original companion Observable tuple.
+ */
+function toCombinationTuple(sourceValue, otherValues) {
+    return [
+        sourceValue,
+        ...otherValues,
+    ];
+}
+/**
+ * Removes one queued value from each companion queue in order.
+ *
+ * Callers only use this after checking that every queue has at least one value.
+ * That precondition is what makes the returned tuple complete instead of partly
+ * `undefined`.
+ */
+function shiftQueuedValues(queues) {
+    return queues.map((queue) => dequeue(queue));
+}
+/**
+ * Starts zip queues small and lets them grow only when buffering actually
+ * happens.
+ *
+ * `zipWith()` can run for a long time, so this avoids paying for large backing
+ * arrays up front while still keeping steady-state dequeue work O(1).
+ */
+const INITIAL_ZIP_QUEUE_CAPACITY = 16;
+/**
+ * Returns whether a queue currently has at least one buffered value.
+ */
+function hasQueuedValue(queue) {
+    return getSize(queue) > 0;
+}
+/**
+ * Appends a value to a queue, growing the underlying circular buffer when the
+ * current capacity is exhausted.
+ *
+ * The shared queue utilities are fixed-capacity by design. `zipWith()` needs
+ * unbounded logical buffering, so this helper preserves the queue API while
+ * replacing the backing queue with a larger one only when necessary.
+ */
+function enqueueQueuedValue(queue, value) {
+    if (!isFull(queue)) {
+        enqueue(queue, value);
+        return queue;
+    }
+    const grownQueue = createQueue(Math.max(queue.capacity * 2, 1));
+    for (const item of toArray(queue)) {
+        enqueue(grownQueue, item);
+    }
+    enqueue(grownQueue, value);
+    return grownQueue;
+}
 /**
  * Transforms each item into a new stream and merges their outputs, running
  * them in parallel.
@@ -64,87 +135,133 @@ import { pull } from "../../observable.js";
  * @returns An operator function that maps and flattens values
  */
 export function mergeMap(project, concurrent = Infinity) {
+    const maxConcurrent = concurrent > 0 ? concurrent : 1;
     return createStatefulOperator({
         name: "mergeMap",
-        // Initialize state
+        errorMode: "pass-through",
         createState: () => ({
-            activeSubscriptions: new Map(),
+            activeIterators: new Map(),
+            activeTasks: new Set(),
             buffer: [],
-            sourceCompleted: false,
             index: 0,
             activeCount: 0,
+            idleDeferred: null,
+            isCancelled: false,
+            sourceCompleted: false,
         }),
-        // 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) {
+        transform(chunk, state, controller) {
+            const value = chunk;
+            const sourceIndex = state.index++;
+            // `flush()` must wait for both active inners and buffered outers.
+            // Resolving this gate too early would let the operator finish while inner
+            // work is still producing values.
+            const resolveIfIdle = () => {
+                if (state.sourceCompleted &&
+                    state.activeCount === 0 &&
+                    state.buffer.length === 0 &&
+                    state.idleDeferred) {
+                    state.idleDeferred.resolve();
+                    state.idleDeferred = null;
+                }
+            };
+            // Keep filling free concurrency slots until either the buffer is empty or
+            // the operator reaches its configured parallelism limit.
+            const drainBuffer = () => {
+                while (!state.isCancelled &&
+                    state.activeCount < maxConcurrent &&
+                    state.buffer.length > 0) {
+                    const next = state.buffer.shift();
+                    if (!next)
+                        break;
+                    launchProjection(next[0], next[1]);
+                }
+                resolveIfIdle();
+            };
+            // Start draining one projected inner Observable and keep enough metadata
+            // around to cancel or await it later.
+            const launchProjection = (innerValue, innerIndex) => {
                 let innerObservable;
                 try {
-                    // Apply projection function to get inner Observable
-                    innerObservable = project(value, innerIndex);
+                    innerObservable = project(innerValue, innerIndex);
                 }
                 catch (err) {
-                    // Forward any errors from the projection function
-                    controller.enqueue(ObservableError.from(err, "operator:stateful:mergeMap:project", value));
+                    try {
+                        controller.enqueue(ObservableError.from(err, "operator:stateful:mergeMap:project", innerValue));
+                    }
+                    catch {
+                        // Downstream cancellation already decided the stream outcome.
+                    }
+                    drainBuffer();
                     return;
                 }
                 state.activeCount++;
-                // Use pull to iterate asynchronously
-                try {
-                    for await (const innerValue of pull(innerObservable, { throwError: false })) {
-                        controller.enqueue(innerValue);
+                const iterator = pull(innerObservable, { throwError: false })[Symbol.asyncIterator]();
+                state.activeIterators.set(innerIndex, iterator);
+                const taskRef = { current: null };
+                const task = (async () => {
+                    try {
+                        while (!state.isCancelled) {
+                            const { value: emittedValue, done } = await iterator.next();
+                            if (done || state.isCancelled) {
+                                break;
+                            }
+                            try {
+                                controller.enqueue(emittedValue);
+                            }
+                            catch {
+                                break;
+                            }
+                        }
                     }
-                }
-                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
+                    catch (err) {
+                        if (!state.isCancelled) {
+                            try {
+                                controller.enqueue(ObservableError.from(err, "operator:stateful:mergeMap:innerObservable", innerValue));
+                            }
+                            catch {
+                                // Downstream cancellation already decided the stream outcome.
+                            }
+                        }
+                    }
+                    finally {
+                        state.activeIterators.delete(innerIndex);
+                        if (taskRef.current) {
+                            state.activeTasks.delete(taskRef.current);
+                        }
+                        state.activeCount--;
+                        drainBuffer();
+                    }
+                })();
+                taskRef.current = task;
+                state.activeTasks.add(task);
+            };
+            if (state.activeCount < maxConcurrent) {
+                launchProjection(value, sourceIndex);
+                return;
             }
+            state.buffer.push([value, sourceIndex]);
         },
-        // Handle the end of the source stream
-        flush(state) {
-            // Mark the source as completed
+        async flush(state) {
             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();
+            if (state.activeCount === 0 && state.buffer.length === 0) {
+                return;
             }
-            // Clear the buffer and state
+            state.idleDeferred ??= Promise.withResolvers();
+            await state.idleDeferred.promise;
+        },
+        async cancel(state) {
+            state.isCancelled = true;
             state.buffer.length = 0;
-            state.activeSubscriptions.clear();
+            const iterators = [...state.activeIterators.values()];
+            state.activeIterators.clear();
+            await Promise.allSettled(iterators.map((iterator) => iterator.return?.()));
+            await Promise.allSettled([...state.activeTasks]);
+            state.activeTasks.clear();
             state.activeCount = 0;
+            if (state.idleDeferred) {
+                state.idleDeferred.resolve();
+                state.idleDeferred = null;
+            }
         },
     });
 }
@@ -248,25 +365,36 @@ export function concatMap(project) {
 export function switchMap(project) {
     return createStatefulOperator({
         name: "switchMap",
-        // Initialize state
+        errorMode: "pass-through",
         createState: () => ({
-            currentController: null,
+            currentIterator: null,
             currentTask: null,
             currentTaskToken: null,
-            sourceCompleted: false,
+            isCancelled: 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;
+        async transform(chunk, state, controller) {
+            /**
+             * Stops the current inner Observable before a newer one replaces it.
+             *
+             * The order matters: `return()` asks the iterator to clean up, then we
+             * await the draining task so no stale emissions race with the next inner.
+             */
+            const stopCurrent = async () => {
+                const iterator = state.currentIterator;
+                const task = state.currentTask;
+                state.currentIterator = null;
+                state.currentTask = null;
+                state.currentTaskToken = null;
+                if (iterator?.return) {
+                    await iterator.return();
+                }
+                if (task) {
+                    await task;
+                }
+            };
+            if (state.currentTaskToken || state.currentIterator || state.currentTask) {
+                await stopCurrent();
             }
             let innerObservable;
             try {
@@ -278,73 +406,512 @@ export function switchMap(project) {
                 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 iterator = pull(innerObservable, { throwError: false })[Symbol.asyncIterator]();
+            state.currentTaskToken = currentTaskToken;
+            state.currentIterator = iterator;
+            const currentTaskRef = {
+                current: null,
+            };
             const currentTask = (async () => {
-                const enqueueIfActive = (value) => {
-                    if (abortController.signal.aborted ||
-                        state.currentController !== abortController) {
-                        return;
-                    }
-                    try {
-                        controller.enqueue(value);
-                    }
-                    catch {
-                        abortController.abort();
-                    }
+                const isActive = () => {
+                    return !state.isCancelled && state.currentTaskToken === currentTaskToken;
                 };
                 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)
+                    while (isActive()) {
+                        const { value: emittedValue, done } = await iterator.next();
+                        if (done || !isActive()) {
                             break;
-                        // Forward the value
-                        enqueueIfActive(value);
+                        }
+                        try {
+                            controller.enqueue(emittedValue);
+                        }
+                        catch {
+                            break;
+                        }
                     }
                 }
                 catch (err) {
-                    if (!abortController.signal.aborted) {
-                        enqueueIfActive(ObservableError.from(err, "operator:stateful:switchMap:innerObservable", chunk));
+                    if (isActive()) {
+                        try {
+                            controller.enqueue(ObservableError.from(err, "operator:stateful:switchMap:innerObservable", chunk));
+                        }
+                        catch {
+                            // Downstream cancellation already decided the stream outcome.
+                        }
                     }
                 }
                 finally {
-                    if (state.currentTaskToken === currentTaskToken) {
+                    if (state.currentIterator === iterator) {
+                        state.currentIterator = null;
+                    }
+                    if (state.currentTask === currentTaskRef.current) {
                         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
+                    if (state.currentTaskToken === currentTaskToken) {
+                        state.currentTaskToken = null;
                     }
                 }
             })();
+            currentTaskRef.current = currentTask;
             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;
+        async cancel(state) {
+            state.isCancelled = true;
+            if (state.currentIterator?.return) {
+                await state.currentIterator.return();
             }
+            if (state.currentTask) {
+                await state.currentTask;
+            }
+            state.currentIterator = null;
             state.currentTask = null;
             state.currentTaskToken = null;
         },
     });
 }
+/**
+ * Emits each source value together with the latest value from every companion
+ * Observable.
+ *
+ * This operator waits until every companion Observable has produced at least
+ * one value. After that gate opens, each new source value emits a tuple that
+ * includes the source value followed by the most recent companion values.
+ *
+ * ```text
+ * companion A: ---a----b-------c--
+ * companion B: -----x-------y-----
+ * source:      ------1--2------3--
+ * output:      ------[1,a,x][2,b,x][3,c,y]
+ * ```
+ *
+ * The source still decides when outputs happen. Companion Observables only
+ * update the remembered latest values.
+ *
+ * @typeParam T - Value type from the primary source
+ * @typeParam TOthers - Value types from the companion Observables
+ * @param others - Companion Observables whose latest values should be attached
+ * @returns An operator that emits tuples of the source value and latest others
+ */
+export function withLatestFrom(...others) {
+    return createStatefulOperator({
+        name: "withLatestFrom",
+        errorMode: "pass-through",
+        createState: () => ({
+            latestValues: new Array(others.length),
+            seenLatest: others.map(() => false),
+            iterators: [],
+            tasks: new Set(),
+            isCancelled: false,
+        }),
+        start(state, controller) {
+            // Companion Observables run in the background and only update cached
+            // latest values. They never decide when to emit tuples themselves.
+            others.forEach((observable, index) => {
+                const iterator = pull(observable, { throwError: false })[Symbol.asyncIterator]();
+                state.iterators[index] = iterator;
+                const taskRef = { current: null };
+                const task = (async () => {
+                    try {
+                        while (!state.isCancelled) {
+                            const { value, done } = await iterator.next();
+                            if (done || state.isCancelled) {
+                                break;
+                            }
+                            if (isObservableError(value)) {
+                                try {
+                                    controller.enqueue(value);
+                                }
+                                catch {
+                                    break;
+                                }
+                                continue;
+                            }
+                            state.latestValues[index] = value;
+                            state.seenLatest[index] = true;
+                        }
+                    }
+                    catch (err) {
+                        if (!state.isCancelled) {
+                            try {
+                                controller.enqueue(ObservableError.from(err, "operator:stateful:withLatestFrom:companion", { companionIndex: index }));
+                            }
+                            catch {
+                                // Downstream cancellation already decided the stream outcome.
+                            }
+                        }
+                    }
+                    finally {
+                        if (taskRef.current) {
+                            state.tasks.delete(taskRef.current);
+                        }
+                    }
+                })();
+                taskRef.current = task;
+                state.tasks.add(task);
+            });
+        },
+        transform(chunk, state, controller) {
+            if (!state.seenLatest.every(Boolean)) {
+                return;
+            }
+            controller.enqueue(toCombinationTuple(chunk, state.latestValues));
+        },
+        async flush(state) {
+            await Promise.allSettled([...state.tasks]);
+        },
+        async cancel(state) {
+            state.isCancelled = true;
+            await Promise.allSettled(state.iterators.map((iterator) => cancelIterator(iterator)));
+            await Promise.allSettled([...state.tasks]);
+            state.tasks.clear();
+            state.iterators.length = 0;
+        },
+    });
+}
+/**
+ * Combines the source with companion Observables using combine-latest timing.
+ *
+ * Once every source has emitted at least one value, any new value from the
+ * primary source or a companion Observable emits a new tuple containing the
+ * latest value from each source.
+ *
+ * @typeParam T - Value type from the primary source
+ * @typeParam TOthers - Value types from the companion Observables
+ * @param others - Companion Observables that participate in the latest-value set
+ * @returns An operator that emits tuples of the latest value from every source
+ */
+export function combineLatestWith(...others) {
+    return createStatefulOperator({
+        name: "combineLatestWith",
+        errorMode: "pass-through",
+        createState: () => ({
+            sourceValue: null,
+            hasSourceValue: false,
+            latestValues: new Array(others.length),
+            seenLatest: others.map(() => false),
+            iterators: [],
+            tasks: new Set(),
+            sourceCompleted: false,
+            isCancelled: false,
+        }),
+        start(state, controller) {
+            /**
+             * Emits the full latest tuple only after the source and every companion
+             * have contributed at least one value.
+             */
+            const emitLatest = () => {
+                if (!state.hasSourceValue || !state.seenLatest.every(Boolean)) {
+                    return;
+                }
+                controller.enqueue(toCombinationTuple(state.sourceValue, state.latestValues));
+            };
+            others.forEach((observable, index) => {
+                const iterator = pull(observable, { throwError: false })[Symbol.asyncIterator]();
+                state.iterators[index] = iterator;
+                const taskRef = { current: null };
+                const task = (async () => {
+                    try {
+                        while (!state.isCancelled) {
+                            const { value, done } = await iterator.next();
+                            if (done || state.isCancelled) {
+                                break;
+                            }
+                            if (isObservableError(value)) {
+                                try {
+                                    controller.enqueue(value);
+                                }
+                                catch {
+                                    break;
+                                }
+                                continue;
+                            }
+                            state.latestValues[index] = value;
+                            state.seenLatest[index] = true;
+                            try {
+                                emitLatest();
+                            }
+                            catch {
+                                break;
+                            }
+                        }
+                    }
+                    catch (err) {
+                        if (!state.isCancelled) {
+                            try {
+                                controller.enqueue(ObservableError.from(err, "operator:stateful:combineLatestWith:companion", { companionIndex: index }));
+                            }
+                            catch {
+                                // Downstream cancellation already decided the stream outcome.
+                            }
+                        }
+                    }
+                    finally {
+                        if (taskRef.current) {
+                            state.tasks.delete(taskRef.current);
+                        }
+                    }
+                })();
+                taskRef.current = task;
+                state.tasks.add(task);
+            });
+        },
+        transform(chunk, state, controller) {
+            state.sourceValue = chunk;
+            state.hasSourceValue = true;
+            if (!state.seenLatest.every(Boolean)) {
+                return;
+            }
+            controller.enqueue(toCombinationTuple(state.sourceValue, state.latestValues));
+        },
+        async flush(state) {
+            state.sourceCompleted = true;
+            await Promise.allSettled([...state.tasks]);
+        },
+        async cancel(state) {
+            state.isCancelled = true;
+            await Promise.allSettled(state.iterators.map((iterator) => cancelIterator(iterator)));
+            await Promise.allSettled([...state.tasks]);
+            state.tasks.clear();
+            state.iterators.length = 0;
+        },
+    });
+}
+/**
+ * Pairs source values with companion values in strict arrival order.
+ *
+ * `zipWith` waits until it has one value from the source and one value from
+ * each companion. It then emits a tuple and removes those values from the
+ * queues before waiting for the next full set.
+ *
+ * @typeParam T - Value type from the primary source
+ * @typeParam TOthers - Value types from the companion Observables
+ * @param others - Companion Observables to align by arrival order
+ * @returns An operator that emits tuples aligned by position instead of time
+ */
+export function zipWith(...others) {
+    return createStatefulOperator({
+        name: "zipWith",
+        errorMode: "pass-through",
+        createState: () => ({
+            sourceQueue: createQueue(INITIAL_ZIP_QUEUE_CAPACITY),
+            otherQueues: others.map(() => createQueue(INITIAL_ZIP_QUEUE_CAPACITY)),
+            sourceCompleted: false,
+            otherCompleted: others.map(() => false),
+            iterators: [],
+            tasks: new Set(),
+            isCancelled: false,
+            isTerminated: false,
+        }),
+        start(state, controller) {
+            /**
+             * Emits as many full zip tuples as are currently available.
+             *
+             * The termination logic is important: once a completed companion has no
+             * queued value left, zip can never produce another full tuple, so the
+             * operator terminates immediately instead of waiting for the source to end.
+             */
+            const emitAvailable = () => {
+                while (!state.isTerminated &&
+                    hasQueuedValue(state.sourceQueue) &&
+                    state.otherQueues.every((queue) => hasQueuedValue(queue))) {
+                    controller.enqueue(toCombinationTuple(dequeue(state.sourceQueue), shiftQueuedValues(state.otherQueues)));
+                }
+                const blockedByCompletedCompanion = state.otherCompleted.some((completed, index) => completed && !hasQueuedValue(state.otherQueues[index]));
+                if (!state.isTerminated &&
+                    (blockedByCompletedCompanion ||
+                        (state.sourceCompleted && !hasQueuedValue(state.sourceQueue)))) {
+                    state.isTerminated = true;
+                    controller.terminate();
+                }
+            };
+            others.forEach((observable, index) => {
+                const iterator = pull(observable, { throwError: false })[Symbol.asyncIterator]();
+                state.iterators[index] = iterator;
+                const taskRef = { current: null };
+                const task = (async () => {
+                    try {
+                        while (!state.isCancelled && !state.isTerminated) {
+                            const { value, done } = await iterator.next();
+                            if (done || state.isCancelled || state.isTerminated) {
+                                break;
+                            }
+                            if (isObservableError(value)) {
+                                try {
+                                    controller.enqueue(value);
+                                }
+                                catch {
+                                    break;
+                                }
+                                continue;
+                            }
+                            state.otherQueues[index] = enqueueQueuedValue(state.otherQueues[index], value);
+                            emitAvailable();
+                        }
+                    }
+                    catch (err) {
+                        if (!state.isCancelled && !state.isTerminated) {
+                            try {
+                                controller.enqueue(ObservableError.from(err, "operator:stateful:zipWith:companion", { companionIndex: index }));
+                            }
+                            catch {
+                                // Downstream cancellation already decided the stream outcome.
+                            }
+                        }
+                    }
+                    finally {
+                        state.otherCompleted[index] = true;
+                        if (taskRef.current) {
+                            state.tasks.delete(taskRef.current);
+                        }
+                        if (!state.isCancelled && !state.isTerminated) {
+                            emitAvailable();
+                        }
+                    }
+                })();
+                taskRef.current = task;
+                state.tasks.add(task);
+            });
+        },
+        transform(chunk, state, controller) {
+            state.sourceQueue = enqueueQueuedValue(state.sourceQueue, chunk);
+            while (!state.isTerminated &&
+                hasQueuedValue(state.sourceQueue) &&
+                state.otherQueues.every((queue) => hasQueuedValue(queue))) {
+                controller.enqueue(toCombinationTuple(dequeue(state.sourceQueue), shiftQueuedValues(state.otherQueues)));
+            }
+            const blockedByCompletedCompanion = state.otherCompleted.some((completed, index) => completed && !hasQueuedValue(state.otherQueues[index]));
+            if (!state.isTerminated && blockedByCompletedCompanion) {
+                state.isTerminated = true;
+                controller.terminate();
+            }
+        },
+        async flush(state, controller) {
+            state.sourceCompleted = true;
+            if (!state.isTerminated && !hasQueuedValue(state.sourceQueue)) {
+                state.isTerminated = true;
+                controller.terminate();
+            }
+            await Promise.allSettled([...state.tasks]);
+        },
+        async cancel(state) {
+            state.isCancelled = true;
+            await Promise.allSettled(state.iterators.map((iterator) => cancelIterator(iterator)));
+            await Promise.allSettled([...state.tasks]);
+            state.tasks.clear();
+            state.iterators.length = 0;
+        },
+    });
+}
+/**
+ * Mirrors whichever Observable emits first: the source or one of the
+ * companions.
+ *
+ * If the primary source wins, future source values keep flowing and companion
+ * Observables are cancelled. If a companion wins, the source is ignored from
+ * that point on and the winning companion continues to drive the output.
+ *
+ * @typeParam T - Value type from the primary source
+ * @typeParam TOthers - Value types from the companion Observables
+ * @param others - Companion Observables racing against the source
+ * @returns An operator that mirrors the winning Observable
+ */
+export function raceWith(...others) {
+    return createStatefulOperator({
+        name: "raceWith",
+        errorMode: "pass-through",
+        createState: () => ({
+            winner: null,
+            iterators: [],
+            tasks: new Set(),
+            sourceCompleted: false,
+            isCancelled: false,
+        }),
+        start(state, controller) {
+            /**
+             * Cancels every companion except the winning one.
+             *
+             * `raceWith()` is intentionally ruthless: once the first value arrives,
+             * every loser is stopped so only one Observable continues to drive output.
+             */
+            const cancelLosers = async (winnerIndex) => {
+                const loserIterators = state.iterators.filter((_, index) => index !== winnerIndex);
+                await Promise.allSettled(loserIterators.map((iterator) => cancelIterator(iterator)));
+            };
+            others.forEach((observable, index) => {
+                const iterator = pull(observable, { throwError: false })[Symbol.asyncIterator]();
+                state.iterators[index] = iterator;
+                const taskRef = { current: null };
+                const task = (async () => {
+                    try {
+                        while (!state.isCancelled) {
+                            const { value, done } = await iterator.next();
+                            if (done || state.isCancelled) {
+                                break;
+                            }
+                            if (state.winner === null) {
+                                state.winner = index;
+                                await cancelLosers(index);
+                            }
+                            if (state.winner !== index) {
+                                break;
+                            }
+                            try {
+                                controller.enqueue(value);
+                            }
+                            catch {
+                                break;
+                            }
+                        }
+                    }
+                    catch (err) {
+                        if (!state.isCancelled && state.winner === index) {
+                            try {
+                                controller.enqueue(ObservableError.from(err, "operator:stateful:raceWith:companion", { companionIndex: index }));
+                            }
+                            catch {
+                                // Downstream cancellation already decided the stream outcome.
+                            }
+                        }
+                    }
+                    finally {
+                        if (taskRef.current) {
+                            state.tasks.delete(taskRef.current);
+                        }
+                    }
+                })();
+                taskRef.current = task;
+                state.tasks.add(task);
+            });
+        },
+        async transform(chunk, state, controller) {
+            if (state.winner === null) {
+                state.winner = "source";
+                await Promise.allSettled(state.iterators.map((iterator) => cancelIterator(iterator)));
+            }
+            if (state.winner !== "source") {
+                return;
+            }
+            controller.enqueue(chunk);
+        },
+        async flush(state) {
+            state.sourceCompleted = true;
+            if (state.winner === "source") {
+                return;
+            }
+            await Promise.allSettled([...state.tasks]);
+        },
+        async cancel(state) {
+            state.isCancelled = true;
+            await Promise.allSettled(state.iterators.map((iterator) => cancelIterator(iterator)));
+            await Promise.allSettled([...state.tasks]);
+            state.tasks.clear();
+            state.iterators.length = 0;
+        },
+    });
+}