reactor-core-ts 2.1.2 → 2.1.4

package/README.md

@@ -336,10 +336,20 @@ Flux.just('a', 'b', 'c')
 | Method | Description |
 |---|---|
 | `.cache()` | Subscribe to the source once; replay all items to subsequent subscribers. |
+| `.share()` | Hot multicast with refCounting — connects on first subscriber, disconnects when the last one leaves. Items are delivered best-effort (no buffering). Re-subscribes to upstream when a new subscriber arrives after all others have left. |
 | `.switchIfEmpty(alternative)` | Switch to `alternative` if source completes without emitting. |
 | `.delaySubscription(ms)` | Delay the actual subscription to the source by `ms` milliseconds. |
 | `.pipe(producer, onRequest, onUnsubscribe)` | Low-level escape hatch for building custom downstream operators. |
 
+```typescript
+// share() — multiple subscribers observe the same live upstream
+const hot = Flux.interval(500).share();
+
+hot.subscribe(v => console.log('A:', v));
+setTimeout(() => hot.subscribe(v => console.log('B:', v)), 1200);
+// A: 0, A: 1, A: 2, B: 2, A: 3, B: 3, …
+```
+
 ### FluxSink
 
 `Flux.create(emitter => …)` hands the `emitter` callback a `FluxSink<T>` with:
@@ -413,6 +423,7 @@ sub.unsubscribe(); // cancel at any time
 | `Mono.empty()` | Complete immediately without emitting. |
 | `Mono.error(err)` | Signal `onError` immediately. |
 | `Mono.firstWithValue(...sources)` | Race: emit the first value from any of the given `Mono` sources. |
+| `Mono.when(...sources)` | `Mono<void>` that completes when **all** given publishers complete. Values are ignored; the first error is propagated and all other sources are cancelled. |
 
 ```typescript
 import { Mono } from 'reactor-core-ts';
@@ -429,6 +440,12 @@ Mono.justOrEmpty(null).subscribe(
     () => console.log('empty'),
 );
 // empty
+
+// Mono.when — wait for multiple async operations to finish
+Mono.when(
+    Mono.fromPromise(saveUser(user)),
+    Mono.fromPromise(sendEmail(user)),
+).subscribe(undefined, undefined, () => console.log('all done'));
 ```
 
 ### Mono Transformation
@@ -439,6 +456,8 @@ Mono.justOrEmpty(null).subscribe(
 | `.mapNotNull(fn)` | Transform `T → R | null | undefined`; if result is null/undefined, complete empty. |
 | `.flatMap(fn)` | Map the value to a `Mono<R>`, then subscribe to that inner Mono. |
 | `.flatMapMany(fn)` | Map the value to a `Flux<R>` or `Mono<R>`, returning a `Flux<R>`. |
+| `.then()` | `Mono<void>` — ignore the emitted value; complete when source completes. |
+| `.then(other)` | Ignore the emitted value; subscribe to `other` after source completes and return `other`'s result. |
 | `.thenReturn(value)` | Ignore the emitted value; emit `value` after source completes. |
 | `.delayElement(ms)` | Delay the emitted value by `ms` milliseconds. |
 | `.delayUntil(triggerFn)` | Hold the emitted value until the trigger publisher fires, then forward it. |
@@ -453,6 +472,18 @@ Mono.just(5)
     .flatMapMany(n => Flux.range(0, n))
     .subscribe(v => console.log(v));
 // 0  1  2  3  4
+
+// then() — sequence operations, ignore intermediate values
+Mono.just('step 1')
+    .then(Mono.just('step 2'))
+    .then(Mono.just('step 3'))
+    .subscribe(v => console.log(v));
+// 'step 3'
+
+// then() with no argument — completion signal only
+Mono.fromPromise(deleteRecord(id))
+    .then()
+    .subscribe(undefined, undefined, () => console.log('deleted'));
 ```
 
 ### Mono Filtering
@@ -547,10 +578,16 @@ const value: number | null = await Mono.just(42).toPromise();
 
 ## Sinks
 
-Sinks are imperative bridges that let external code push values into a reactive stream. The `Sinks` factory returns a `SinkPublisher<T>` — an object that implements both `Sink<T>` (push API) and `Publisher<T>` (subscribe API).
+Sinks are imperative bridges that let external code push values into a reactive stream. The `Sinks` factory returns a `SinkPublisher<T>` — an object that implements both `Sink<T>` (push API) and `Publisher<T>` (subscribe API), plus a convenience `asFlux()` method that wraps the sink as a full-featured `Flux<T>` with all operators available.
 
 ```typescript
 import { Sinks, Flux } from 'reactor-core-ts';
+
+// asFlux() gives access to all Flux operators
+const sink = Sinks.many().replay().all<number>();
+sink.next(1);
+sink.next(2);
+sink.asFlux().map(n => n * 10).subscribe(v => console.log(v)); // 10  20
 ```
 
 ### `Sinks.empty<T>()`

package/dist/index.d.mts

@@ -569,6 +569,56 @@ interface FluxSink<T> extends Sink<T> {
     onDispose(fn: () => void): FluxSink<T>;
 }
 
+/**
+ * Minimal interface compatible with the browser `WebSocket` API and the `ws` npm package.
+ *
+ * Any object that exposes `onmessage`, `onerror`, `onclose`, and `close()` satisfies
+ * this interface and can be passed to {@link Flux.fromWebSocket}.
+ *
+ * @typeParam T - The type of `event.data` received in each message.
+ */
+interface WebSocketLike<T = unknown> {
+    /** Assigned when a message arrives; `event.data` carries the payload. */
+    onmessage: ((event: {
+        data: T;
+    }) => void) | null;
+    /** Assigned when a transport-level error occurs. */
+    onerror: ((event: unknown) => void) | null;
+    /** Assigned when the connection is closed. */
+    onclose: ((event: {
+        code: number;
+        reason: string | Buffer;
+    }) => void) | null;
+    /** Close the connection, optionally with a status code and reason. */
+    close(code?: number, reason?: string | Buffer): void;
+    /** Current connection state (0 = CONNECTING, 1 = OPEN, 2 = CLOSING, 3 = CLOSED). */
+    readonly readyState: number;
+}
+/**
+ * Minimal DOM-style event target interface (`addEventListener` / `removeEventListener`).
+ * Satisfied by browser `EventTarget`, `HTMLElement`, `window`, `document`, etc.
+ *
+ * @typeParam T - The event type emitted by the target.
+ */
+interface DOMEventTargetLike<T = Event> {
+    addEventListener(type: string, listener: (event: T) => void): void;
+    removeEventListener(type: string, listener: (event: T) => void): void;
+}
+/**
+ * Minimal Node.js-style event emitter interface (`on` / `off`).
+ * Satisfied by Node.js `EventEmitter` and any object with the same shape.
+ *
+ * @typeParam T - The event data type emitted by the emitter.
+ */
+interface NodeEventEmitterLike<T = unknown> {
+    on(event: string | symbol, listener: (data: T) => void): void;
+    off(event: string | symbol, listener: (data: T) => void): void;
+}
+/**
+ * Union of {@link DOMEventTargetLike} and {@link NodeEventEmitterLike}.
+ * Accepted by {@link Flux.fromEvent}.
+ */
+type EventSourceLike<T = unknown> = DOMEventTargetLike<T> | NodeEventEmitterLike<T>;
 /**
  * A cold publisher of 0 to N items with full backpressure support.
  *
@@ -743,6 +793,68 @@ declare class Flux<T> extends AbstractPipePublisher<T, Flux<T>> implements PipeP
      * ```
      */
     static using<T, R>(resourceSupplier: () => R, sourceFactory: (resource: R) => Publisher<T>, cleanup: (resource: R) => void): Flux<T>;
+    /**
+     * Creates a `Flux<T>` that emits each message received on a `WebSocket`.
+     *
+     * - Each message's `data` is emitted as the next item.
+     * - The stream **completes** when the socket is closed (any close code).
+     * - A transport-level error event terminates the stream with an `Error`.
+     * - **Unsubscribing** closes the socket gracefully (sends a normal-closure frame).
+     *
+     * Compatible with the browser `WebSocket` API and the `ws` npm package. Any object
+     * satisfying the {@link WebSocketLike} interface can be passed.
+     *
+     * @param ws - An open (or opening) WebSocket instance.
+     * @returns A `Flux<T>` backed by the WebSocket message stream.
+     *
+     * @example
+     * ```typescript
+     * // Browser
+     * Flux.fromWebSocket<string>(new WebSocket('wss://example.com/chat'))
+     *   .map(msg => JSON.parse(msg))
+     *   .subscribe(msg => console.log(msg));
+     *
+     * // Node.js (ws package)
+     * import WebSocket from 'ws';
+     * Flux.fromWebSocket<Buffer>(new WebSocket('ws://localhost:8080'))
+     *   .map(buf => buf.toString())
+     *   .subscribe(text => console.log(text));
+     * ```
+     */
+    static fromWebSocket<T = unknown>(ws: WebSocketLike<T>): Flux<T>;
+    /**
+     * Creates an infinite `Flux<T>` that emits every event of type `eventName` fired on
+     * `target`. The stream never completes on its own — call `unsubscribe()` or chain a
+     * limiting operator (e.g. `.take(n)`, `.takeUntilOther(stop$)`) to terminate it.
+     *
+     * Works with:
+     * - **DOM targets** (`EventTarget`: `HTMLElement`, `window`, `document`, …) — uses
+     *   `addEventListener` / `removeEventListener`.
+     * - **Node.js emitters** (any object with `on` / `off`) — uses those methods directly.
+     *
+     * Events fired while downstream has no demand are **buffered** (via {@link Flux.create})
+     * and delivered once demand is available.
+     *
+     * @param target - A DOM `EventTarget` or Node.js-style event emitter.
+     * @param eventName - The event name / type to listen for.
+     * @returns An infinite cold `Flux<T>` of matching events.
+     *
+     * @example
+     * ```typescript
+     * // Browser — click events on a button
+     * Flux.fromEvent<MouseEvent>(document.getElementById('btn')!, 'click')
+     *   .map(e => ({ x: e.clientX, y: e.clientY }))
+     *   .subscribe(pos => console.log(pos));
+     *
+     * // Node.js EventEmitter
+     * import { EventEmitter } from 'events';
+     * const emitter = new EventEmitter();
+     * Flux.fromEvent<string>(emitter, 'data')
+     *   .take(5)
+     *   .subscribe(v => console.log(v));
+     * ```
+     */
+    static fromEvent<T = Event>(target: EventSourceLike<T>, eventName: string): Flux<T>;
     /**
      * Merges N publishers by subscribing to all of them concurrently and interleaving
      * their items as they arrive.
@@ -2096,6 +2208,27 @@ declare class Mono<T> extends AbstractPipePublisher<T, Mono<T>> implements PipeP
      * ```
      */
     thenReturn<R>(value: R): Mono<R>;
+    /**
+     * Ignores the value emitted by this `Mono` and, upon completion, subscribes to `other`
+     * and forwards its result downstream.
+     *
+     * If `other` is omitted, returns a `Mono<void>` that completes when this `Mono` completes.
+     * Errors from this `Mono` are propagated without subscribing to `other`.
+     *
+     * @param other - Optional `Mono<V>` to subscribe to after this `Mono` completes.
+     * @returns `Mono<void>` when called with no argument; `Mono<V>` when `other` is provided.
+     *
+     * @example
+     * ```typescript
+     * // Sequencing: run A, then run B and return B's value
+     * Mono.just('ignored').then(Mono.just(42)).subscribe(v => console.log(v)); // 42
+     *
+     * // Completion signal only
+     * Mono.just('ignored').then().subscribe(undefined, undefined, () => console.log('done'));
+     * ```
+     */
+    then(): Mono<void>;
+    then<V>(other: Mono<V>): Mono<V>;
     /**
      * Delays delivery of the emitted value by `ms` milliseconds.
      *
@@ -2399,4 +2532,4 @@ declare const Sinks: {
     };
 };
 
-export { type CancellableScheduler, Flux, type FluxSink, type GroupedFlux, Mono, type Publisher, type Scheduler, Schedulers, Signal, type Sink, type SinkPublisher, Sinks, type Subscriber, type Subscription };
+export { type CancellableScheduler, type DOMEventTargetLike, type EventSourceLike, Flux, type FluxSink, type GroupedFlux, Mono, type NodeEventEmitterLike, type Publisher, type Scheduler, Schedulers, Signal, type Sink, type SinkPublisher, Sinks, type Subscriber, type Subscription, type WebSocketLike };

package/dist/index.d.ts

@@ -569,6 +569,56 @@ interface FluxSink<T> extends Sink<T> {
     onDispose(fn: () => void): FluxSink<T>;
 }
 
+/**
+ * Minimal interface compatible with the browser `WebSocket` API and the `ws` npm package.
+ *
+ * Any object that exposes `onmessage`, `onerror`, `onclose`, and `close()` satisfies
+ * this interface and can be passed to {@link Flux.fromWebSocket}.
+ *
+ * @typeParam T - The type of `event.data` received in each message.
+ */
+interface WebSocketLike<T = unknown> {
+    /** Assigned when a message arrives; `event.data` carries the payload. */
+    onmessage: ((event: {
+        data: T;
+    }) => void) | null;
+    /** Assigned when a transport-level error occurs. */
+    onerror: ((event: unknown) => void) | null;
+    /** Assigned when the connection is closed. */
+    onclose: ((event: {
+        code: number;
+        reason: string | Buffer;
+    }) => void) | null;
+    /** Close the connection, optionally with a status code and reason. */
+    close(code?: number, reason?: string | Buffer): void;
+    /** Current connection state (0 = CONNECTING, 1 = OPEN, 2 = CLOSING, 3 = CLOSED). */
+    readonly readyState: number;
+}
+/**
+ * Minimal DOM-style event target interface (`addEventListener` / `removeEventListener`).
+ * Satisfied by browser `EventTarget`, `HTMLElement`, `window`, `document`, etc.
+ *
+ * @typeParam T - The event type emitted by the target.
+ */
+interface DOMEventTargetLike<T = Event> {
+    addEventListener(type: string, listener: (event: T) => void): void;
+    removeEventListener(type: string, listener: (event: T) => void): void;
+}
+/**
+ * Minimal Node.js-style event emitter interface (`on` / `off`).
+ * Satisfied by Node.js `EventEmitter` and any object with the same shape.
+ *
+ * @typeParam T - The event data type emitted by the emitter.
+ */
+interface NodeEventEmitterLike<T = unknown> {
+    on(event: string | symbol, listener: (data: T) => void): void;
+    off(event: string | symbol, listener: (data: T) => void): void;
+}
+/**
+ * Union of {@link DOMEventTargetLike} and {@link NodeEventEmitterLike}.
+ * Accepted by {@link Flux.fromEvent}.
+ */
+type EventSourceLike<T = unknown> = DOMEventTargetLike<T> | NodeEventEmitterLike<T>;
 /**
  * A cold publisher of 0 to N items with full backpressure support.
  *
@@ -743,6 +793,68 @@ declare class Flux<T> extends AbstractPipePublisher<T, Flux<T>> implements PipeP
      * ```
      */
     static using<T, R>(resourceSupplier: () => R, sourceFactory: (resource: R) => Publisher<T>, cleanup: (resource: R) => void): Flux<T>;
+    /**
+     * Creates a `Flux<T>` that emits each message received on a `WebSocket`.
+     *
+     * - Each message's `data` is emitted as the next item.
+     * - The stream **completes** when the socket is closed (any close code).
+     * - A transport-level error event terminates the stream with an `Error`.
+     * - **Unsubscribing** closes the socket gracefully (sends a normal-closure frame).
+     *
+     * Compatible with the browser `WebSocket` API and the `ws` npm package. Any object
+     * satisfying the {@link WebSocketLike} interface can be passed.
+     *
+     * @param ws - An open (or opening) WebSocket instance.
+     * @returns A `Flux<T>` backed by the WebSocket message stream.
+     *
+     * @example
+     * ```typescript
+     * // Browser
+     * Flux.fromWebSocket<string>(new WebSocket('wss://example.com/chat'))
+     *   .map(msg => JSON.parse(msg))
+     *   .subscribe(msg => console.log(msg));
+     *
+     * // Node.js (ws package)
+     * import WebSocket from 'ws';
+     * Flux.fromWebSocket<Buffer>(new WebSocket('ws://localhost:8080'))
+     *   .map(buf => buf.toString())
+     *   .subscribe(text => console.log(text));
+     * ```
+     */
+    static fromWebSocket<T = unknown>(ws: WebSocketLike<T>): Flux<T>;
+    /**
+     * Creates an infinite `Flux<T>` that emits every event of type `eventName` fired on
+     * `target`. The stream never completes on its own — call `unsubscribe()` or chain a
+     * limiting operator (e.g. `.take(n)`, `.takeUntilOther(stop$)`) to terminate it.
+     *
+     * Works with:
+     * - **DOM targets** (`EventTarget`: `HTMLElement`, `window`, `document`, …) — uses
+     *   `addEventListener` / `removeEventListener`.
+     * - **Node.js emitters** (any object with `on` / `off`) — uses those methods directly.
+     *
+     * Events fired while downstream has no demand are **buffered** (via {@link Flux.create})
+     * and delivered once demand is available.
+     *
+     * @param target - A DOM `EventTarget` or Node.js-style event emitter.
+     * @param eventName - The event name / type to listen for.
+     * @returns An infinite cold `Flux<T>` of matching events.
+     *
+     * @example
+     * ```typescript
+     * // Browser — click events on a button
+     * Flux.fromEvent<MouseEvent>(document.getElementById('btn')!, 'click')
+     *   .map(e => ({ x: e.clientX, y: e.clientY }))
+     *   .subscribe(pos => console.log(pos));
+     *
+     * // Node.js EventEmitter
+     * import { EventEmitter } from 'events';
+     * const emitter = new EventEmitter();
+     * Flux.fromEvent<string>(emitter, 'data')
+     *   .take(5)
+     *   .subscribe(v => console.log(v));
+     * ```
+     */
+    static fromEvent<T = Event>(target: EventSourceLike<T>, eventName: string): Flux<T>;
     /**
      * Merges N publishers by subscribing to all of them concurrently and interleaving
      * their items as they arrive.
@@ -2096,6 +2208,27 @@ declare class Mono<T> extends AbstractPipePublisher<T, Mono<T>> implements PipeP
      * ```
      */
     thenReturn<R>(value: R): Mono<R>;
+    /**
+     * Ignores the value emitted by this `Mono` and, upon completion, subscribes to `other`
+     * and forwards its result downstream.
+     *
+     * If `other` is omitted, returns a `Mono<void>` that completes when this `Mono` completes.
+     * Errors from this `Mono` are propagated without subscribing to `other`.
+     *
+     * @param other - Optional `Mono<V>` to subscribe to after this `Mono` completes.
+     * @returns `Mono<void>` when called with no argument; `Mono<V>` when `other` is provided.
+     *
+     * @example
+     * ```typescript
+     * // Sequencing: run A, then run B and return B's value
+     * Mono.just('ignored').then(Mono.just(42)).subscribe(v => console.log(v)); // 42
+     *
+     * // Completion signal only
+     * Mono.just('ignored').then().subscribe(undefined, undefined, () => console.log('done'));
+     * ```
+     */
+    then(): Mono<void>;
+    then<V>(other: Mono<V>): Mono<V>;
     /**
      * Delays delivery of the emitted value by `ms` milliseconds.
      *
@@ -2399,4 +2532,4 @@ declare const Sinks: {
     };
 };
 
-export { type CancellableScheduler, Flux, type FluxSink, type GroupedFlux, Mono, type Publisher, type Scheduler, Schedulers, Signal, type Sink, type SinkPublisher, Sinks, type Subscriber, type Subscription };
+export { type CancellableScheduler, type DOMEventTargetLike, type EventSourceLike, Flux, type FluxSink, type GroupedFlux, Mono, type NodeEventEmitterLike, type Publisher, type Scheduler, Schedulers, Signal, type Sink, type SinkPublisher, Sinks, type Subscriber, type Subscription, type WebSocketLike };