@okikio/observables 1.0.2 → 1.3.0

package/script/helpers/utils.js

@@ -4,8 +4,13 @@ exports.isTransformStreamOptions = isTransformStreamOptions;
 exports.isTransformFunctionOptions = isTransformFunctionOptions;
 exports.applyOperator = applyOperator;
 exports.toStream = toStream;
+exports.fromStreamPair = fromStreamPair;
+exports.streamAsObservable = streamAsObservable;
+exports.observableInputToStream = observableInputToStream;
+exports.fromObservableOperator = fromObservableOperator;
 exports.injectError = injectError;
 const error_js_1 = require("../error.js");
+const observable_js_1 = require("../observable.js");
 /**
  * Type guard to check if options is a TransformStreamOptions
  *
@@ -125,6 +130,173 @@ function toStream(iterable) {
         },
     });
 }
+/**
+ * Adapts a readable/writable stream pair into an Observable operator.
+ *
+ * Some platform transforms, such as `CompressionStream`, expose a writable side
+ * and a readable side without being created through this library's operator
+ * builders. This helper turns that pair into a normal `Operator` so it can be
+ * used inside `pipe()` like any built-in operator.
+ *
+ * A fresh pair is created for each operator application. That preserves the
+ * cold semantics of the surrounding Observable pipeline and avoids reusing a
+ * consumed stream pair across subscriptions.
+ *
+ * @typeParam TIn - Chunk type written into the pair
+ * @typeParam TOut - Chunk type read from the pair
+ * @param createPair - Factory that returns a fresh readable/writable pair
+ * @returns An operator that pipes input through the created pair
+ *
+ * @example
+ * ```ts
+ * const gzip = fromStreamPair<Uint8Array, Uint8Array>(
+ *   () => new CompressionStream('gzip')
+ * );
+ * ```
+ */
+function fromStreamPair(createPair) {
+    return (source) => source.pipeThrough(createPair());
+}
+/**
+ * Wraps a `ReadableStream` as an Observable so foreign Observable-style
+ * operators can subscribe to it directly.
+ *
+ * This avoids first converting the stream into an async-iterable Observable via
+ * `Observable.from()`, which would add an extra adaptation layer before the
+ * foreign operator even starts running.
+ */
+function streamAsObservable(stream) {
+    return new observable_js_1.Observable((observer) => {
+        const reader = stream.getReader();
+        let cancelled = false;
+        void (async () => {
+            try {
+                while (!cancelled && !observer.closed) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        break;
+                    }
+                    observer.next(value);
+                }
+                if (!cancelled && !observer.closed) {
+                    observer.complete();
+                }
+            }
+            catch (err) {
+                if (!cancelled && !observer.closed) {
+                    observer.error(err);
+                }
+            }
+            finally {
+                try {
+                    reader.releaseLock();
+                }
+                catch {
+                    // Releasing the reader is best-effort during teardown.
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            void reader.cancel();
+        };
+    });
+}
+/**
+ * Returns true when a value exposes a direct `subscribe()` method.
+ *
+ * Many Observable libraries return subscribable objects that are usable without
+ * first going through this library's `Observable.from()`. Detecting that shape
+ * lets interop stay direct for outputs such as RxJS Observables.
+ */
+function hasSubscribe(input) {
+    return typeof input === "object" && input !== null &&
+        typeof input.subscribe === "function";
+}
+/**
+ * Subscribes to an Observable-like output and exposes it as a ReadableStream.
+ *
+ * Foreign operators are allowed to return either a normal `Observable.from()`
+ * input or a direct subscribable from another Observable implementation.
+ * Converting the result with a direct subscription avoids the extra
+ * async-generator and stream layers that `pull(...)+toStream()` would add.
+ */
+function observableInputToStream(input, errorContext) {
+    let subscription;
+    return new ReadableStream({
+        start(controller) {
+            const source = hasSubscribe(input) ? input : observable_js_1.Observable.from(input);
+            subscription = source.subscribe({
+                next(value) {
+                    try {
+                        controller.enqueue(value);
+                    }
+                    catch {
+                        // Downstream cancellation already decided the stream outcome.
+                    }
+                },
+                error(error) {
+                    try {
+                        controller.enqueue(error_js_1.ObservableError.from(error, errorContext));
+                        controller.close();
+                    }
+                    catch {
+                        // Downstream cancellation already decided the stream outcome.
+                    }
+                },
+                complete() {
+                    try {
+                        controller.close();
+                    }
+                    catch {
+                        // Downstream cancellation already decided the stream outcome.
+                    }
+                },
+            });
+        },
+        cancel() {
+            subscription?.unsubscribe?.();
+            subscription = undefined;
+        },
+    });
+}
+/**
+ * Adapts a foreign Observable-style operator into a stream operator.
+ *
+ * Libraries such as RxJS model operators as functions from one Observable-like
+ * source to another Observable-like result. This helper bridges that shape into
+ * this library's `Operator` contract by:
+ *
+ * 1. wrapping the input stream as an Observable-like source
+ * 2. calling the foreign operator
+ * 3. converting the resulting Observable-like output back into a stream
+ *
+ * The result keeps this library's buffered error behavior by converting the
+ * foreign output into a `ReadableStream` that enqueues wrapped
+ * `ObservableError` values instead of failing the readable side outright.
+ *
+ * @typeParam TIn - Value type accepted by the foreign operator
+ * @typeParam TOut - Value type produced by the foreign operator
+ * @param operator - Foreign operator function to adapt
+ * @returns An operator compatible with this library's `pipe()`
+ *
+ * @example
+ * ```ts
+ * const foreignTakeOne = fromObservableOperator<number, number>((source) =>
+ *   rxTake(1)(source)
+ * , { sourceAdapter: (source) => rxFrom(source) });
+ * ```
+ */
+function fromObservableOperator(operator, options) {
+    return (source) => {
+        const observableSource = streamAsObservable(source);
+        const foreignSource = options?.sourceAdapter
+            ? options.sourceAdapter(observableSource)
+            : observableSource;
+        const output = operator(foreignSource);
+        return observableInputToStream(output, options?.errorContext ?? "operator:fromObservableOperator:output");
+    };
+}
 /**
  * Creates a TransformStream that injects an error at the start and passes through all original data.
  *