reactor-core-ts 2.0.0 → 2.1.1

package/dist/index.d.mts

@@ -227,6 +227,45 @@ interface PipePublisher<T> extends Publisher<T> {
     subscribeOn(scheduler: Scheduler): PipePublisher<T>;
 }
 
+/**
+ * Represents a reactive signal — one of the three events that can be emitted
+ * by a {@link Publisher}: a value (`next`), a terminal error (`error`), or
+ * a normal completion (`complete`).
+ *
+ * `Signal` is the type used by {@link Flux#materialize} /
+ * {@link Flux#dematerialize} to pass reactive events as plain data values.
+ *
+ * @typeParam T - The type of the value carried by a `next` signal.
+ */
+type Signal<T> = {
+    readonly kind: 'next';
+    readonly value: T;
+} | {
+    readonly kind: 'error';
+    readonly error: Error;
+} | {
+    readonly kind: 'complete';
+};
+/**
+ * Namespace of factory helpers for creating {@link Signal} instances.
+ */
+declare const Signal: {
+    /**
+     * Creates a `next` signal carrying `value`.
+     * @param value - The item to wrap.
+     */
+    next<T>(value: T): Signal<T>;
+    /**
+     * Creates an `error` signal carrying `error`.
+     * @param error - The error to wrap.
+     */
+    error<T>(error: Error): Signal<T>;
+    /**
+     * Creates a `complete` signal.
+     */
+    complete<T>(): Signal<T>;
+};
+
 /**
  * Base class for Flux and Mono providing the common operator implementations
  * that are identical across both types. Operators that preserve T use the
@@ -352,6 +391,114 @@ declare abstract class AbstractPipePublisher<T, Self> implements Publisher<T> {
      * @returns A publisher that delivers signals on the given scheduler.
      */
     publishOn(scheduler: Scheduler): Self;
+    /**
+     * Falls back to a publisher produced by `fn` when the source signals an error.
+     *
+     * Unlike {@link onErrorReturn} (which takes a static replacement), this operator
+     * calls `fn` with the actual error, allowing dynamic recovery based on the error type.
+     *
+     * @param fn - Called with the error; returns the replacement publisher.
+     * @returns A publisher that recovers from errors dynamically.
+     *
+     * @example
+     * ```typescript
+     * Flux.error(new Error('not found'))
+     *   .onErrorResume(e => e.message === 'not found' ? Flux.just('default') : Flux.error(e))
+     *   .subscribe(v => console.log(v)); // 'default'
+     * ```
+     */
+    onErrorResume(fn: (error: Error) => Publisher<T>): Self;
+    /**
+     * Transforms the error signal using `fn` before forwarding it downstream.
+     *
+     * Useful for converting low-level errors into domain-specific error types.
+     *
+     * @param fn - Receives the original error and returns a replacement error.
+     * @returns A publisher that transforms errors before propagating them.
+     *
+     * @example
+     * ```typescript
+     * Flux.error(new Error('HTTP 404'))
+     *   .onErrorMap(e => new Error(`NotFound: ${e.message}`))
+     *   .subscribe(null, e => console.error(e.message)); // NotFound: HTTP 404
+     * ```
+     */
+    onErrorMap(fn: (error: Error) => Error): Self;
+    /**
+     * Emits a `TimeoutError` (or switches to `fallback`) if no item is received
+     * within `ms` milliseconds of the previous item (or of subscription).
+     *
+     * The timer resets on each received item, so it measures **inter-item** idle time.
+     *
+     * @param ms - Timeout duration in milliseconds.
+     * @param fallback - Optional publisher to switch to on timeout instead of erroring.
+     * @returns A publisher that errors or falls back when no item arrives in time.
+     *
+     * @example
+     * ```typescript
+     * Flux.never<number>()
+     *   .timeout(100)
+     *   .subscribe(null, e => console.error(e.message)); // TimeoutError after 100ms
+     * ```
+     */
+    timeout(ms: number, fallback?: Publisher<T>): Self;
+    /**
+     * Delays the subscription to the upstream source by `ms` milliseconds.
+     *
+     * `onSubscribe` is delivered immediately with a proxy `Subscription`.
+     * Any `request(n)` calls before the delay elapses are accumulated and
+     * forwarded once the actual subscription starts.
+     *
+     * @param ms - Delay in milliseconds before subscribing to the source.
+     * @returns A publisher whose upstream subscription is deferred.
+     */
+    delaySubscription(ms: number): Self;
+    /**
+     * Logs each reactive signal to the console for debugging.
+     *
+     * Prints `onSubscribe`, `request(n)`, `onNext(value)`, `onError`, `onComplete`,
+     * and `cancel` with an optional label prefix.
+     *
+     * @param label - Optional label prepended to each log line (default: `'reactor'`).
+     * @returns A publisher with logging side effects attached.
+     *
+     * @example
+     * ```typescript
+     * Flux.just(1, 2).log('source').subscribe(v => console.log(v));
+     * // [source] onSubscribe
+     * // [source] request(9007199254740991)
+     * // [source] onNext(1)
+     * // ...
+     * ```
+     */
+    log(label?: string): Self;
+    /**
+     * Executes a side-effect `fn` whenever the downstream subscriber issues a `request(n)`.
+     *
+     * Useful for debugging backpressure — see exactly how much demand is flowing upstream.
+     * Any exception thrown by `fn` is silently swallowed.
+     *
+     * @param fn - Called with the requested count `n`.
+     * @returns A publisher with the side effect attached to the request signal.
+     */
+    doOnRequest(fn: (n: number) => void): Self;
+    /**
+     * Executes a side-effect `fn` for every reactive signal (next, error, complete).
+     *
+     * The {@link Signal} discriminated union lets you inspect the kind and payload
+     * of each event in a single callback.
+     *
+     * @param fn - Called for every signal with a {@link Signal} wrapper.
+     * @returns A publisher with the side effect attached to all signals.
+     *
+     * @example
+     * ```typescript
+     * Flux.just(1, 2)
+     *   .doOnEach(s => { if (s.kind === 'next') console.log('item:', s.value); })
+     *   .subscribe();
+     * ```
+     */
+    doOnEach(fn: (signal: Signal<T>) => void): Self;
     /**
      * Shifts the *subscription* (and source execution) to the given `scheduler`.
      *
@@ -368,6 +515,60 @@ declare abstract class AbstractPipePublisher<T, Self> implements Publisher<T> {
     subscribeOn(scheduler: Scheduler): Self;
 }
 
+/**
+ * Backpressure-aware push interface handed to the generator function of {@link Flux.create}.
+ *
+ * Extends {@link Sink} with demand tracking and lifecycle hooks so the producer
+ * can react to downstream request signals and cancellation. The generator may call
+ * `next`, `error`, and `complete` freely from any context (event listener, timer,
+ * callback). Items pushed when downstream demand is zero are buffered and delivered
+ * as soon as demand becomes available.
+ *
+ * @typeParam T - The type of items to push.
+ */
+interface FluxSink<T> extends Sink<T> {
+    /**
+     * Push the next value. Buffered if downstream has no outstanding demand.
+     * No-op after `complete()` or `error()` have been called.
+     */
+    next(value: T): void;
+    /**
+     * Terminate the stream with an error.
+     * No-op if the sink has already terminated.
+     */
+    error(error: Error): void;
+    /**
+     * Complete the stream normally.
+     * No-op if the sink has already terminated.
+     */
+    complete(): void;
+    /**
+     * The current downstream demand (number of items the subscriber has requested
+     * but not yet received). Useful for push-pull hybrid sources.
+     */
+    readonly requested: number;
+    /**
+     * Register a callback that is called each time downstream requests more items.
+     * Multiple callbacks may be registered; they are all called in registration order.
+     * @param fn - Called with the additional demand count.
+     * @returns `this` for chaining.
+     */
+    onRequest(fn: (n: number) => void): FluxSink<T>;
+    /**
+     * Register a callback that is called when downstream cancels (unsubscribes).
+     * @param fn - Cancellation handler.
+     * @returns `this` for chaining.
+     */
+    onCancel(fn: () => void): FluxSink<T>;
+    /**
+     * Register a callback that is called when the sink is disposed —
+     * either by cancellation or terminal signal.
+     * @param fn - Disposal handler.
+     * @returns `this` for chaining.
+     */
+    onDispose(fn: () => void): FluxSink<T>;
+}
+
 /**
  * A cold publisher of 0 to N items with full backpressure support.
  *
@@ -494,6 +695,158 @@ declare class Flux<T> extends AbstractPipePublisher<T, Flux<T>> implements PipeP
      * @returns A `Flux<T>` that stays subscribed forever.
      */
     static never<T = never>(): Flux<T>;
+    /**
+     * Creates a `Flux` from a generator function that **pushes** values imperatively
+     * via a {@link FluxSink}.
+     *
+     * Unlike {@link Flux.generate} (which is request-pull), `create` is designed for
+     * **push-based** sources (EventEmitter, WebSocket, DOM events, Node.js streams).
+     * Items pushed when downstream demand is zero are **buffered** and delivered as demand
+     * becomes available.
+     *
+     * Register `onRequest`, `onCancel`, and `onDispose` callbacks on the sink to respond
+     * to downstream lifecycle events.
+     *
+     * @param emitter - Called once per subscription; receives a `FluxSink<T>` for pushing values.
+     * @returns A cold `Flux<T>`.
+     *
+     * @example
+     * ```typescript
+     * const emitter = new EventEmitter();
+     * const flux = Flux.create<string>(sink => {
+     *   emitter.on('data', v => sink.next(v));
+     *   emitter.on('end',  () => sink.complete());
+     *   sink.onCancel(() => emitter.removeAllListeners());
+     * });
+     * ```
+     */
+    static create<T>(emitter: (sink: FluxSink<T>) => void): Flux<T>;
+    /**
+     * Creates a `Flux` that acquires a resource, uses it to build a source publisher,
+     * and guarantees the resource is cleaned up when the stream terminates or is cancelled.
+     *
+     * The cleanup runs after `onComplete`, `onError`, or `unsubscribe()` — whichever
+     * happens first.
+     *
+     * @param resourceSupplier - Called once per subscription to acquire the resource.
+     * @param sourceFactory - Builds the source publisher from the resource.
+     * @param cleanup - Called with the resource after the stream terminates.
+     * @returns A `Flux<T>` with guaranteed resource cleanup.
+     *
+     * @example
+     * ```typescript
+     * Flux.using(
+     *   () => openFile('data.txt'),
+     *   file => Flux.fromIterable(file.readLines()),
+     *   file => file.close()
+     * ).subscribe(line => console.log(line));
+     * ```
+     */
+    static using<T, R>(resourceSupplier: () => R, sourceFactory: (resource: R) => Publisher<T>, cleanup: (resource: R) => void): Flux<T>;
+    /**
+     * Merges N publishers by subscribing to all of them concurrently and interleaving
+     * their items as they arrive.
+     *
+     * The stream completes when **all** sources complete.
+     * Any error from any source terminates the merged stream immediately.
+     *
+     * @param sources - Publishers to merge.
+     * @returns A `Flux<T>` that emits items from all sources concurrently.
+     *
+     * @example
+     * ```typescript
+     * Flux.merge(Flux.just(1, 2), Flux.just(3, 4)).subscribe(v => console.log(v));
+     * // 1 2 3 4 (order may vary for async sources)
+     * ```
+     */
+    static merge<T>(...sources: Publisher<T>[]): Flux<T>;
+    /**
+     * Subscribes to all `sources` concurrently and emits the **first value** produced
+     * by any of them. All other subscriptions are cancelled immediately after the winner emits.
+     *
+     * If all sources complete without emitting a value, the result completes empty.
+     * Errors from non-winning sources are ignored once a winner is found.
+     *
+     * @param sources - Publishers to race.
+     * @returns A `Flux<T>` that emits the first value from any source.
+     *
+     * @example
+     * ```typescript
+     * // Take whichever request responds first
+     * Flux.firstWithValue(fetchFromCDN(), fetchFromOrigin())
+     *   .subscribe(data => console.log(data));
+     * ```
+     */
+    static firstWithValue<T>(...sources: Publisher<T>[]): Flux<T>;
+    /**
+     * Emits an ever-incrementing counter (0, 1, 2, …) at a fixed `ms` rate.
+     *
+     * Items are **dropped** when downstream has no outstanding demand (rather than
+     * buffered), matching Reactor's `Flux.interval` drop-on-overflow behaviour.
+     * The stream never completes on its own — cancel the subscription to stop it.
+     *
+     * @param ms - Interval duration in milliseconds.
+     * @returns An infinite `Flux<number>`.
+     *
+     * @example
+     * ```typescript
+     * Flux.interval(1000).take(3).subscribe(n => console.log(n)); // 0  1  2
+     * ```
+     */
+    static interval(ms: number): Flux<number>;
+    /**
+     * Combines items from 2 sources positionally via `combiner`.
+     * Emits one combined value for each position; stops when the shorter source exhausts.
+     */
+    static zip<A, B, R>(sources: [Publisher<A>, Publisher<B>], combiner: (a: A, b: B) => R): Flux<R>;
+    /**
+     * Combines items from 3 sources positionally via `combiner`.
+     */
+    static zip<A, B, C, R>(sources: [Publisher<A>, Publisher<B>, Publisher<C>], combiner: (a: A, b: B, c: C) => R): Flux<R>;
+    /**
+     * Combines items from 4 sources positionally via `combiner`.
+     */
+    static zip<A, B, C, D, R>(sources: [Publisher<A>, Publisher<B>, Publisher<C>, Publisher<D>], combiner: (a: A, b: B, c: C, d: D) => R): Flux<R>;
+    /**
+     * General N-source positional zip.
+     *
+     * Subscribes to each source concurrently, using a prefetch of 1 per source.
+     * Once every source has provided one item for a given position, `combiner` is
+     * called with those items and the result is emitted downstream.  The stream
+     * completes when any source completes and has no buffered items left.
+     *
+     * @param sources - Publishers to zip.
+     * @param combiner - Combines one item from each source at the same position.
+     * @returns A `Flux<R>` of combined values.
+     *
+     * @example
+     * ```typescript
+     * Flux.zip([Flux.just(1, 2), Flux.just('a', 'b')], (n, s) => `${n}${s}`)
+     *   .subscribe(v => console.log(v)); // '1a'  '2b'
+     * ```
+     */
+    static zip<T, R>(sources: Publisher<T>[], combiner: (...args: T[]) => R): Flux<R>;
+    /**
+     * Combines the **latest** value from each source whenever any source emits.
+     *
+     * Does not emit until all sources have produced at least one value.
+     * Continues emitting with each new item from any source, using the latest values
+     * from all others.  Sources run at unbounded speed; downstream demand controls delivery.
+     *
+     * @param sources - Publishers to combine.
+     * @param combiner - Called with the latest value from each source.
+     * @returns A `Flux<R>` of combined values.
+     *
+     * @example
+     * ```typescript
+     * Flux.combineLatest([Flux.just(1, 2), Flux.just('a', 'b')], (n, s) => `${n}${s}`)
+     *   .subscribe(v => console.log(v)); // '1a'  '2a'  '2b'  (order depends on timing)
+     * ```
+     */
+    static combineLatest<A, B, R>(sources: [Publisher<A>, Publisher<B>], combiner: (a: A, b: B) => R): Flux<R>;
+    static combineLatest<A, B, C, R>(sources: [Publisher<A>, Publisher<B>, Publisher<C>], combiner: (a: A, b: B, c: C) => R): Flux<R>;
+    static combineLatest<A, B, C, D, R>(sources: [Publisher<A>, Publisher<B>, Publisher<C>, Publisher<D>], combiner: (a: A, b: B, c: C, d: D) => R): Flux<R>;
+    static combineLatest<T, R>(sources: Publisher<T>[], combiner: (...args: T[]) => R): Flux<R>;
     /**
      * Transforms each item using `fn`, producing a `Flux<R>`.
      *
@@ -992,13 +1345,17 @@ declare class Flux<T> extends AbstractPipePublisher<T, Flux<T>> implements PipeP
      */
     distinctUntilChanged(comparator?: (a: T, b: T) => boolean): Flux<T>;
     /**
-     * Delays the delivery of each item by `ms` milliseconds using the delay scheduler.
+     * Delays the delivery of each item by `ms` milliseconds.
+     *
+     * Items are processed **one at a time**: the next item is requested from the source
+     * only after the previous delayed item has been delivered downstream.  This guarantees
+     * items are spaced at least `ms` apart and that `onComplete` fires only after the last
+     * delayed item has been delivered.
      *
-     * The source is subscribed to at full speed; each emitted item is individually
-     * scheduled for delivery after the specified delay.
+     * Errors are forwarded immediately without delay, cancelling any pending timer.
      *
-     * @param ms - Delay in milliseconds applied to each item.
-     * @returns A `Flux<T>` with delayed item delivery.
+     * @param ms - Delay in milliseconds between consecutive item deliveries.
+     * @returns A `Flux<T>` where each item is delayed by `ms` before being forwarded.
      */
     delayElements(ms: number): Flux<T>;
     /**
@@ -1076,7 +1433,281 @@ declare class Flux<T> extends AbstractPipePublisher<T, Flux<T>> implements PipeP
      * @returns A `Mono<void>` that completes once `other` completes.
      */
     thenEmpty(other: Publisher<unknown>): Mono<void>;
+    /**
+     * Re-subscribes to the source when the publisher returned by `fn` emits,
+     * enabling controlled retry with strategies like exponential back-off.
+     *
+     * `fn` receives a `Flux<Error>` — the stream of errors emitted by each failed attempt.
+     * Each emission from the returned publisher triggers a retry.
+     * When the returned publisher completes or errors, the retry loop stops.
+     *
+     * @param fn - Receives an error stream and returns a control publisher.
+     * @returns A `Flux<T>` with dynamic retry behaviour.
+     *
+     * @example
+     * ```typescript
+     * // Exponential back-off: wait 2^n × 100ms between retries, max 3 retries
+     * flux.retryWhen(errors =>
+     *   errors.zipWith(Flux.range(1, 3), (_, n) => n)
+     *         .flatMap(n => Mono.delay(n * 100))
+     * );
+     * ```
+     */
+    retryWhen(fn: (errors: Flux<Error>) => Publisher<unknown>): Flux<T>;
+    /**
+     * Re-subscribes to the source each time it completes normally, as controlled by
+     * the publisher returned by `fn` (**polling** semantics).
+     *
+     * `fn` receives a `Flux<void>` — one emission per completion. Each emission triggers
+     * a repeat. When the control publisher completes or errors, the loop stops.
+     *
+     * @param fn - Receives a completion-signal stream and returns a control publisher.
+     * @returns A `Flux<T>` that repeats under the control of `fn`.
+     *
+     * @example
+     * ```typescript
+     * // Poll every second, stop after 5 times
+     * fetchLatest()
+     *   .toFlux()
+     *   .repeatWhen(completes => completes.zipWith(Flux.range(1, 5), (_, n) => n)
+     *                                     .flatMap(() => Mono.delay(1000)));
+     * ```
+     */
+    repeatWhen(fn: (completes: Flux<void>) => Publisher<unknown>): Flux<T>;
+    /**
+     * Groups items by a key derived from `keyFn`, emitting a {@link GroupedFlux} per
+     * unique key. Each `GroupedFlux` is itself a `Flux<T>` exposing the group `key`.
+     *
+     * The source is consumed at full speed. Items are routed to the corresponding group's
+     * buffer and replayed to any subscriber of that group.
+     *
+     * @param keyFn - Extracts the group key from each item.
+     * @returns A `Flux<GroupedFlux<K, T>>` emitting one group per unique key.
+     *
+     * @example
+     * ```typescript
+     * Flux.just(1, 2, 3, 4, 5)
+     *   .groupBy(n => n % 2 === 0 ? 'even' : 'odd')
+     *   .flatMap(group => group.collectList().map(items => ({ key: group.key, items })))
+     *   .subscribe(v => console.log(v));
+     * // { key: 'odd', items: [1, 3, 5] }
+     * // { key: 'even', items: [2, 4] }
+     * ```
+     */
+    groupBy<K>(keyFn: (value: T) => K): Flux<GroupedFlux<K, T>>;
+    /**
+     * Buffers items into arrays emitted when either `maxSize` items accumulate
+     * **or** `ms` milliseconds elapse since the last flush — whichever comes first.
+     *
+     * @param maxSize - Maximum items per batch.
+     * @param ms - Maximum time (ms) to wait before flushing a partial batch.
+     * @returns A `Flux<T[]>` of batches.
+     *
+     * @example
+     * ```typescript
+     * // Batch up to 10 items or flush every 500ms
+     * eventStream.bufferTimeout(10, 500).subscribe(batch => sendBatch(batch));
+     * ```
+     */
+    bufferTimeout(maxSize: number, ms: number): Flux<T[]>;
+    /**
+     * Samples this `Flux`, emitting the **most recent** item whenever `trigger` emits.
+     *
+     * If no item has arrived since the last sample, the trigger emission is ignored.
+     * Useful for rate-limiting with external signals (scroll, resize, `requestAnimationFrame`).
+     *
+     * @param trigger - Controls when to sample; its value is ignored.
+     * @returns A `Flux<T>` emitting the latest value at each trigger tick.
+     */
+    sample(trigger: Publisher<unknown>): Flux<T>;
+    /**
+     * For each item, subscribes to `triggerFn(item)` and waits for it to emit or complete
+     * before forwarding the item downstream (**delayUntil** semantics).
+     *
+     * Triggers are executed sequentially (concatMap semantics). The trigger's value
+     * is ignored — only its timing matters.
+     *
+     * @param triggerFn - Returns a publisher whose first signal releases the item.
+     * @returns A `Flux<T>` where each item is held until its trigger fires.
+     *
+     * @example
+     * ```typescript
+     * Flux.just(1, 2, 3)
+     *   .delayUntil(() => Mono.delay(100))
+     *   .subscribe(v => console.log(v)); // each item delayed 100ms
+     * ```
+     */
+    delayUntil(triggerFn: (value: T) => Publisher<unknown>): Flux<T>;
+    /**
+     * Recursively expands each item using `fn`, emitting both the original items and
+     * all items produced by the expansion (**breadth-first** order).
+     *
+     * Useful for **pagination**: call `fn` with the current page to fetch the next,
+     * until `fn` returns empty.
+     *
+     * @param fn - Receives an item; returns a publisher of zero or more new items to expand.
+     * @returns A `Flux<T>` of all original and expanded items.
+     *
+     * @example
+     * ```typescript
+     * // Fetch all pages recursively
+     * fetchPage(1)
+     *   .toFlux()
+     *   .expand(page => page.hasNext ? fetchPage(page.nextId).toFlux() : Flux.empty())
+     *   .subscribe(page => process(page));
+     * ```
+     */
+    expand(fn: (value: T) => Publisher<T>): Flux<T>;
+    /**
+     * Recursively expands each item using `fn`, emitting both the original items and
+     * all items produced by the expansion (**depth-first** order).
+     *
+     * Unlike {@link expand} (breadth-first), each item's children are emitted immediately
+     * after the item itself, before any sibling items are processed. This mirrors a
+     * recursive pre-order tree traversal.
+     *
+     * @param fn - Receives an item; returns a publisher of zero or more new items to expand.
+     * @returns A `Flux<T>` of all original and expanded items in depth-first order.
+     *
+     * @example
+     * ```typescript
+     * // Tree: 1 → [2, 3], 2 → [4, 5], others → empty
+     * Flux.just(1)
+     *   .expandDeep(n =>
+     *     n === 1 ? Flux.just(2, 3) :
+     *     n === 2 ? Flux.just(4, 5) :
+     *     Flux.empty()
+     *   )
+     *   .subscribe(v => console.log(v));
+     * // 1 2 4 5 3  (depth-first pre-order)
+     * ```
+     */
+    expandDeep(fn: (value: T) => Publisher<T>): Flux<T>;
+    /**
+     * Pairs each item with the time elapsed (in ms) since the **previous** item
+     * (or since subscription for the first item).
+     *
+     * @returns A `Flux<[number, T]>` where the first element is elapsed milliseconds.
+     *
+     * @example
+     * ```typescript
+     * Flux.interval(100).take(3).elapsed().subscribe(([ms, n]) => console.log(ms, n));
+     * // ~100 0   ~100 1   ~100 2
+     * ```
+     */
+    elapsed(): Flux<[number, T]>;
+    /**
+     * Attaches a `Date.now()` timestamp (in ms since epoch) to each item.
+     *
+     * @returns A `Flux<[number, T]>` where the first element is the Unix timestamp in ms.
+     */
+    timestamp(): Flux<[number, T]>;
+    /**
+     * Wraps each signal (next, error, complete) into a {@link Signal} data object,
+     * emitting them all as `onNext` items on a `Flux<Signal<T>>`.
+     *
+     * After materializing, the resulting `Flux` always completes normally (errors become
+     * `Signal.error` items rather than `onError` signals).
+     * Use {@link dematerialize} to convert back.
+     *
+     * @returns A `Flux<Signal<T>>` where every event is represented as a data item.
+     */
+    materialize(): Flux<Signal<T>>;
+    /**
+     * Unwraps a `Flux<Signal<R>>` back into a regular `Flux<R>`, restoring
+     * `error` and `complete` signals from their materialized form.
+     *
+     * This is the inverse of {@link materialize}.
+     *
+     * @returns A `Flux<R>` with signals restored from the `Signal` wrappers.
+     */
+    dematerialize<R>(this: Flux<Signal<R>>): Flux<R>;
+    /**
+     * Buffers all upstream items regardless of downstream demand, delivering them
+     * when demand becomes available.
+     *
+     * If `maxSize` is exceeded, an overflow error is signalled downstream.
+     *
+     * @param maxSize - Maximum buffer capacity (default: unbounded).
+     * @returns A `Flux<T>` with explicit backpressure buffering.
+     */
+    onBackpressureBuffer(maxSize?: number): Flux<T>;
+    /**
+     * Drops upstream items that arrive when downstream has no outstanding demand.
+     *
+     * An optional `onDrop` callback is invoked for each dropped item.
+     *
+     * @param onDrop - Optional callback called with each dropped item.
+     * @returns A `Flux<T>` with drop backpressure strategy.
+     */
+    onBackpressureDrop(onDrop?: (value: T) => void): Flux<T>;
+    /**
+     * Keeps only the **latest** upstream item when downstream has no demand;
+     * older buffered items are overwritten as new ones arrive.
+     *
+     * @returns A `Flux<T>` with latest-value backpressure strategy.
+     */
+    onBackpressureLatest(): Flux<T>;
+    /**
+     * Requests items from upstream in batches of `n`, replenishing when 75% of
+     * the batch has been consumed (**prefetch** / **limitRate** semantics).
+     *
+     * Prevents requesting all items at once from expensive sources.
+     *
+     * @param n - Prefetch batch size.
+     * @returns A `Flux<T>` with controlled upstream demand.
+     */
+    limitRate(n: number): Flux<T>;
+    /**
+     * Filters items by runtime type, passing only items that are instances of `constructor`.
+     *
+     * @typeParam R - The target subtype.
+     * @param constructor - The class/constructor to filter by.
+     * @returns A `Flux<R>` containing only items that pass `instanceof`.
+     *
+     * @example
+     * ```typescript
+     * class Cat { meow() {} }
+     * class Dog { bark() {} }
+     * Flux.just(new Cat(), new Dog(), new Cat())
+     *   .ofType(Cat)
+     *   .subscribe(cat => cat.meow());
+     * ```
+     */
+    ofType<R extends T>(constructor: new (...args: unknown[]) => R): Flux<R>;
+    /**
+     * Applies a reusable operator function `fn` to this `Flux`, deferred per subscription.
+     *
+     * `fn` receives this `Flux<T>` (as a `Publisher<T>`) and returns a new `Publisher<R>`.
+     * The transformation is re-evaluated on each `subscribe()` call (deferred assembly).
+     *
+     * @param fn - Operator function to apply.
+     * @returns A `Flux<R>` produced by `fn`.
+     *
+     * @example
+     * ```typescript
+     * const retryThrice = <T>(source: Publisher<T>) => Flux.from(source).retry(3);
+     * Flux.just(1, 2).transformDeferred(retryThrice).subscribe(v => console.log(v));
+     * ```
+     */
+    transformDeferred<R>(fn: (flux: Publisher<T>) => Publisher<R>): Flux<R>;
 }
+/**
+ * A `Flux<T>` tagged with a group `key`.
+ *
+ * Produced by {@link Flux#groupBy} — subscribe to it exactly like any `Flux<T>`;
+ * the extra `key` property identifies which group this stream belongs to.
+ *
+ * Implemented as a plain type intersection rather than a subclass: the runtime
+ * object is an ordinary `Flux<T>` with a `key` property attached via
+ * `Object.assign`, so no extra prototype chain is required.
+ *
+ * @typeParam K - The type of the group key.
+ * @typeParam T - The type of items in the group.
+ */
+type GroupedFlux<K, T> = Flux<T> & {
+    readonly key: K;
+};
 
 /**
  * A cold publisher of 0 or 1 items with full backpressure support.
@@ -1187,6 +1818,61 @@ declare class Mono<T> extends AbstractPipePublisher<T, Mono<T>> implements PipeP
      * @returns A lazy `Mono<T>`.
      */
     static defer<T>(factory: () => Mono<T>): Mono<T>;
+    /**
+     * Alias for {@link Mono.generate} — imperative push interface.
+     *
+     * The generator receives a {@link Sink} and should call exactly one of:
+     * `sink.next(value)`, `sink.error(err)`, or `sink.complete()`.
+     *
+     * @param generator - Function that drives the `Mono` via the provided `Sink<T>`.
+     * @returns A cold `Mono<T>`.
+     */
+    static create<T>(generator: (sink: Sink<T>) => void): Mono<T>;
+    /**
+     * Creates a `Mono<number>` that emits `0` after `ms` milliseconds then completes.
+     *
+     * Useful for introducing timed delays in reactive pipelines.
+     *
+     * @param ms - The delay in milliseconds.
+     * @returns A `Mono<number>` that emits `0` after the delay.
+     *
+     * @example
+     * ```typescript
+     * Mono.delay(500).flatMap(() => Mono.just('hello')).subscribe(v => console.log(v));
+     * ```
+     */
+    static delay(ms: number): Mono<number>;
+    /**
+     * Creates a `Mono<T>` from a synchronous, potentially-throwing factory function.
+     *
+     * The factory is called **lazily** at subscription time (not at assembly time).
+     * If the factory throws, the exception is forwarded as `onError`.
+     *
+     * @param fn - Synchronous factory invoked once per subscription.
+     * @returns A cold `Mono<T>`.
+     *
+     * @example
+     * ```typescript
+     * Mono.fromCallable(() => JSON.parse(rawJson)).subscribe(v => console.log(v));
+     * ```
+     */
+    static fromCallable<T>(fn: () => T): Mono<T>;
+    /**
+     * Races multiple `Mono`s — emits the first value to arrive, cancelling the rest.
+     *
+     * If a source completes without emitting, it is excluded from the race.
+     * If **all** sources complete empty, the resulting `Mono` also completes empty.
+     * If any source errors before another source emits, the error is propagated.
+     *
+     * @param sources - One or more `Mono<T>` sources to race.
+     * @returns A `Mono<T>` that emits the first available value.
+     *
+     * @example
+     * ```typescript
+     * Mono.firstWithValue(slow, fast).subscribe(v => console.log(v)); // fast's value
+     * ```
+     */
+    static firstWithValue<T>(...sources: Mono<T>[]): Mono<T>;
     /**
      * Transforms the emitted value using `fn`, producing a `Mono<R>`.
      *
@@ -1326,6 +2012,122 @@ declare class Mono<T> extends AbstractPipePublisher<T, Mono<T>> implements PipeP
      * @returns A `Mono<boolean>`.
      */
     hasElement(): Mono<boolean>;
+    /**
+     * Side effect executed when the `Mono` emits its value.
+     *
+     * Does **not** affect the emitted value or stream lifecycle.
+     * Exceptions thrown by `fn` are forwarded as `onError`.
+     *
+     * @param fn - Called with the emitted value.
+     * @returns A `Mono<T>` with the side effect attached.
+     *
+     * @example
+     * ```typescript
+     * Mono.just(42).doOnSuccess(v => console.log('got', v)).subscribe();
+     * ```
+     */
+    doOnSuccess(fn: (value: T) => void): Mono<T>;
+    /**
+     * Converts a terminal error into a normal `onComplete` signal.
+     *
+     * If a `predicate` is supplied, only errors for which the predicate returns `true`
+     * are swallowed; others are re-propagated as-is.
+     *
+     * @param predicate - Optional filter; when absent all errors are converted.
+     * @returns A `Mono<T>` that completes rather than errors (when predicate matches).
+     *
+     * @example
+     * ```typescript
+     * Mono.error(new Error('oops')).onErrorComplete().subscribe(undefined, undefined, () => console.log('done'));
+     * ```
+     */
+    onErrorComplete(predicate?: (e: Error) => boolean): Mono<T>;
+    /**
+     * Ignores any value emitted by this `Mono` and, upon normal completion,
+     * emits `value` instead.
+     *
+     * Errors from the source are propagated unchanged.
+     *
+     * @param value - The value to emit after this `Mono` completes.
+     * @returns A `Mono<R>` that emits `value` on source completion.
+     *
+     * @example
+     * ```typescript
+     * Mono.just('ignored').thenReturn(42).subscribe(v => console.log(v)); // 42
+     * ```
+     */
+    thenReturn<R>(value: R): Mono<R>;
+    /**
+     * Delays delivery of the emitted value by `ms` milliseconds.
+     *
+     * The delay is introduced **after** the source emits; completion and errors
+     * are forwarded without delay.
+     *
+     * @param ms - Delay in milliseconds.
+     * @returns A `Mono<T>` whose value arrives `ms` milliseconds later.
+     *
+     * @example
+     * ```typescript
+     * Mono.just('hello').delayElement(200).subscribe(v => console.log(v));
+     * ```
+     */
+    delayElement(ms: number): Mono<T>;
+    /**
+     * Holds the emitted value until a trigger publisher (returned by `triggerFn`) emits
+     * or completes, then forwards the value downstream.
+     *
+     * If the trigger errors, the error is propagated and the value is discarded.
+     * If the source is empty, completes immediately without invoking `triggerFn`.
+     *
+     * @param triggerFn - Receives the emitted value and returns a trigger `Publisher`.
+     * @returns A `Mono<T>` that emits after the trigger fires.
+     *
+     * @example
+     * ```typescript
+     * Mono.just(42).delayUntil(() => Mono.delay(300)).subscribe(v => console.log(v));
+     * ```
+     */
+    delayUntil(triggerFn: (value: T) => Publisher<unknown>): Mono<T>;
+    /**
+     * Falls back to `other` if this `Mono` completes without emitting a value (empty).
+     *
+     * If this `Mono` emits a value or errors, `other` is never subscribed to.
+     *
+     * @param other - The fallback `Mono<T>` to subscribe to when the source is empty.
+     * @returns A `Mono<T>` that emits from `other` when the source is empty.
+     *
+     * @example
+     * ```typescript
+     * Mono.empty<number>().or(Mono.just(99)).subscribe(v => console.log(v)); // 99
+     * ```
+     */
+    or(other: Mono<T>): Mono<T>;
+    /**
+     * Re-subscribes to this `Mono` on error, using a control publisher to decide
+     * whether and when to retry.
+     *
+     * Each time the source errors, the error is pushed to the control stream returned
+     * by `fn`. If that stream emits any item, the source is re-subscribed. If it
+     * completes or errors, that terminal signal is forwarded downstream.
+     *
+     * @param fn - Receives a `Flux<Error>` of upstream errors; returns a control publisher.
+     * @returns A `Mono<T>` that retries according to the control signal.
+     *
+     * @example
+     * ```typescript
+     * Mono.error(new Error('boom'))
+     *   .retryWhen(errors => errors.take(3))
+     *   .subscribe(undefined, e => console.error(e));
+     * ```
+     */
+    retryWhen(fn: (errors: Flux<Error>) => Publisher<unknown>): Mono<T>;
+    /**
+     * Alias for {@link Mono#toPromise} — returns a `Promise<T | null>` that resolves
+     * with the emitted value (or `null` if the `Mono` is empty).
+     *
+     * @returns A `Promise<T | null>`.
+     */
+    toFuture(): Promise<T | null>;
     /**
      * Subscribes to this `Mono` and returns a `Promise<T | null>`.
      *
@@ -1555,4 +2357,4 @@ declare const Sinks: {
     };
 };
 
-export { type CancellableScheduler, Flux, Mono, type Publisher, type Scheduler, Schedulers, type Sink, type SinkPublisher, Sinks, type Subscriber, type Subscription };
+export { type CancellableScheduler, Flux, type FluxSink, type GroupedFlux, Mono, type Publisher, type Scheduler, Schedulers, Signal, type Sink, type SinkPublisher, Sinks, type Subscriber, type Subscription };