@thi.ng/rstream/stream.d.ts

Reactive streams & subscription primitives for constructing dataflow graphs / pipelines

import type { Maybe } from "@thi.ng/api";
import type { CommonOpts, IStream, ISubscriber, ISubscription, StreamCancel, StreamSource, TransformableOpts, WithErrorHandlerOpts } from "./api.js";
import { Subscription } from "./subscription.js";
/**
 * Creates a new {@link Stream} instance, optionally with given `StreamSource`
 * function and / or options.
 *
 * @remarks
 * If a `src` function is provided, the function will be only called (with the
 * `Stream` instance as single argument) once the first subscriber has attached
 * to the stream. If the function returns another function, it will be used for
 * cleanup purposes if the stream is cancelled, e.g. if the first / last
 * subscriber has unsubscribed (depending on `closeOut` option). Streams are
 * intended as (primarily async) data sources in a dataflow graph and are the
 * primary construct for the various `from*()` functions provided by this
 * package. However, streams can also be triggered manually (from outside the
 * stream), in which case the user should call `stream.next()` to cause value
 * propagation.
 *
 * Streams (like {@link Subscription}) implement the
 * [`IDeref`](https://docs.thi.ng/umbrella/api/interfaces/IDeref.html) interface
 * which provides read access to a stream's last received value. This is useful
 * for various purposes, e.g. in combination with
 * [`thi.ng/hdom`](https://thi.ng/hdom), which supports direct embedding of
 * streams (i.e. their values) into UI components (and will be deref them
 * automatically). If the stream has not yet emitted a value, value caching is
 * disabled or if the stream is done, it will deref to `undefined`.
 *
 * @example
 * ```ts tangle:../export/stream.ts
 * import { stream, subscription, trace } from "@thi.ng/rstream";
 *
 * const a = stream((s) => {
 *     s.next(1);
 *     s.next(2);
 *     s.done()
 * });
 * a.subscribe(trace("a"))
 * // a 1
 * // a 2
 * // a done
 *
 * // as reactive value mechanism
 * const b = stream();
 * // or alternatively
 * // b = subscription();
 *
 * b.subscribe(trace("b1"));
 * b.subscribe(trace("b2"));
 *
 * // external / manual trigger
 * b.next(42);
 * // b1 42
 * // b2 42
 * ```
 *
 * @param opts -
 */
export declare function stream<T>(opts?: Partial<WithErrorHandlerOpts>): Stream<T>;
export declare function stream<T>(src: StreamSource<T>, opts?: Partial<WithErrorHandlerOpts>): Stream<T>;
/**
 * Syntax sugar for {@link stream}. Creates new stream which is
 * immediately seeded with initial `val` and configured with optional
 * `opts`.
 *
 * @param val -
 * @param opts -
 */
export declare const reactive: <T>(val: T, opts?: Partial<CommonOpts>) => Stream<T>;
/**
 * See {@link stream} & {@link reactive} for reference & examples.
 */
export declare class Stream<T> extends Subscription<T, T> implements IStream<T> {
    src?: StreamSource<T>;
    protected _cancel: Maybe<StreamCancel>;
    protected _inited: boolean;
    constructor(opts?: Partial<WithErrorHandlerOpts>);
    constructor(src: StreamSource<T>, opts?: Partial<WithErrorHandlerOpts>);
    subscribe<C>(sub: ISubscription<T, C>): ISubscription<T, C>;
    subscribe(sub: Partial<ISubscriber<T>>, opts?: Partial<CommonOpts>): ISubscription<T, T>;
    subscribe<C>(sub: Partial<ISubscriber<C>>, opts?: Partial<TransformableOpts<T, C>>): ISubscription<T, C>;
    unsubscribe(sub?: ISubscription<T, any>): boolean;
    done(): void;
    error(e: any): boolean;
    cancel(): void;
}
//# sourceMappingURL=stream.d.ts.map