runflow/dist/index.d.ts

A fast and reliable flow engine for orchestration and more uses in *Node.js*

import { Debugger } from 'debug';

interface FlowSpec {
    tasks?: TaskSpecMap;
    configs?: FlowConfigs;
    options?: FlowOptions;
}
declare class TaskSpecMap {
    [code: string]: TaskSpec;
}
interface TaskSpec {
    requires?: string[];
    provides?: string[];
    defaultResult?: AnyValue;
    resolver?: TaskResolverSpec;
}
interface TaskResolverSpec {
    name: string;
    params?: TaskParamsMap;
    results?: TaskResultsMap;
}
interface TaskParamsMap {
    [code: string]: string | ResolverParamInfoValue | ResolverParamInfoTransform;
}
interface ResolverParamInfoValue {
    value: AnyValue;
}
interface ResolverParamInfoTransform {
    transform: TransformTemplate;
}
interface TaskResultsMap {
    [code: string]: AnyValue;
}
interface FlowOptions {
    throwErrorOnUnsolvableResult?: boolean;
    resolverAutomapParams?: boolean;
    resolverAutomapResults?: boolean;
}
type FlowConfigs = FlowOptions;

declare class FlowManager {
    static plugins: {
        resolvers: TaskResolverMap;
    };
    static logger: FlowedLogger | null;
    static run(flowSpec: FlowSpec, params?: ValueMap, expectedResults?: string[], resolvers?: TaskResolverMap, context?: ValueMap, options?: ValueMap): OptPromise<ValueMap>;
    static runFromString(flowSpecJson: string, params?: ValueMap, expectedResults?: string[], resolvers?: TaskResolverMap, context?: ValueMap, options?: ValueMap): Promise<ValueMap>;
    static runFromFile(flowSpecFilepath: string, params?: ValueMap, expectedResults?: string[], resolvers?: TaskResolverMap, context?: ValueMap, options?: ValueMap): Promise<ValueMap>;
    static runFromUrl(flowSpecUrl: string, params?: ValueMap, expectedResults?: string[], resolvers?: TaskResolverMap, context?: ValueMap, options?: ValueMap): Promise<ValueMap>;
    static installPlugin(plugin: FlowedPlugin): void;
    static installLogger(logger: FlowedLogger): void;
    static log(entry: FlowedLogEntry): void;
}

declare class Task {
    code: string;
    spec: TaskSpec;
    runStatus: TaskRunStatus;
    constructor(code: string, spec: TaskSpec);
    getResolverName(): string;
    getSerializableState(): SerializedFlowRunStatus;
    setSerializableState(runStatus: TaskRunStatus): void;
    resetRunStatus(): void;
    isReadyToRun(): boolean;
    getResults(): ValueMap;
    supplyReq(reqName: string, value: AnyValue): void;
    supplyReqs(reqsMap: ValueMap): void;
    mapParamsForResolver(solvedReqs: ValueMap, automap: boolean, flowId: number, log: LoggerFn): ValueMap;
    mapResultsFromResolver(solvedResults: ValueMap, automap: boolean, flowId: number, log: LoggerFn): ValueMap;
    protected parseSpec(): void;
}

declare class ProcessManager {
    nextProcessId: number;
    processes: TaskProcess[];
    constructor();
    createProcess(task: Task, taskResolverExecutor: TaskResolverExecutor, context: ValueMap, automapParams: boolean, automapResults: boolean, flowId: number, debug: Debugger, log: LoggerFn): TaskProcess;
    runningCount(): number;
    removeProcess(process: TaskProcess): void;
}

declare class TaskProcess {
    manager: ProcessManager;
    id: number;
    task: Task;
    protected taskResolverExecutor: TaskResolverExecutor;
    protected context: ValueMap;
    protected automapParams: boolean;
    protected automapResults: boolean;
    protected flowId: number;
    protected debug: Debugger;
    protected log: LoggerFn;
    static nextPid: number;
    protected params: ValueMap;
    pid: number;
    constructor(manager: ProcessManager, id: number, task: Task, taskResolverExecutor: TaskResolverExecutor, context: ValueMap, automapParams: boolean, automapResults: boolean, flowId: number, debug: Debugger, log: LoggerFn);
    getParams(): ValueMap;
    run(): Promise<ValueMap>;
}

interface IFlow {
    start(params: ValueMap, expectedResults: string[], resolvers: TaskResolverMap, context: ValueMap): OptPromise<ValueMap>;
    pause(): OptPromise<ValueMap>;
    resume(): OptPromise<ValueMap>;
    stop(): OptPromise<ValueMap>;
    reset(): void;
    getStateCode(): FlowStateEnum;
    debug(formatter: string, ...args: AnyValue[]): void;
}

declare abstract class FlowState implements IFlow {
    protected static builtInResolvers: TaskResolverMap;
    protected runStatus: FlowRunStatus;
    constructor(runStatus: FlowRunStatus);
    start(params: ValueMap, expectedResults: string[], resolvers: TaskResolverMap, context: ValueMap, _options?: ValueMap): OptPromise<ValueMap>;
    finished(_error?: Error | boolean): void;
    pause(): Promise<ValueMap>;
    paused(_error?: Error | boolean): void;
    resume(): Promise<ValueMap>;
    stop(): Promise<ValueMap>;
    stopped(_error?: Error | boolean): void;
    reset(): void;
    abstract getStateCode(): FlowStateEnum;
    execFinishResolve(): void;
    execFinishReject(error: Error): void;
    isRunning(): boolean;
    setExpectedResults(expectedResults: string[]): void;
    getResults(): ValueMap;
    setResolvers(resolvers: TaskResolverMap): void;
    setContext(context: ValueMap): void;
    setRunOptions(options: ValueMap): void;
    supplyParameters(params: ValueMap): void;
    createFinishPromise(): void;
    getResolverForTask(task: Task): TaskResolverExecutor;
    getResolverByName(name: string): TaskResolverExecutor | null;
    getResolvers(): TaskResolverMap;
    supplyResult(resultName: string, result: AnyValue): void;
    getStateInstance(state: FlowStateEnum): FlowState;
    startReadyTasks(): void;
    setState(newState: FlowStateEnum): void;
    getSerializableState(): SerializedFlowRunStatus;
    protected processFinished(process: TaskProcess, error: Error | boolean, stopFlowExecutionOnError: boolean): void;
    protected postProcessFinished(_error: Error | boolean, _stopFlowExecutionOnError: boolean): void;
    protected createTransitionError(transition: string): Error;
    protected createMethodError(method: string): Error;
    debug(formatter: string, ...args: AnyValue[]): void;
    static formatDebugMessage({ n, m, l, e, }: {
        n?: number;
        m: string;
        mp?: ValueMap;
        l?: string;
        e?: string;
    }): string;
    static createLogEntry({ n, m, mp, l, e, pid, task, }: {
        n?: number;
        m: string;
        mp?: ValueMap;
        l?: string;
        e?: string;
        pid?: number;
        task?: AnyValue;
    }, flowStatus?: FlowRunStatus): FlowedLogEntry;
    log({ n, m, mp, l, e, pid, task, }: {
        n?: number;
        m: string;
        mp?: ValueMap;
        l?: string;
        e?: string;
        pid?: number;
        task?: AnyValue;
    }): void;
}

declare class FlowRunStatus {
    static nextId: number;
    flow: Flow;
    id: number;
    processManager: ProcessManager;
    tasksReady: Task[];
    tasksByReq: {
        [req: string]: TaskMap;
    };
    taskProvisions: string[];
    resolvers: TaskResolverMap;
    expectedResults: string[];
    results: ValueMap;
    context: ValueMap;
    runOptions: ValueMap;
    finishResolve: (result: ValueMap) => void;
    finishReject: (error: Error) => void;
    finishPromise: Promise<ValueMap>;
    options: FlowOptions;
    states: {
        [stateKey: string]: FlowState;
    };
    spec: FlowSpec;
    state: FlowState;
    tasks: TaskMap;
    constructor(flow: Flow, spec: FlowSpec, runStatus?: SerializedFlowRunStatus);
    initRunStatus(spec: FlowSpec, runState?: SerializedFlowRunStatus): void;
    fromSerializable(runState: SerializedFlowRunStatus): void;
    toSerializable(): SerializedFlowRunStatus;
}
interface SerializedFlowRunStatus {
    id: number;
    nextProcessId: number;
    tasksReady: string[];
    tasksByReq: {
        [req: string]: string[];
    };
    taskProvisions: string[];
    expectedResults: string[];
    options: FlowOptions;
    results: ValueMap;
    context: ValueMap;
    taskStatuses: {
        [taskCode: string]: TaskRunStatus;
    };
}

declare class Flow implements IFlow {
    protected runStatus: FlowRunStatus;
    constructor(spec?: FlowSpec, runState?: SerializedFlowRunStatus);
    getStateCode(): FlowStateEnum;
    start(params?: ValueMap, expectedResults?: string[], resolvers?: TaskResolverMap, context?: ValueMap, options?: ValueMap): OptPromise<ValueMap>;
    pause(): Promise<ValueMap>;
    resume(): Promise<ValueMap>;
    stop(): Promise<ValueMap>;
    reset(): void;
    getSerializableState(): SerializedFlowRunStatus;
    debug(formatter: string, ...args: AnyValue[]): void;
    log({ n, m, mp, l, e, }: {
        n?: number;
        m: string;
        mp?: ValueMap;
        l?: string;
        e?: string;
    }): void;
}

type ValueQueue = AnyValue[];
interface ValueQueueMap {
    [name: string]: ValueQueue;
}
type SerializableValueQueueManager = ValueQueueMap;
declare class ValueQueueManager {
    static fromSerializable(serializable: ValueQueueManager): ValueQueueManager;
    protected queues: ValueQueueMap;
    protected queueNames: string[];
    protected nonEmptyQueues: Set<string>;
    constructor(queueNames: string[]);
    push(queueName: string, value: AnyValue): void;
    getEmptyQueueNames(): string[];
    popAll(): ValueMap;
    topAll(): ValueMap;
    toSerializable(): SerializableValueQueueManager;
    validateAllNonEmpty(): void;
    allHaveContent(): boolean;
}

declare enum FlowStateEnum {
    Ready = "Ready",
    Running = "Running",
    Finished = "Finished",
    Pausing = "Pausing",
    Paused = "Paused",
    Stopping = "Stopping",
    Stopped = "Stopped"
}
declare enum FlowTransitionEnum {
    Start = "Start",
    Finished = "Finished",
    Reset = "Reset",
    Pause = "Pause",
    Paused = "Paused",
    Resume = "Resume",
    Stop = "Stop",
    Stopped = "Stopped"
}
type AnyValue = any;
type TransformTemplate = AnyValue;
type OptPromise<T> = T | Promise<T>;
interface ValueMap {
    [key: string]: AnyValue;
}
type GenericValueMap = ValueMap;
interface ITaskResolver {
    exec(params: ValueMap, context?: ValueMap, task?: Task, debug?: Debugger, log?: LoggerFn): OptPromise<ValueMap>;
}
declare class TaskResolver implements ITaskResolver {
    exec(_params: ValueMap, _context?: ValueMap, _task?: Task, _debug?: Debugger, _log?: LoggerFn): OptPromise<ValueMap>;
}
type TaskResolverFn = (params: ValueMap, context?: ValueMap, task?: Task, debug?: Debugger, log?: LoggerFn) => OptPromise<ValueMap>;
type TaskResolverClass = typeof TaskResolver;
type TaskResolverExecutor = TaskResolverClass | TaskResolverFn;
declare class TaskResolverMap {
    [key: string]: TaskResolverExecutor;
}
interface TaskMap {
    [code: string]: Task;
}
interface TaskRunStatus {
    solvedReqs: ValueQueueManager;
    solvedResults: ValueMap;
}
interface FlowedPlugin {
    resolverLibrary: TaskResolverMap;
}
interface FlowedLogger {
    log(entry: FlowedLogEntry): void;
}
interface FlowedLogEntry {
    timestamp: Date;
    level: string;
    eventType: string;
    message: string;
    objectId?: string;
    tags?: string[];
    extra?: ValueMap;
}
type LoggerFn = ({ n, m, mp, l, e, }: {
    n?: number;
    m: string;
    mp?: ValueMap;
    l?: string;
    e?: string;
}) => void;

declare class NoopResolver {
    exec(): ValueMap;
}
declare class EchoResolver {
    exec(params: ValueMap): ValueMap;
}
declare class ThrowErrorResolver {
    exec(params: ValueMap): ValueMap;
}
declare class ConditionalResolver {
    exec(params: ValueMap): ValueMap;
}
declare class WaitResolver {
    exec(params: ValueMap): ValueMap;
}
declare class SubFlowResolver {
    exec(params: ValueMap, context: ValueMap): Promise<ValueMap>;
}
declare class RepeaterResolver {
    exec(params: ValueMap, context: ValueMap, task: Task, debug: Debugger, log: LoggerFn): Promise<ValueMap>;
}
declare class ArrayMapResolver {
    exec(params: ValueMap, context: ValueMap, task: Task, debug: Debugger, log: LoggerFn): Promise<ValueMap>;
}
declare class LoopResolver {
    exec(params: ValueMap, context: ValueMap, task: Task, debug: Debugger, log: LoggerFn): Promise<ValueMap>;
}
declare class StopResolver {
    exec(params: ValueMap, context: ValueMap): ValueMap;
}
declare class PauseResolver {
    exec(params: ValueMap, context: ValueMap): ValueMap;
}

export { type AnyValue, ArrayMapResolver, ConditionalResolver, EchoResolver, Flow, type FlowConfigs, FlowManager, type FlowOptions, type FlowSpec, FlowStateEnum, FlowTransitionEnum, type FlowedLogEntry, type FlowedLogger, type FlowedPlugin, type GenericValueMap, type ITaskResolver, type LoggerFn, LoopResolver, NoopResolver, type OptPromise, PauseResolver, RepeaterResolver, type ResolverParamInfoTransform, type ResolverParamInfoValue, StopResolver, SubFlowResolver, Task, type TaskMap, type TaskParamsMap, TaskResolver, type TaskResolverClass, type TaskResolverExecutor, type TaskResolverFn, TaskResolverMap, type TaskResolverSpec, type TaskResultsMap, type TaskRunStatus, type TaskSpec, TaskSpecMap, ThrowErrorResolver, type TransformTemplate, type ValueMap, WaitResolver };