@synergenius/flow-weaver 0.2.0

package/dist/ast/builder.d.ts

@@ -0,0 +1,210 @@
+import type { TBranchingStrategy, TConnectionAST, TDataType, TExecuteWhen, TImportDeclaration, TImportSpecifier, TNodeTypeAST, TNodeInstanceAST, TPortDefinition, TPortReference, TSerializableValue, TWorkflowAST } from "./types.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 declare class WorkflowBuilder {
+    private ast;
+    /**
+     * Create a new workflow builder
+     * @param name - Internal workflow name
+     * @param functionName - Exported function name
+     * @param sourceFile - Source file path
+     */
+    constructor(name: string, functionName: string, sourceFile: string);
+    description(desc: string): this;
+    generatedFile(path: string): this;
+    addNodeType(nodeType: TNodeTypeAST): this;
+    addNodeInstance(instance: TNodeInstanceAST): this;
+    addConnection(connection: TConnectionAST): this;
+    addScope(scopeName: string, instanceIds: string[]): this;
+    addImport(importDecl: TImportDeclaration): this;
+    metadata(key: string, value: unknown): this;
+    /** Build and return the final TWorkflowAST */
+    build(): TWorkflowAST;
+}
+/**
+ * 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 declare class NodeTypeBuilder {
+    private nodeType;
+    /**
+     * Create a new node type builder
+     * @param name - Unique node type name
+     * @param functionName - Name of the implementing function
+     */
+    constructor(name: string, functionName: string);
+    label(label: string): this;
+    description(desc: string): this;
+    scope(scopeName: string): this;
+    input(name: string, definition: TPortDefinition): this;
+    output(name: string, definition: TPortDefinition): this;
+    successPort(enabled?: boolean): this;
+    failurePort(enabled?: boolean): this;
+    executeWhen(when: TExecuteWhen): this;
+    branchingStrategy(strategy: TBranchingStrategy, field?: string): this;
+    defaultConfig(config: import("./types.js").TNodeTypeDefaultConfig): this;
+    metadata(key: string, value: unknown): this;
+    /** Build and return the final TNodeTypeAST */
+    build(): TNodeTypeAST;
+}
+/**
+ * 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 declare class NodeInstanceBuilder {
+    private 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: string, nodeType: string);
+    config(configData: import("./types.js").TNodeInstanceConfig): this;
+    parentScope(scope: string): this;
+    metadata(key: string, value: unknown): this;
+    /** Build and return the final TNodeInstanceAST */
+    build(): TNodeInstanceAST;
+}
+/**
+ * Fluent builder for constructing TConnectionAST programmatically
+ *
+ * @example
+ * ```typescript
+ * const conn = new ConnectionBuilder(
+ *   { node: 'Start', port: 'x' },
+ *   { node: 'adder1', port: 'a' }
+ * )
+ *   .dataFlow(true)
+ *   .build();
+ * ```
+ */
+export declare class ConnectionBuilder {
+    private connection;
+    /**
+     * Create a new connection builder
+     * @param from - Source port reference
+     * @param to - Target port reference
+     */
+    constructor(from: TPortReference, to: TPortReference);
+    controlFlow(isControlFlow?: boolean): this;
+    dataFlow(isDataFlow?: boolean): this;
+    metadata(key: string, value: unknown): this;
+    /** Build and return the final TConnectionAST */
+    build(): TConnectionAST;
+}
+/**
+ * Helper function to create a PortReference
+ * @param node - Node ID
+ * @param port - Port name
+ * @returns TPortReference object
+ */
+export declare function portRef(node: string, port: string): TPortReference;
+/**
+ * Helper function to create a PortDefinition
+ * @param dataType - The data type of the port
+ * @param options - Optional port configuration
+ * @returns TPortDefinition object
+ */
+export declare function port(dataType: TDataType, options?: {
+    optional?: boolean;
+    default?: TSerializableValue;
+    label?: string;
+    description?: string;
+}): TPortDefinition;
+/**
+ * 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 declare function importDecl(specifiers: TImportSpecifier[], source: string, importKind?: "value" | "type"): TImportDeclaration;
+/**
+ * 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 declare function namedImport(name: string, alias?: string): TImportSpecifier;
+/**
+ * Helper function to create a default import specifier
+ * @param name - Local name for the default import
+ * @returns TImportSpecifier for default import
+ */
+export declare function defaultImport(name: string): TImportSpecifier;
+/**
+ * Helper function to create a namespace import specifier
+ * @param name - Local name for the namespace
+ * @returns TImportSpecifier for namespace import
+ */
+export declare function namespaceImport(name: string): TImportSpecifier;
+/**
+ * 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 declare function workflow(name: string, functionName: string, sourceFile: string): WorkflowBuilder;
+/**
+ * Helper function to create a NodeTypeBuilder
+ * @param name - Node type name
+ * @param functionName - Implementing function name
+ * @returns New NodeTypeBuilder instance
+ */
+export declare function nodeType(name: string, functionName: string): NodeTypeBuilder;
+/**
+ * Helper function to create a NodeInstanceBuilder
+ * @param id - Unique instance ID
+ * @param nodeTypeName - Name of the NodeType to instantiate
+ * @returns New NodeInstanceBuilder instance
+ */
+export declare function nodeInstance(id: string, nodeTypeName: string): NodeInstanceBuilder;
+/**
+ * Helper function to create a ConnectionBuilder
+ * @param from - Source port reference
+ * @param to - Target port reference
+ * @returns New ConnectionBuilder instance
+ */
+export declare function connection(from: TPortReference, to: TPortReference): ConnectionBuilder;
+/**
+ * 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 declare function connect(fromNode: string, fromPort: string, toNode: string, toPort: string): TConnectionAST;
+//# sourceMappingURL=builder.d.ts.map

package/dist/ast/builder.js

@@ -0,0 +1,395 @@
+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/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./builder.js";
+export * from "./types.js";
+export * from "./workflow-utils.js";
+export * from "./serialization.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/ast/index.js

@@ -0,0 +1,5 @@
+export * from "./builder.js";
+export * from "./types.js";
+export * from "./workflow-utils.js";
+export * from "./serialization.js";
+//# sourceMappingURL=index.js.map

package/dist/ast/serialization-node.d.ts

@@ -0,0 +1,6 @@
+import type { TWorkflowAST } from "./types.js";
+export declare function saveAST(ast: TWorkflowAST, filePath: string): Promise<void>;
+export declare function loadAST(filePath: string): Promise<TWorkflowAST>;
+export declare function saveASTAlongside(ast: TWorkflowAST): Promise<string>;
+export declare function loadASTAlongside(sourceFile: string): Promise<TWorkflowAST>;
+//# sourceMappingURL=serialization-node.d.ts.map

package/dist/ast/serialization-node.js

@@ -0,0 +1,30 @@
+/**
+ * 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.d.ts

@@ -0,0 +1,43 @@
+import type { TWorkflowAST } from "./types.js";
+/**
+ * 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 declare function serializeAST(ast: TWorkflowAST, pretty?: boolean): string;
+/**
+ * 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 declare function deserializeAST(json: string): TWorkflowAST;
+/**
+ * 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 declare function astToString(ast: TWorkflowAST): string;
+interface ASTValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * 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 declare function validateASTStructure(ast: unknown): ASTValidationResult;
+export {};
+//# sourceMappingURL=serialization.d.ts.map