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

Reactive streams & subscription primitives for constructing dataflow graphs / pipelines

import type { Fn, Maybe } from "@thi.ng/api";
import type { Reduced, Reducer, Transducer } from "@thi.ng/transducers";
import { State, type CloseMode, type CommonOpts, type ISubscriber, type ISubscription, type SubscriptionOpts, type TransformableOpts, type WithErrorHandlerOpts, type WithTransform } from "./api.js";
/**
 * Creates a new {@link Subscription} instance, the fundamental datatype and
 * building block provided by this package.
 *
 * @remarks
 * Most other types in rstream, including {@link Stream}s, are `Subscription`s
 * and all can be:
 *
 * - connected into directed graphs (sync or async & not necessarily DAGs)
 * - transformed using transducers (incl. support for early termination)
 * - can have any number of subscribers (optionally each w/ their own
 *   transducers)
 * - recursively unsubscribe themselves from parent after their last subscriber
 *   unsubscribed (configurable)
 * - will go into a non-recoverable error state if none of the subscribers has
 *   an error handler itself
 * - implement the
 *   [`IDeref`](https://docs.thi.ng/umbrella/api/interfaces/IDeref.html)
 *   interface
 *
 * If a transducer is provided (via the `xform` option), all received values
 * will be first processed by the transducer and only its transformed result(s)
 * (if any) will be passed to downstream subscribers. Any uncaught errors
 * *inside* the transducer will cause this subscription's error handler to be
 * called and will stop this subscription from receiving any further values (by
 * default, unless overridden).
 *
 * Subscription behavior can be customized via the additional (optional) options
 * arg. See {@link CommonOpts} and {@link SubscriptionOpts} for further details.
 *
 * @example
 * ```ts tangle:../export/subscription.ts
 * import { subscription, trace } from "@thi.ng/rstream";
 * import { filter } from "@thi.ng/transducers";
 *
 * // as reactive value mechanism (same as with stream() above)
 * const s = subscription<number, number>();
 *
 * // attach child subscriptions
 * s.subscribe(trace("s1"));
 * // this child sub will receive filtered values only
 * s.subscribe(trace("s2"), { xform: filter((x: number) => x > 25) });
 *
 * // external trigger
 * s.next(23);
 * // s1 23
 * s.next(42);
 * // s1 42
 * // s2 42
 * ```
 *
 * @param sub -
 * @param opts -
 */
export declare const subscription: <A, B>(sub?: Partial<ISubscriber<B>>, opts?: Partial<SubscriptionOpts<A, B>>) => Subscription<A, B>;
export declare class Subscription<A, B> implements ISubscription<A, B> {
    protected wrapped?: Partial<ISubscriber<B>> | undefined;
    id: string;
    closeIn: CloseMode;
    closeOut: CloseMode;
    parent?: ISubscription<any, A>;
    __owner?: ISubscription<any, any>;
    protected xform?: Reducer<A, B[]>;
    protected cacheLast: boolean;
    protected last: any;
    protected state: State;
    protected subs: Partial<ISubscriber<B>>[];
    constructor(wrapped?: Partial<ISubscriber<B>> | undefined, opts?: Partial<SubscriptionOpts<A, B>>);
    deref(): Maybe<B>;
    getState(): State;
    protected setState(state: State): void;
    /**
     * Creates new child subscription with given subscriber and/or
     * transducer and options.
     */
    subscribe<C>(sub: ISubscription<B, C>): ISubscription<B, C>;
    subscribe(sub: Partial<ISubscriber<B>>, opts?: Partial<CommonOpts>): ISubscription<B, B>;
    subscribe<C>(sub: Partial<ISubscriber<C>>, opts?: Partial<TransformableOpts<B, C>>): ISubscription<B, C>;
    /**
     * Creates a new child subscription using given transducers and optional
     * subscription ID. Supports up to 4 transducers and if more than one
     * transducer is given, composes them in left-to-right order using
     * [`comp`](https://docs.thi.ng/umbrella/transducers/functions/comp.html).
     *
     * Shorthand for `subscribe(comp(xf1, xf2,...), id)`
     */
    transform<C>(a: Transducer<B, C>, opts?: Partial<WithErrorHandlerOpts>): ISubscription<B, C>;
    transform<C, D>(a: Transducer<B, C>, b: Transducer<C, D>, opts?: Partial<WithErrorHandlerOpts>): ISubscription<B, D>;
    transform<C, D, E>(a: Transducer<B, C>, b: Transducer<C, D>, c: Transducer<D, E>, opts?: Partial<WithErrorHandlerOpts>): ISubscription<B, E>;
    transform<C, D, E, F>(a: Transducer<B, C>, b: Transducer<C, D>, c: Transducer<D, E>, d: Transducer<E, F>, opts?: Partial<WithErrorHandlerOpts>): ISubscription<B, F>;
    transform<C>(opts: WithTransform<B, C> & Partial<WithErrorHandlerOpts>): ISubscription<B, C>;
    /**
     * Syntax sugar for {@link Subscription.transform} when using a single
     * [`map`](https://docs.thi.ng/umbrella/transducers/functions/map.html)
     * transducer only. The given function `fn` is used as `map`'s
     * transformation fn.
     *
     * @param fn -
     * @param opts -
     */
    map<C>(fn: Fn<B, C>, opts?: Partial<WithErrorHandlerOpts>): ISubscription<B, C>;
    unsubscribe(sub?: ISubscription<B, any>): boolean;
    protected unsubscribeSelf(): boolean;
    protected unsubscribeChild(sub: ISubscription<B, any>): boolean;
    next(x: A): void;
    done(): void;
    error(e: any): boolean;
    protected unhandledError(e: any): boolean;
    protected dispatchTo(type: "next" | "done" | "error", x?: B): boolean;
    protected dispatch(x: B): void;
    protected dispatchXform(x: A): void;
    protected dispatchXformDone(): boolean;
    protected dispatchXformVals(acc: B[] | Reduced<B[]>): boolean;
    protected ensureState(): void;
    protected release(): void;
}
//# sourceMappingURL=subscription.d.ts.map