@okikio/observables 1.0.2 → 1.3.0

package/README.md

@@ -280,7 +280,7 @@ Observable.of(1, 2, 3); // From values
 Observable.from(fetch("/api/data")); // From promises/iterables
 ```
 
-### Operators (19+ included)
+### Operators (including combination, conditional, and recovery helpers)
 
 ```ts
 import { debounce, filter, map, pipe, switchMap } from "@okikio/observables";
@@ -295,6 +295,15 @@ pipe(
 );
 ```
 
+The built-in operator set covers the common array-like transforms plus the
+stream-specific coordination helpers you usually reach for next:
+
+- `map`, `filter`, `scan`, `take`, `drop`
+- `find`, `findIndex`, `first`, `elementAt`
+- `mergeMap`, `concatMap`, `switchMap`
+- `withLatestFrom`, `combineLatestWith`, `zipWith`, `raceWith`
+- `changed`, `unique`, `catchErrors`, `ignoreErrors`
+
 ### EventBus & EventDispatcher
 
 ```ts
@@ -448,6 +457,103 @@ function movingAverage(windowSize: number) {
 }
 ```
 
+### Native Stream and RxJS Interop
+
+The library stays on Web Streams internally, but you can still bring in
+platform transforms and foreign operator ecosystems when that is the cheapest
+way to solve a problem.
+
+If you already have a readable/writable pair such as `CompressionStream`, use
+`fromStreamPair()` to treat it like a normal operator:
+
+```ts
+import {
+  fromStreamPair,
+  Observable,
+  pipe,
+} from "@okikio/observables";
+
+const gzip = fromStreamPair<Uint8Array, Uint8Array>(
+  () => new CompressionStream("gzip"),
+);
+
+const compressed = pipe(
+  Observable.of(new TextEncoder().encode("hello world")),
+  gzip,
+);
+```
+
+If you want to reuse RxJS operator functions, `fromObservableOperator()` wraps
+that operator shape and keeps the rest of your pipeline in this library.
+
+That helper is intentionally a little wider than `Observable.from()`. The core
+`Observable.from()` conversion path stays aligned with spec-style inputs such as
+iterables, promises, async iterables, array-like values, and objects that
+implement `[Symbol.observable]()`. The interop helper also accepts direct
+subscribables returned by third-party operator ecosystems, so you can reuse an
+RxJS stage without first forcing its output through the stricter `from()`
+contract.
+
+Use the standard RxJS names when you are only talking to RxJS inside the
+adapter:
+
+```ts
+import { fromObservableOperator, Observable, pipe } from "@okikio/observables";
+import { from, map, pipe as rxPipe, take } from "rxjs";
+
+const rxStage = fromObservableOperator<number, number>(
+  rxPipe(
+    map((value) => value + 1),
+    take(2),
+  ),
+  { sourceAdapter: (source) => from(source) },
+);
+
+const result = pipe(Observable.of(1, 2, 3), rxStage);
+```
+
+Alias the RxJS imports when you want local operators and RxJS operators in the
+same file:
+
+```ts
+import {
+  fromObservableOperator,
+  map,
+  Observable,
+  pipe,
+} from "@okikio/observables";
+import {
+  from as rxFrom,
+  map as rxMap,
+  pipe as rxPipe,
+  take as rxTake,
+} from "rxjs";
+
+const result = pipe(
+  Observable.of(1, 2, 3, 4),
+  map((value) => value * 10),
+  fromObservableOperator<number, number>(
+    rxPipe(
+      rxMap((value) => value + 1),
+      rxTake(2),
+    ),
+    { sourceAdapter: (source) => rxFrom(source) },
+  ),
+);
+```
+
+`sourceAdapter` is the important piece for standard RxJS operators. RxJS
+operator functions expect an RxJS `Observable` on the input side, so the
+adapter converts this library's Observable into that source shape before the
+foreign operator runs. On the output side, `fromObservableOperator()` can read
+either a normal `Observable.from()` input or a direct subscribable returned by
+RxJS.
+
+Some operators have the same name in both ecosystems, such as `switchMap`,
+`mergeMap`, `concatMap`, `findIndex`, `first`, and `elementAt`. Others map by
+intent rather than by exact name. For example, this library's `changed()` is
+closest to RxJS `distinctUntilChanged()`.
+
 ## Performance
 
 We built this on Web Streams for good reason, native backpressure and memory
@@ -459,6 +565,12 @@ efficiency come for free. Here's what you get:
 - **Tree Shaking**: Import only what you use (most apps need <4KB)
 - **TypeScript Native**: Zero runtime overhead for type safety
 
+Interop helpers are intentionally thin, but they still add one adaptation
+boundary. If raw throughput is the main goal, prefer built-in operators first,
+then reach for `fromStreamPair()` or `fromObservableOperator()` when reusing an
+existing platform transform or foreign operator saves more code than it costs
+in adapter overhead.
+
 Performance varies by use case, but here's how different error modes stack up:
 
 | Error Mode     | Performance | When We Use It            |
@@ -500,9 +612,8 @@ like a stream of search results, mouse movements, or WebSocket messages.
 
 ### Why not just use RxJS?
 
-RxJS is powerful but can be overwhelming. We've all been there, 100+ operators,
-steep learning curve, 35KB bundle size. This library gives you the essential
-Observable patterns you actually use day-to-day, following the TC39 proposal so
+RxJS is powerful but can be overwhelming. 100+ operators, a steep learning curve, 35KB bundle size, it can be very overwhelming. `@okikio/observables` gives you the essential
+Observable patterns you actually need day-to-day, following the TC39 proposal so
 you're future-ready.
 
 ### EventBus vs Observable, when do I use which?
@@ -525,9 +636,9 @@ Pick the mode that fits your situation:
 
 ### Is this actually production ready?
 
-We use it in production. It follows the TC39 proposal, has comprehensive tests,
+It follows the TC39 proposal, has comprehensive tests,
 and handles resource management properly. The Web Streams foundation is
-battle-tested across browsers and runtimes.
+battle-tested across browsers and runtimes. I'd say it's good enough for prime-time, but as with any library, test it in your specific use case first.
 
 ## Contributing
 

package/esm/helpers/_types.d.ts

@@ -1,5 +1,6 @@
 import type { ObservableError } from "../error.js";
 import type { Observable } from "../observable.js";
+import type { SpecObservable } from "../_spec.js";
 /**
  * Type representing a stream operator function
  * Transforms a ReadableStream of type In to a ReadableStream of type Out
@@ -67,6 +68,67 @@ export interface BaseTransformOptions {
      */
     name?: string;
 }
+/**
+ * Structural readable/writable pair used by platform transforms such as
+ * `CompressionStream`.
+ */
+export interface StreamPair<TIn, TOut> {
+    /** Readable side exposed by the transform-like object. */
+    readable: ReadableStream<TOut>;
+    /** Writable side exposed by the transform-like object. */
+    writable: WritableStream<TIn>;
+}
+/**
+ * Minimal subscribable shape used by foreign Observable implementations.
+ */
+export interface SubscribableLike<T> {
+    /** Subscribe to values from the foreign Observable-like object. */
+    subscribe(observer: {
+        next?(value: T): void;
+        error?(error: unknown): void;
+        complete?(): void;
+    }): {
+        unsubscribe?(): void;
+    } | void;
+}
+/**
+ * Observable-like values that can be converted through `Observable.from()`.
+ */
+export type ObservableInputLike<T> = SpecObservable<T> | AsyncIterable<T> | Iterable<T> | PromiseLike<T>;
+/**
+ * Wider Observable-like values accepted by interop helpers that adapt foreign
+ * operator ecosystems.
+ *
+ * This is intentionally wider than `ObservableInputLike<T>`. `Observable.from()`
+ * stays aligned with the library's spec-facing conversion contract, while
+ * interop helpers may also need to consume direct subscribables returned by
+ * third-party libraries such as RxJS.
+ */
+export type ObservableInteropInputLike<T> = ObservableInputLike<T> | SubscribableLike<T>;
+/**
+ * Foreign operator shape used by libraries that transform one Observable-like
+ * source into another Observable-like result.
+ */
+export type ObservableOperatorInterop<TIn, TOut, TSource = Observable<TIn>> = (source: TSource) => ObservableInteropInputLike<TOut>;
+/**
+ * Configuration for adapting foreign Observable-style operators.
+ *
+ * Some libraries, such as RxJS, require their own Observable class on the
+ * input side even when the returned operator shape is still `(source) =>
+ * output`. `sourceAdapter` lets callers convert this library's Observable into
+ * that foreign source type before the operator runs.
+ */
+export interface ObservableOperatorInteropOptions<TIn, TSource = Observable<TIn>> {
+    /**
+     * Converts this library's Observable into the source type expected by the
+     * foreign operator.
+     */
+    sourceAdapter?: (source: Observable<TIn>) => TSource;
+    /**
+     * Context label used when the foreign output reports an error.
+     */
+    errorContext?: string;
+}
 /**
  * Options for using an existing TransformStream
  */

package/esm/helpers/_types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_types.d.ts","sourceRoot":"","sources":["../../src/helpers/_types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"_types.d.ts","sourceRoot":"","sources":["../../src/helpers/_types.ts"],"names":[],"mappings":"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"}

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

@@ -18,6 +18,51 @@ import "../../_dnt.polyfills.js";
 import type { SpecObservable } from "../../_spec.js";
 import type { ExcludeError, Operator } from "../_types.js";
 import { ObservableError } from "../../error.js";
+/**
+ * Creates a follow-up Observable for each source value.
+ *
+ * These higher-order operators all work in two stages:
+ * they read an outer source value, then use this callback to start an inner
+ * Observable whose values are forwarded according to the operator's policy.
+ *
+ * ```text
+ * outer value ---> createFollowUp(value, index) ---> inner Observable
+ * ```
+ *
+ * The operators in this module differ in what they do after that point:
+ *
+ * ```text
+ * mergeMap   -> keep many inners running at once
+ * concatMap  -> queue inners and run one at a time
+ * switchMap  -> cancel the old inner and keep only the latest one
+ * ```
+ *
+ * @typeParam T - Value type from the outer source
+ * @typeParam R - Value type emitted by each follow-up Observable
+ */
+export type FollowUpProject<T, R> = (value: ExcludeError<T>, index: number) => SpecObservable<R>;
+/**
+ * Tuple of values emitted by a source and one or more companion Observables.
+ *
+ * Operators such as `withLatestFrom`, `combineLatestWith`, and `zipWith`
+ * return tuples so callers can decide how to shape the combined values in a
+ * later `map()` step without losing type information.
+ *
+ * @typeParam T - Value type from the primary source
+ * @typeParam TOthers - Value types from the companion Observables
+ */
+export type CombinationTuple<T, TOthers extends readonly unknown[]> = [
+    T,
+    ...TOthers
+];
+/**
+ * Tuple-shaped list of companion Observables used by the combination helpers.
+ *
+ * @typeParam TValues - Value types emitted by each companion Observable
+ */
+export type CombinationSources<TValues extends readonly unknown[]> = {
+    [K in keyof TValues]: SpecObservable<TValues[K]>;
+};
 /**
  * Transforms each item into a new stream and merges their outputs, running
  * them in parallel.
@@ -63,7 +108,7 @@ import { ObservableError } from "../../error.js";
  * to concurrently. Default is Infinity.
  * @returns An operator function that maps and flattens values
  */
-export declare function mergeMap<T, R>(project: (value: ExcludeError<T>, index: number) => SpecObservable<R>, concurrent?: number): Operator<T | ObservableError, R | ObservableError>;
+export declare function mergeMap<T, R>(project: FollowUpProject<T, R>, concurrent?: number): Operator<T | ObservableError, R | ObservableError>;
 /**
  * Transforms each item into a new stream and runs them one after another, in
  * strict order.
@@ -113,7 +158,7 @@ export declare function mergeMap<T, R>(project: (value: ExcludeError<T>, index:
  * @param project - Function that maps a source value to an Observable
  * @returns An operator function that maps and concatenates values
  */
-export declare function concatMap<T, R>(project: (value: ExcludeError<T>, index: number) => SpecObservable<R>): Operator<T | ObservableError, R | ObservableError>;
+export declare function concatMap<T, R>(project: FollowUpProject<T, R>): Operator<T | ObservableError, R | ObservableError>;
 /**
  * Transforms items into new streams, but cancels the previous stream when a new
  * item arrives.
@@ -158,5 +203,69 @@ export declare function concatMap<T, R>(project: (value: ExcludeError<T>, index:
  * @param project - Function that maps a source value to an Observable
  * @returns An operator function that maps and switches between values
  */
-export declare function switchMap<T, R>(project: (value: ExcludeError<T>, index: number) => SpecObservable<R>): Operator<T | ObservableError, R | ObservableError>;
+export declare function switchMap<T, R>(project: FollowUpProject<T, R>): Operator<T | ObservableError, R | ObservableError>;
+/**
+ * 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 declare function withLatestFrom<T, TOthers extends readonly unknown[]>(...others: CombinationSources<TOthers>): Operator<T | ObservableError, CombinationTuple<ExcludeError<T>, TOthers> | ObservableError>;
+/**
+ * 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 declare function combineLatestWith<T, TOthers extends readonly unknown[]>(...others: CombinationSources<TOthers>): Operator<T | ObservableError, CombinationTuple<ExcludeError<T>, TOthers> | ObservableError>;
+/**
+ * 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 declare function zipWith<T, TOthers extends readonly unknown[]>(...others: CombinationSources<TOthers>): Operator<T | ObservableError, CombinationTuple<ExcludeError<T>, TOthers> | ObservableError>;
+/**
+ * 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 declare function raceWith<T, TOthers extends readonly unknown[]>(...others: CombinationSources<TOthers>): Operator<T | ObservableError, ExcludeError<T> | TOthers[number] | ObservableError>;
 //# sourceMappingURL=combination.d.ts.map

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

@@ -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"}
+{"version":3,"file":"combination.d.ts","sourceRoot":"","sources":["../../../src/helpers/operations/combination.ts"],"names":[],"mappings":"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"}