@synergenius/flow-weaver 0.33.2 → 0.44.0

package/dist/ast/builder.js

@@ -1,395 +0,0 @@
-import { EXECUTION_STRATEGIES } from "../constants.js";
-/**
- * Fluent builder for constructing TWorkflowAST programmatically
- *
- * @example
- * ```typescript
- * const workflow = new WorkflowBuilder('myWorkflow', 'myWorkflow', './workflow.ts')
- *   .description('My workflow description')
- *   .addNodeType(nodeType)
- *   .addNodeInstance(instance)
- *   .addConnection(connection)
- *   .build();
- * ```
- */
-export class WorkflowBuilder {
-    ast;
-    /**
-     * Create a new workflow builder
-     * @param name - Internal workflow name
-     * @param functionName - Exported function name
-     * @param sourceFile - Source file path
-     */
-    constructor(name, functionName, sourceFile) {
-        this.ast = {
-            type: "Workflow",
-            sourceFile,
-            name,
-            functionName,
-            nodeTypes: [],
-            instances: [],
-            connections: [],
-            startPorts: {},
-            exitPorts: {},
-            imports: [],
-        };
-    }
-    description(desc) {
-        this.ast.description = desc;
-        return this;
-    }
-    generatedFile(path) {
-        this.ast.generatedFile = path;
-        return this;
-    }
-    addNodeType(nodeType) {
-        this.ast.nodeTypes.push(nodeType);
-        return this;
-    }
-    addNodeInstance(instance) {
-        this.ast.instances.push(instance);
-        return this;
-    }
-    addConnection(connection) {
-        this.ast.connections.push(connection);
-        return this;
-    }
-    addScope(scopeName, instanceIds) {
-        if (!this.ast.scopes) {
-            this.ast.scopes = {};
-        }
-        this.ast.scopes[scopeName] = instanceIds;
-        return this;
-    }
-    addImport(importDecl) {
-        this.ast.imports.push(importDecl);
-        return this;
-    }
-    metadata(key, value) {
-        if (!this.ast.metadata) {
-            this.ast.metadata = {};
-        }
-        this.ast.metadata[key] = value;
-        return this;
-    }
-    /** Build and return the final TWorkflowAST */
-    build() {
-        return this.ast;
-    }
-}
-/**
- * Fluent builder for constructing TNodeTypeAST programmatically
- *
- * NodeTypes are templates that can be instantiated multiple times in a workflow.
- *
- * @example
- * ```typescript
- * const addNode = new NodeTypeBuilder('Add', 'add')
- *   .label('Add Numbers')
- *   .input('a', { dataType: 'NUMBER' })
- *   .input('b', { dataType: 'NUMBER' })
- *   .output('sum', { dataType: 'NUMBER' })
- *   .successPort(true)
- *   .build();
- * ```
- */
-export class NodeTypeBuilder {
-    nodeType;
-    /**
-     * Create a new node type builder
-     * @param name - Unique node type name
-     * @param functionName - Name of the implementing function
-     */
-    constructor(name, functionName) {
-        this.nodeType = {
-            type: "NodeType",
-            name,
-            functionName,
-            inputs: {},
-            outputs: {},
-            hasSuccessPort: false,
-            hasFailurePort: false,
-            executeWhen: EXECUTION_STRATEGIES.CONJUNCTION,
-            isAsync: false,
-        };
-    }
-    label(label) {
-        this.nodeType.label = label;
-        return this;
-    }
-    description(desc) {
-        this.nodeType.description = desc;
-        return this;
-    }
-    scope(scopeName) {
-        this.nodeType.scope = scopeName;
-        return this;
-    }
-    input(name, definition) {
-        this.nodeType.inputs[name] = definition;
-        return this;
-    }
-    output(name, definition) {
-        this.nodeType.outputs[name] = definition;
-        return this;
-    }
-    successPort(enabled = true) {
-        this.nodeType.hasSuccessPort = enabled;
-        return this;
-    }
-    failurePort(enabled = true) {
-        this.nodeType.hasFailurePort = enabled;
-        return this;
-    }
-    executeWhen(when) {
-        this.nodeType.executeWhen = when;
-        return this;
-    }
-    branchingStrategy(strategy, field) {
-        this.nodeType.branchingStrategy = strategy;
-        if (field) {
-            this.nodeType.branchField = field;
-        }
-        return this;
-    }
-    defaultConfig(config) {
-        this.nodeType.defaultConfig = config;
-        return this;
-    }
-    metadata(key, value) {
-        if (!this.nodeType.metadata) {
-            this.nodeType.metadata = {};
-        }
-        this.nodeType.metadata[key] = value;
-        return this;
-    }
-    /** Build and return the final TNodeTypeAST */
-    build() {
-        return this.nodeType;
-    }
-}
-/**
- * Fluent builder for constructing TNodeInstanceAST programmatically
- *
- * NodeInstances are the actual nodes placed in a workflow, referencing a NodeType template.
- *
- * @example
- * ```typescript
- * const adder1 = new NodeInstanceBuilder('adder1', 'Add')
- *   .config({ pullExecution: true })
- *   .build();
- * ```
- */
-export class NodeInstanceBuilder {
-    instance;
-    /**
-     * Create a new node instance builder
-     * @param id - Unique instance ID within the workflow
-     * @param nodeType - Name of the NodeType this instance references
-     */
-    constructor(id, nodeType) {
-        this.instance = {
-            type: "NodeInstance",
-            id,
-            nodeType,
-        };
-    }
-    config(configData) {
-        this.instance.config = configData;
-        return this;
-    }
-    parentScope(scope) {
-        // scope format is "parentNodeId.scopeName"
-        const dotIndex = scope.indexOf('.');
-        const parentNodeName = dotIndex > 0 ? scope.substring(0, dotIndex) : scope;
-        const scopeName = dotIndex > 0 ? scope.substring(dotIndex + 1) : '';
-        this.instance.parent = { id: parentNodeName, scope: scopeName };
-        return this;
-    }
-    metadata(key, value) {
-        if (!this.instance.metadata) {
-            this.instance.metadata = {};
-        }
-        this.instance.metadata[key] = value;
-        return this;
-    }
-    /** Build and return the final TNodeInstanceAST */
-    build() {
-        return this.instance;
-    }
-}
-/**
- * Fluent builder for constructing TConnectionAST programmatically
- *
- * @example
- * ```typescript
- * const conn = new ConnectionBuilder(
- *   { node: 'Start', port: 'x' },
- *   { node: 'adder1', port: 'a' }
- * )
- *   .dataFlow(true)
- *   .build();
- * ```
- */
-export class ConnectionBuilder {
-    connection;
-    /**
-     * Create a new connection builder
-     * @param from - Source port reference
-     * @param to - Target port reference
-     */
-    constructor(from, to) {
-        this.connection = {
-            type: "Connection",
-            from,
-            to,
-        };
-    }
-    controlFlow(isControlFlow = true) {
-        if (!this.connection.metadata) {
-            this.connection.metadata = {};
-        }
-        this.connection.metadata.isControlFlow = isControlFlow;
-        return this;
-    }
-    dataFlow(isDataFlow = true) {
-        if (!this.connection.metadata) {
-            this.connection.metadata = {};
-        }
-        this.connection.metadata.isDataFlow = isDataFlow;
-        return this;
-    }
-    metadata(key, value) {
-        if (!this.connection.metadata) {
-            this.connection.metadata = {};
-        }
-        this.connection.metadata[key] = value;
-        return this;
-    }
-    /** Build and return the final TConnectionAST */
-    build() {
-        return this.connection;
-    }
-}
-/**
- * Helper function to create a PortReference
- * @param node - Node ID
- * @param port - Port name
- * @returns TPortReference object
- */
-export function portRef(node, port) {
-    return { node, port };
-}
-/**
- * Helper function to create a PortDefinition
- * @param dataType - The data type of the port
- * @param options - Optional port configuration
- * @returns TPortDefinition object
- */
-export function port(dataType, options) {
-    return {
-        dataType,
-        ...options,
-    };
-}
-/**
- * Helper function to create an ImportDeclaration
- * @param specifiers - Import specifiers (named, default, or namespace)
- * @param source - Module path to import from
- * @param importKind - Whether this is a value or type import
- * @returns TImportDeclaration object
- */
-export function importDecl(specifiers, source, importKind = "value") {
-    return {
-        type: "Import",
-        specifiers,
-        source,
-        importKind,
-    };
-}
-/**
- * Helper function to create a named import specifier
- * @param name - Name of the imported symbol
- * @param alias - Optional local alias
- * @returns TImportSpecifier for named import
- */
-export function namedImport(name, alias) {
-    return {
-        imported: name,
-        local: alias || name,
-        kind: "named",
-    };
-}
-/**
- * Helper function to create a default import specifier
- * @param name - Local name for the default import
- * @returns TImportSpecifier for default import
- */
-export function defaultImport(name) {
-    return {
-        imported: "default",
-        local: name,
-        kind: "default",
-    };
-}
-/**
- * Helper function to create a namespace import specifier
- * @param name - Local name for the namespace
- * @returns TImportSpecifier for namespace import
- */
-export function namespaceImport(name) {
-    return {
-        imported: "*",
-        local: name,
-        kind: "namespace",
-    };
-}
-/**
- * Helper function to create a WorkflowBuilder
- * @param name - Internal workflow name
- * @param functionName - Exported function name
- * @param sourceFile - Source file path
- * @returns New WorkflowBuilder instance
- */
-export function workflow(name, functionName, sourceFile) {
-    return new WorkflowBuilder(name, functionName, sourceFile);
-}
-/**
- * Helper function to create a NodeTypeBuilder
- * @param name - Node type name
- * @param functionName - Implementing function name
- * @returns New NodeTypeBuilder instance
- */
-export function nodeType(name, functionName) {
-    return new NodeTypeBuilder(name, functionName);
-}
-/**
- * Helper function to create a NodeInstanceBuilder
- * @param id - Unique instance ID
- * @param nodeTypeName - Name of the NodeType to instantiate
- * @returns New NodeInstanceBuilder instance
- */
-export function nodeInstance(id, nodeTypeName) {
-    return new NodeInstanceBuilder(id, nodeTypeName);
-}
-/**
- * Helper function to create a ConnectionBuilder
- * @param from - Source port reference
- * @param to - Target port reference
- * @returns New ConnectionBuilder instance
- */
-export function connection(from, to) {
-    return new ConnectionBuilder(from, to);
-}
-/**
- * Convenience function to create a TConnectionAST directly
- * @param fromNode - Source node ID
- * @param fromPort - Source port name
- * @param toNode - Target node ID
- * @param toPort - Target port name
- * @returns Built ConnectionAST
- */
-export function connect(fromNode, fromPort, toNode, toPort) {
-    return connection(portRef(fromNode, fromPort), portRef(toNode, toPort)).build();
-}
-//# sourceMappingURL=builder.js.map

package/dist/ast/serialization-node.js

@@ -1,30 +0,0 @@
-/**
- * Node.js-only AST file I/O functions.
- * NOT exported from /ast - use direct import if needed.
- */
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import { serializeAST, deserializeAST } from "./serialization.js";
-export async function saveAST(ast, filePath) {
-    const json = serializeAST(ast, true);
-    await fs.writeFile(filePath, json, "utf-8");
-}
-export async function loadAST(filePath) {
-    const json = await fs.readFile(filePath, "utf-8");
-    return deserializeAST(json);
-}
-export async function saveASTAlongside(ast) {
-    const sourceFile = ast.sourceFile;
-    const dir = path.dirname(sourceFile);
-    const basename = path.basename(sourceFile, path.extname(sourceFile));
-    const astFile = path.join(dir, `${basename}.ast.json`);
-    await saveAST(ast, astFile);
-    return astFile;
-}
-export async function loadASTAlongside(sourceFile) {
-    const dir = path.dirname(sourceFile);
-    const basename = path.basename(sourceFile, path.extname(sourceFile));
-    const astFile = path.join(dir, `${basename}.ast.json`);
-    return loadAST(astFile);
-}
-//# sourceMappingURL=serialization-node.js.map

package/dist/ast/serialization.js

@@ -1,134 +0,0 @@
-import { RESERVED_PORT_NAMES } from "../constants.js";
-// ============================================================================
-// BROWSER-SAFE FUNCTIONS (no Node.js dependencies)
-// ============================================================================
-/**
- * Serializes a workflow AST to a JSON string.
- *
- * @param ast - The workflow AST to serialize.
- * @param pretty - If true, formats the JSON with 2-space indentation. Defaults to true.
- * @returns The JSON string representation of the AST.
- */
-export function serializeAST(ast, pretty = true) {
-    return pretty ? JSON.stringify(ast, null, 2) : JSON.stringify(ast);
-}
-/**
- * Deserializes a JSON string into a workflow AST.
- * Validates that the root node type is "Workflow" before returning.
- *
- * @param json - The JSON string to parse.
- * @returns The parsed workflow AST.
- * @throws {Error} If the parsed object's type is not "Workflow".
- */
-export function deserializeAST(json) {
-    const ast = JSON.parse(json);
-    if (ast.type !== "Workflow") {
-        throw new Error('Invalid AST: root node must be of type "Workflow"');
-    }
-    return ast;
-}
-/**
- * Converts a workflow AST into a human-readable text summary.
- * Includes workflow metadata, imports, node types with their port counts
- * and control flow ports, and all connections.
- *
- * @param ast - The workflow AST to convert.
- * @returns A multi-line string describing the workflow structure.
- */
-export function astToString(ast) {
-    const lines = [];
-    lines.push(`Workflow: ${ast.name} (export: ${ast.functionName})`);
-    if (ast.description) {
-        lines.push(`Description: ${ast.description}`);
-    }
-    lines.push(`Source: ${ast.sourceFile}`);
-    lines.push("");
-    if (ast.imports.length > 0) {
-        lines.push("Imports:");
-        ast.imports.forEach((imp) => {
-            const specifiers = imp.specifiers.map((s) => s.local).join(", ");
-            lines.push(`  ${specifiers} from '${imp.source}'`);
-        });
-        lines.push("");
-    }
-    lines.push(`Node Types (${ast.nodeTypes.length}):`);
-    ast.nodeTypes.forEach((node) => {
-        lines.push(`  ${node.name} (${node.functionName})`);
-        const inputCount = Object.keys(node.inputs).length;
-        const outputCount = Object.keys(node.outputs).length;
-        lines.push(`    Inputs: ${inputCount}, Outputs: ${outputCount}`);
-        if (node.hasSuccessPort || node.hasFailurePort) {
-            const ports = [];
-            if (node.hasSuccessPort)
-                ports.push(RESERVED_PORT_NAMES.ON_SUCCESS);
-            if (node.hasFailurePort)
-                ports.push(RESERVED_PORT_NAMES.ON_FAILURE);
-            lines.push(`    Control flow: ${ports.join(", ")}`);
-        }
-    });
-    lines.push("");
-    lines.push(`Connections (${ast.connections.length}):`);
-    ast.connections.forEach((conn) => {
-        lines.push(`  ${conn.from.node}.${conn.from.port} → ${conn.to.node}.${conn.to.port}`);
-    });
-    return lines.join("\n");
-}
-/**
- * Validates the structural integrity of a workflow AST object.
- * Checks that the root is a "Workflow" type with required fields (name, functionName,
- * sourceFile, instances, connections, imports), and validates each node and connection
- * within the AST.
- *
- * @param ast - The unknown value to validate as a workflow AST.
- * @returns A validation result containing a `valid` boolean and an array of error messages.
- */
-export function validateASTStructure(ast) {
-    const errors = [];
-    const astObj = ast;
-    if (astObj.type !== "Workflow") {
-        errors.push('Root node must be of type "Workflow"');
-    }
-    if (!astObj.name)
-        errors.push("Workflow must have a name");
-    if (!astObj.functionName)
-        errors.push("Workflow must have a functionName");
-    if (!astObj.sourceFile)
-        errors.push("Workflow must have a sourceFile");
-    if (!Array.isArray(astObj.instances))
-        errors.push("Workflow must have instances array");
-    if (!Array.isArray(astObj.connections))
-        errors.push("Workflow must have connections array");
-    if (!Array.isArray(astObj.imports))
-        errors.push("Workflow must have imports array");
-    if (Array.isArray(astObj.instances)) {
-        astObj.instances.forEach((node, idx) => {
-            if (node.type !== "Node") {
-                errors.push(`Node ${idx} must be of type "Node"`);
-            }
-            if (!node.name) {
-                errors.push(`Node ${idx} must have a name`);
-            }
-            if (!node.functionName) {
-                errors.push(`Node ${idx} must have a functionName`);
-            }
-        });
-    }
-    if (Array.isArray(astObj.connections)) {
-        astObj.connections.forEach((conn, idx) => {
-            if (conn.type !== "Connection") {
-                errors.push(`Connection ${idx} must be of type "Connection"`);
-            }
-            if (!conn.from || !conn.from.node || !conn.from.port) {
-                errors.push(`Connection ${idx} must have valid 'from' reference`);
-            }
-            if (!conn.to || !conn.to.node || !conn.to.port) {
-                errors.push(`Connection ${idx} must have valid 'to' reference`);
-            }
-        });
-    }
-    return {
-        valid: errors.length === 0,
-        errors,
-    };
-}
-//# sourceMappingURL=serialization.js.map

package/dist/ast/types.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=types.js.map

package/dist/ast/workflow-utils.js

@@ -1,114 +0,0 @@
-import { RESERVED_PORT_NAMES, isStartNode, isExitNode, isSuccessPort, isFailurePort, } from "../constants.js";
-/**
- * Extracts the input port definitions from the workflow's Start virtual node.
- * Returns the workflow's explicit `startPorts` if defined, otherwise infers them
- * from connections originating at the Start node by matching target node input types.
- * Always includes the reserved EXECUTE control-flow port.
- *
- * @param workflow - The workflow AST to extract start ports from.
- * @returns A record mapping port names to their port definitions.
- */
-export function extractStartPorts(workflow) {
-    if (workflow.startPorts) {
-        return workflow.startPorts;
-    }
-    const startPorts = {};
-    startPorts[RESERVED_PORT_NAMES.EXECUTE] = {
-        dataType: "STEP",
-        isControlFlow: true,
-    };
-    workflow.connections
-        .filter((conn) => isStartNode(conn.from.node))
-        .forEach((conn) => {
-        const portName = conn.from.port;
-        const targetNodeType = workflow.nodeTypes.find((n) => n.name === conn.to.node);
-        if (targetNodeType?.inputs[conn.to.port]) {
-            startPorts[portName] = {
-                ...targetNodeType.inputs[conn.to.port],
-            };
-        }
-        else {
-            startPorts[portName] = {
-                dataType: "ANY",
-            };
-        }
-    });
-    return startPorts;
-}
-/**
- * Extracts the output port definitions from the workflow's Exit virtual node.
- * Returns the workflow's explicit `exitPorts` if defined, otherwise infers them
- * from connections targeting the Exit node by matching source node output types.
- *
- * @param workflow - The workflow AST to extract exit ports from.
- * @returns A record mapping port names to their port definitions.
- */
-export function extractExitPorts(workflow) {
-    if (workflow.exitPorts) {
-        return workflow.exitPorts;
-    }
-    const exitPorts = {};
-    workflow.connections
-        .filter((conn) => isExitNode(conn.to.node))
-        .forEach((conn) => {
-        const portName = conn.to.port;
-        const sourceNodeType = workflow.nodeTypes.find((n) => n.name === conn.from.node);
-        if (sourceNodeType?.outputs[conn.from.port]) {
-            exitPorts[portName] = {
-                ...sourceNodeType.outputs[conn.from.port],
-            };
-        }
-        else {
-            exitPorts[portName] = {
-                dataType: "ANY",
-            };
-        }
-    });
-    return exitPorts;
-}
-/**
- * Finds a node type definition by name within a workflow.
- *
- * @param workflow - The workflow AST to search.
- * @param nodeName - The name of the node type to find.
- * @returns The matching node type, or undefined if not found.
- */
-export function getNodeType(workflow, nodeName) {
-    return workflow.nodeTypes.find((n) => n.name === nodeName);
-}
-/**
- * Returns all connections originating from the specified node.
- *
- * @param workflow - The workflow AST to search.
- * @param nodeName - The source node name to filter by.
- * @returns An array of connections where `from.node` matches the given name.
- */
-export function getConnectionsFrom(workflow, nodeName) {
-    return workflow.connections.filter((c) => c.from.node === nodeName);
-}
-/**
- * Returns all connections targeting the specified node.
- *
- * @param workflow - The workflow AST to search.
- * @param nodeName - The target node name to filter by.
- * @returns An array of connections where `to.node` matches the given name.
- */
-export function getConnectionsTo(workflow, nodeName) {
-    return workflow.connections.filter((c) => c.to.node === nodeName);
-}
-/**
- * Determines whether a workflow contains branching control flow.
- * A workflow has branching if any node type has multiple outgoing success connections
- * or any outgoing failure connections.
- *
- * @param workflow - The workflow AST to inspect.
- * @returns True if the workflow contains branching logic.
- */
-export function hasBranching(workflow) {
-    return workflow.nodeTypes.some((nodeType) => {
-        const successConns = workflow.connections.filter((c) => c.from.node === nodeType.name && isSuccessPort(c.from.port));
-        const failureConns = workflow.connections.filter((c) => c.from.node === nodeType.name && isFailurePort(c.from.port));
-        return successConns.length > 1 || failureConns.length > 0;
-    });
-}
-//# sourceMappingURL=workflow-utils.js.map