@thi.ng/rstream-graph/graph.d.ts

Declarative dataflow graph construction for @thi.ng/rstream

import type { IObjectOf, Maybe, Tuple } from "@thi.ng/api";
import type { IAtom } from "@thi.ng/atom";
import { type ResolveFn } from "@thi.ng/resolve-map";
import type { ISubscription } from "@thi.ng/rstream";
import type { Transducer } from "@thi.ng/transducers";
import type { Graph, GraphSpec, Node, NodeFactory, NodeSpec } from "./api.js";
/**
 * Dataflow graph initialization function. Takes a state Atom (or `null` if not
 * needed) and an object of {@link NodeSpec} values or functions returning
 * {@link Node} objects. Calls `nodeFromSpec()` for each spec and then
 * recursively resolves references via
 * [`resolve`](https://docs.thi.ng/umbrella/resolve-map/functions/resolve.html).
 * Returns new initialized graph object of {@link Node} objects and
 * [`thi.ng/rstream`](https://thi.ng/rstream) stream constructs. Does NOT mutate
 * original {@link GraphSpec} object.
 *
 * @param state -
 * @param spec -
 */
export declare const initGraph: (state: IAtom<any>, spec: GraphSpec) => Graph;
/**
 * Transforms a single {@link NodeSpec} into a lookup function for
 * {@link resolve} (which is called from {@link initGraph}). When that function
 * is called, recursively resolves all specified input streams and calls this
 * spec's `fn` to produce a new stream from these inputs.
 *
 * If the spec includes the optional `outs` keys, it also creates the
 * subscriptions for each of the given output keys, which then can be used as
 * inputs by other nodes. Each value in the `outs` subspec can be a function or
 * state path (string/number/array, see [`thi.ng/paths`](https://thi.ng/paths)).
 * Functions are called with this node's constructed stream/subscribable and the
 * output id and must return a new
 * [`ISubscribable`](https://docs.thi.ng/umbrella/rstream/interfaces/ISubscribable.html).
 * For path values a subscription is added to this node's result stream which
 * then updates the provided state atom at the path given.
 *
 * Non-function output specs subs assume the raw node output value is an object
 * from which the different output keys are being extracted. The special `*`
 * output key can be used to handle the entire node output value. This is
 * useful/required for non-object node result values.
 *
 * @example
 * ```ts
 * out: {
 *   // fn output spec
 *   // creates new sub which uses {@link pick} transducer to
 *   // select key `a` from main node output (assumed to be object)
 *   a: (node, id) => node.subscribe({}, pick(id)),
 *
 *   // yields sub of `b` key's values extracted from main output
 *   // and also stores them at given path in state atom
 *   b: "foo.b"
 *
 *   // yields sub with same value as main node output and
 *   // stores vals in state atom at given path
 *   "*": "foo.main"
 * }
 * ```
 *
 * See `api.ts` for further details and possible spec variations.
 *
 * @param state -
 * @param spec -
 * @param id -
 */
export declare const nodeFromSpec: (state: IAtom<any>, spec: NodeSpec, id: string) => (resolve: ResolveFn) => Node;
/**
 * Compiles given {@link NodeSpec} and adds it to graph. Returns compiled
 * {@link Node} object for the given spec. Throws error if the graph already
 * contains a node with given `id`.
 *
 * @param graph -
 * @param state -
 * @param id -
 * @param spec -
 */
export declare const addNode: (graph: Graph, state: IAtom<any>, id: string, spec: NodeSpec) => Node;
/**
 * Calls `.unsubscribe()` on given node and all of its outputs, then
 * removes it from graph. Returns `false` if no node exists for given
 * `id`.
 *
 * @param graph -
 * @param id -
 */
export declare const removeNode: (graph: Graph, id: string) => boolean;
/**
 * Calls `.unsubscribe()` on all nodes in the graph, causing all related
 * streams & subscriptions to terminate.
 *
 * @param graph -
 */
export declare const stop: (graph: Graph) => void;
/**
 * Higher order node / stream creator. Takes a transducer and (optional)
 * required input stream IDs. The returned function takes an object of input
 * streams and returns a new
 * [`StreamSync`](https://docs.thi.ng/umbrella/rstream/classes/StreamSync.html)
 * instance. The returned function will throw an error if `inputIDs` is given
 * and the object of inputs does not contain all of them.
 *
 * If `reset` is true (default: false), the `xform` will only re-run when all
 * inputs have produced new values. See
 * [`StreamSync`](https://docs.thi.ng/umbrella/rstream/classes/StreamSync.html)
 * for further reference.
 *
 * // TODO add close behavior opts
 *
 * @param xform -
 * @param inputIDs -
 * @param reset -
 */
export declare const node: (xform: Transducer<IObjectOf<any>, any>, inputIDs?: string[], reset?: boolean) => NodeFactory<any>;
/**
 * Similar to {@link node}, but optimized for nodes using only a single
 * input. Uses "src" as default input ID.
 *
 * // TODO add close behavior opts
 *
 * @param xform -
 * @param inputID -
 */
export declare const node1: (xform?: Transducer<any, any>, inputID?: string) => NodeFactory<any>;
/**
 * Syntax sugar for `node()`, intended for nodes w/ 2 inputs, by default
 * named `a` & `b` (but can be overridden).
 *
 * @param xform -
 * @param inputIDs -
 * @param reset -
 */
export declare const node2: (xform: Transducer<IObjectOf<any>, any>, inputIDs?: Tuple<string, 2>, reset?: boolean) => NodeFactory<any>;
/**
 * Helper function to verify given object of inputs has required input IDs.
 * Throws error if validation fails.
 *
 * @param src -
 * @param inputIDs -
 * @param nodeID -
 */
export declare const ensureInputs: (src: IObjectOf<ISubscription<any, any>>, inputIDs: Maybe<string[]>, nodeID: string) => void;
//# sourceMappingURL=graph.d.ts.map