@synergenius/flow-weaver 0.2.0

package/dist/api/builder.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Builder API for fluent workflow construction
+ * Provides chainable methods for creating workflows programmatically
+ */
+import type { TWorkflowAST, TNodeTypeAST, TNodeInstanceAST, TPortDefinition, TPortReference } from "../ast/types.js";
+/**
+ * Fluent builder for constructing workflows programmatically
+ *
+ * @example
+ * ```typescript
+ * const workflow = new WorkflowBuilder('myWorkflow')
+ *   .addStartPort('input', { dataType: 'NUMBER' })
+ *   .addExitPort('output', { dataType: 'NUMBER' })
+ *   .addNodeType({
+ *     type: 'NodeType',
+ *     name: 'double',
+ *     functionName: 'double',
+ *     inputs: { x: { dataType: 'NUMBER' } },
+ *     outputs: { result: { dataType: 'NUMBER' } },
+ *     hasSuccessPort: true,
+ *     hasFailurePort: true,
+ *     executeWhen: 'CONJUNCTION'
+ *   })
+ *   .addNode('doubler', 'double')
+ *   .connect('Start.input', 'doubler.x')
+ *   .connect('doubler.result', 'Exit.output')
+ *   .build();
+ * ```
+ */
+export declare class WorkflowBuilder {
+    private ast;
+    /**
+     * Create a new workflow builder
+     *
+     * @param name - Workflow name (also used as functionName)
+     * @param sourceFile - Optional source file path
+     */
+    constructor(name: string, sourceFile?: string);
+    /**
+     * Add a Start port to the workflow
+     *
+     * @param name - Port name
+     * @param definition - Port definition
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.addStartPort('userId', { dataType: 'STRING' });
+     * ```
+     */
+    addStartPort(name: string, definition: TPortDefinition): this;
+    /**
+     * Add an Exit port to the workflow
+     *
+     * @param name - Port name
+     * @param definition - Port definition
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.addExitPort('result', { dataType: 'NUMBER' });
+     * ```
+     */
+    addExitPort(name: string, definition: TPortDefinition): this;
+    /**
+     * Add a node type definition
+     *
+     * @param nodeType - Complete node type definition
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.addNodeType({
+     *   type: 'NodeType',
+     *   name: 'processor',
+     *   functionName: 'process',
+     *   inputs: { data: { dataType: 'ANY' } },
+     *   outputs: { result: { dataType: 'ANY' } },
+     *   hasSuccessPort: true,
+     *   hasFailurePort: true,
+     *   executeWhen: 'CONJUNCTION'
+     * });
+     * ```
+     */
+    addNodeType(nodeType: TNodeTypeAST): this;
+    /**
+     * Add a node instance
+     *
+     * @param id - Node instance ID
+     * @param nodeType - Node type (functionName)
+     * @param config - Optional node configuration
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.addNode('processor1', 'process');
+     * builder.addNode('processor2', 'process', { x: 100, y: 200, label: 'Main' });
+     * ```
+     */
+    addNode(id: string, nodeType: string, config?: TNodeInstanceAST["config"]): this;
+    /**
+     * Connect two ports
+     *
+     * Supports multiple formats:
+     * - String format: "node1.port1", "node2.port2"
+     * - Object format: { node: "node1", port: "port1" }
+     *
+     * @param from - Source port reference
+     * @param to - Target port reference
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.connect('Start.input', 'processor1.data');
+     * builder.connect({ node: 'processor1', port: 'result' }, 'Exit.output');
+     * ```
+     */
+    connect(from: string | TPortReference, to: string | TPortReference): this;
+    /**
+     * Create a scope and add nodes to it
+     *
+     * @param scopeName - Name of the scope
+     * @param nodeIds - Array of node IDs to include
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.createScope('mainLoop', ['processor1', 'processor2']);
+     * ```
+     */
+    createScope(scopeName: string, nodeIds: string[]): this;
+    /**
+     * Set workflow description
+     *
+     * @param description - Workflow description
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.setDescription('Processes user data and generates reports');
+     * ```
+     */
+    setDescription(description: string): this;
+    /**
+     * Validate the current workflow state
+     *
+     * @returns Validation result
+     *
+     * @example
+     * ```typescript
+     * const validation = builder.validate();
+     * if (!validation.valid) {
+     *   console.error('Errors:', validation.errors);
+     * }
+     * ```
+     */
+    validate(): import("./validate.js").ValidationResult;
+    /**
+     * Build and return the final workflow
+     *
+     * Validates the workflow before returning. Throws if invalid.
+     *
+     * @returns Complete workflow AST
+     * @throws {Error} If workflow validation fails
+     *
+     * @example
+     * ```typescript
+     * const workflow = builder.build();
+     * ```
+     */
+    build(): TWorkflowAST;
+    /**
+     * Get the current workflow state without validation
+     *
+     * Use this to inspect the workflow during construction.
+     *
+     * @returns Current workflow AST
+     *
+     * @example
+     * ```typescript
+     * const current = builder.getWorkflow();
+     * console.log(`Nodes: ${current.instances.length}`);
+     * ```
+     */
+    getWorkflow(): TWorkflowAST;
+}
+/**
+ * Create a new workflow builder
+ *
+ * Convenience function for creating a builder instance.
+ *
+ * @param name - Workflow name
+ * @param sourceFile - Optional source file path
+ * @returns New WorkflowBuilder instance
+ *
+ * @example
+ * ```typescript
+ * const workflow = createWorkflow('myWorkflow')
+ *   .addStartPort('input', { dataType: 'NUMBER' })
+ *   .addExitPort('output', { dataType: 'NUMBER' })
+ *   .build();
+ * ```
+ */
+export declare function createWorkflow(name: string, sourceFile?: string): WorkflowBuilder;
+/**
+ * Create a builder from an existing workflow AST
+ *
+ * Allows modifying existing workflows using the builder API.
+ *
+ * @param ast - Existing workflow AST
+ * @returns WorkflowBuilder initialized with the AST
+ *
+ * @example
+ * ```typescript
+ * const existingWorkflow = parseWorkflow(source);
+ * const modified = fromAST(existingWorkflow)
+ *   .addNode('newNode', 'process')
+ *   .connect('Start.input', 'newNode.data')
+ *   .build();
+ * ```
+ */
+export declare function fromAST(ast: TWorkflowAST): WorkflowBuilder;
+//# sourceMappingURL=builder.d.ts.map

package/dist/api/builder.js

@@ -0,0 +1,345 @@
+/**
+ * Builder API for fluent workflow construction
+ * Provides chainable methods for creating workflows programmatically
+ */
+import { produce } from "immer";
+import { validateWorkflow } from "./validate.js";
+import { validatePortReference } from "./helpers.js";
+/**
+ * Fluent builder for constructing workflows programmatically
+ *
+ * @example
+ * ```typescript
+ * const workflow = new WorkflowBuilder('myWorkflow')
+ *   .addStartPort('input', { dataType: 'NUMBER' })
+ *   .addExitPort('output', { dataType: 'NUMBER' })
+ *   .addNodeType({
+ *     type: 'NodeType',
+ *     name: 'double',
+ *     functionName: 'double',
+ *     inputs: { x: { dataType: 'NUMBER' } },
+ *     outputs: { result: { dataType: 'NUMBER' } },
+ *     hasSuccessPort: true,
+ *     hasFailurePort: true,
+ *     executeWhen: 'CONJUNCTION'
+ *   })
+ *   .addNode('doubler', 'double')
+ *   .connect('Start.input', 'doubler.x')
+ *   .connect('doubler.result', 'Exit.output')
+ *   .build();
+ * ```
+ */
+export class WorkflowBuilder {
+    ast;
+    /**
+     * Create a new workflow builder
+     *
+     * @param name - Workflow name (also used as functionName)
+     * @param sourceFile - Optional source file path
+     */
+    constructor(name, sourceFile = `${name}.ts`) {
+        this.ast = {
+            type: "Workflow",
+            name,
+            functionName: name,
+            sourceFile,
+            nodeTypes: [],
+            instances: [],
+            connections: [],
+            scopes: {},
+            startPorts: {},
+            exitPorts: {},
+            imports: [],
+        };
+    }
+    /**
+     * Add a Start port to the workflow
+     *
+     * @param name - Port name
+     * @param definition - Port definition
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.addStartPort('userId', { dataType: 'STRING' });
+     * ```
+     */
+    addStartPort(name, definition) {
+        // Use simplified type to avoid excessive type instantiation
+        this.ast = produce(this.ast, (draft) => {
+            draft.startPorts[name] = definition;
+        });
+        return this;
+    }
+    /**
+     * Add an Exit port to the workflow
+     *
+     * @param name - Port name
+     * @param definition - Port definition
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.addExitPort('result', { dataType: 'NUMBER' });
+     * ```
+     */
+    addExitPort(name, definition) {
+        // Use simplified type to avoid excessive type instantiation
+        this.ast = produce(this.ast, (draft) => {
+            draft.exitPorts[name] = definition;
+        });
+        return this;
+    }
+    /**
+     * Add a node type definition
+     *
+     * @param nodeType - Complete node type definition
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.addNodeType({
+     *   type: 'NodeType',
+     *   name: 'processor',
+     *   functionName: 'process',
+     *   inputs: { data: { dataType: 'ANY' } },
+     *   outputs: { result: { dataType: 'ANY' } },
+     *   hasSuccessPort: true,
+     *   hasFailurePort: true,
+     *   executeWhen: 'CONJUNCTION'
+     * });
+     * ```
+     */
+    addNodeType(nodeType) {
+        // Validate before produce to avoid type instantiation issues
+        if (this.ast.nodeTypes.some((nt) => nt.name === nodeType.name)) {
+            throw new Error(`Node type "${nodeType.name}" already exists`);
+        }
+        // Use simplified type to avoid excessive type instantiation
+        this.ast = produce(this.ast, (draft) => {
+            draft.nodeTypes.push(nodeType);
+        });
+        return this;
+    }
+    /**
+     * Add a node instance
+     *
+     * @param id - Node instance ID
+     * @param nodeType - Node type (functionName)
+     * @param config - Optional node configuration
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.addNode('processor1', 'process');
+     * builder.addNode('processor2', 'process', { x: 100, y: 200, label: 'Main' });
+     * ```
+     */
+    addNode(id, nodeType, config) {
+        // Validate before produce to avoid type instantiation issues
+        if (this.ast.instances.some((n) => n.id === id)) {
+            throw new Error(`Node "${id}" already exists`);
+        }
+        if (!this.ast.nodeTypes.some((nt) => nt.name === nodeType || nt.functionName === nodeType)) {
+            throw new Error(`Node type "${nodeType}" not found. Available types: ${this.ast.nodeTypes.map((nt) => nt.name || nt.functionName).join(", ")}`);
+        }
+        const node = {
+            type: "NodeInstance",
+            id,
+            nodeType,
+        };
+        if (config) {
+            node.config = config;
+        }
+        // Use simplified type to avoid excessive type instantiation
+        this.ast = produce(this.ast, (draft) => {
+            draft.instances.push(node);
+        });
+        return this;
+    }
+    /**
+     * Connect two ports
+     *
+     * Supports multiple formats:
+     * - String format: "node1.port1", "node2.port2"
+     * - Object format: { node: "node1", port: "port1" }
+     *
+     * @param from - Source port reference
+     * @param to - Target port reference
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.connect('Start.input', 'processor1.data');
+     * builder.connect({ node: 'processor1', port: 'result' }, 'Exit.output');
+     * ```
+     */
+    connect(from, to) {
+        const fromRef = validatePortReference(from);
+        const toRef = validatePortReference(to);
+        const connection = {
+            type: "Connection",
+            from: fromRef,
+            to: toRef,
+        };
+        // Use simplified type to avoid excessive type instantiation
+        this.ast = produce(this.ast, (draft) => {
+            draft.connections.push(connection);
+        });
+        return this;
+    }
+    /**
+     * Create a scope and add nodes to it
+     *
+     * @param scopeName - Name of the scope
+     * @param nodeIds - Array of node IDs to include
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.createScope('mainLoop', ['processor1', 'processor2']);
+     * ```
+     */
+    createScope(scopeName, nodeIds) {
+        // Validate before produce
+        if (this.ast.scopes && this.ast.scopes[scopeName]) {
+            throw new Error(`Scope "${scopeName}" already exists`);
+        }
+        // scopeName format is "parentNodeId.scopeName"
+        const dotIndex = scopeName.indexOf('.');
+        const parentNodeName = dotIndex > 0 ? scopeName.substring(0, dotIndex) : scopeName;
+        const scope = dotIndex > 0 ? scopeName.substring(dotIndex + 1) : '';
+        // Use simplified type to avoid excessive type instantiation
+        this.ast = produce(this.ast, (draft) => {
+            if (!draft.scopes) {
+                draft.scopes = {};
+            }
+            draft.scopes[scopeName] = nodeIds;
+            nodeIds.forEach((nodeId) => {
+                const node = draft.instances.find((n) => n.id === nodeId);
+                if (node) {
+                    node.parent = { id: parentNodeName, scope };
+                }
+            });
+        });
+        return this;
+    }
+    /**
+     * Set workflow description
+     *
+     * @param description - Workflow description
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.setDescription('Processes user data and generates reports');
+     * ```
+     */
+    setDescription(description) {
+        // Use simplified type to avoid excessive type instantiation
+        this.ast = produce(this.ast, (draft) => {
+            draft.description = description;
+        });
+        return this;
+    }
+    /**
+     * Validate the current workflow state
+     *
+     * @returns Validation result
+     *
+     * @example
+     * ```typescript
+     * const validation = builder.validate();
+     * if (!validation.valid) {
+     *   console.error('Errors:', validation.errors);
+     * }
+     * ```
+     */
+    validate() {
+        return validateWorkflow(this.ast);
+    }
+    /**
+     * Build and return the final workflow
+     *
+     * Validates the workflow before returning. Throws if invalid.
+     *
+     * @returns Complete workflow AST
+     * @throws {Error} If workflow validation fails
+     *
+     * @example
+     * ```typescript
+     * const workflow = builder.build();
+     * ```
+     */
+    build() {
+        const validation = this.validate();
+        if (!validation.valid) {
+            const errorDetails = validation.errors
+                .slice(0, 3)
+                .map((e) => `  - ${e.message}`)
+                .join("\n");
+            throw new Error(`Cannot build workflow: validation failed\n${errorDetails}${validation.errors.length > 3 ? `\n  ... and ${validation.errors.length - 3} more errors` : ""}`);
+        }
+        return this.ast;
+    }
+    /**
+     * Get the current workflow state without validation
+     *
+     * Use this to inspect the workflow during construction.
+     *
+     * @returns Current workflow AST
+     *
+     * @example
+     * ```typescript
+     * const current = builder.getWorkflow();
+     * console.log(`Nodes: ${current.instances.length}`);
+     * ```
+     */
+    getWorkflow() {
+        return this.ast;
+    }
+}
+/**
+ * Create a new workflow builder
+ *
+ * Convenience function for creating a builder instance.
+ *
+ * @param name - Workflow name
+ * @param sourceFile - Optional source file path
+ * @returns New WorkflowBuilder instance
+ *
+ * @example
+ * ```typescript
+ * const workflow = createWorkflow('myWorkflow')
+ *   .addStartPort('input', { dataType: 'NUMBER' })
+ *   .addExitPort('output', { dataType: 'NUMBER' })
+ *   .build();
+ * ```
+ */
+export function createWorkflow(name, sourceFile) {
+    return new WorkflowBuilder(name, sourceFile);
+}
+/**
+ * Create a builder from an existing workflow AST
+ *
+ * Allows modifying existing workflows using the builder API.
+ *
+ * @param ast - Existing workflow AST
+ * @returns WorkflowBuilder initialized with the AST
+ *
+ * @example
+ * ```typescript
+ * const existingWorkflow = parseWorkflow(source);
+ * const modified = fromAST(existingWorkflow)
+ *   .addNode('newNode', 'process')
+ *   .connect('Start.input', 'newNode.data')
+ *   .build();
+ * ```
+ */
+export function fromAST(ast) {
+    const builder = new WorkflowBuilder(ast.name, ast.sourceFile);
+    // Access private field through bracket notation to avoid exposing internal state
+    builder.ast = ast;
+    return builder;
+}
+//# sourceMappingURL=builder.js.map

package/dist/api/compile.d.ts

@@ -0,0 +1,92 @@
+import type { TCompileResult as ASTCompileResult } from '../ast/types.js';
+import { type GenerateOptions } from './generate.js';
+import { type InPlaceGenerateOptions } from './generate-in-place.js';
+import { type ParseOptions } from './parse.js';
+/**
+ * Options for compiling a workflow file
+ */
+export interface CompileOptions {
+    /** Options for parsing the source file */
+    parse?: ParseOptions;
+    /** Options for code generation */
+    generate?: GenerateOptions & InPlaceGenerateOptions;
+    /**
+     * Compile in-place (modifies source file, default: true)
+     * When false, generates to a separate file
+     */
+    inPlace?: boolean;
+    /** Custom output file path (only used when inPlace=false) */
+    outputFile?: string;
+    /** Whether to write the compiled code to disk (default: true) */
+    write?: boolean;
+    /** Whether to save AST alongside the generated file (default: false) */
+    saveAST?: boolean;
+}
+/**
+ * Result of workflow compilation
+ */
+export type CompileResult = ASTCompileResult;
+/**
+ * Compile a workflow file from TypeScript annotations to executable code.
+ *
+ * By default, compiles in-place (updates the source file with generated code).
+ * Set inPlace=false to generate to a separate file.
+ *
+ * @param filePath - Path to the workflow file
+ * @param options - Compilation options
+ * @returns CompileResult with code, AST, and metadata
+ *
+ * @example
+ * ```typescript
+ * // Compile in-place (default)
+ * const result = await compileWorkflow('./workflow.ts');
+ *
+ * // Generate to separate file for production
+ * const result = await compileWorkflow('./workflow.ts', {
+ *   inPlace: false,
+ *   outputFile: './dist/workflow.ts',
+ *   generate: { production: true }
+ * });
+ * ```
+ *
+ * @throws {Error} If parsing fails or workflow contains errors
+ */
+export declare function compileWorkflow(filePath: string, options?: CompileOptions): Promise<CompileResult>;
+/**
+ * Compile multiple workflow files in parallel
+ *
+ * @param filePaths - Array of workflow file paths to compile
+ * @param options - Compilation options applied to all files
+ * @returns Array of CompileResults for each file
+ *
+ * @example
+ * ```typescript
+ * const results = await compileWorkflows([
+ *   './workflow-1.ts',
+ *   './workflow-2.ts'
+ * ]);
+ * ```
+ */
+export declare function compileWorkflows(filePaths: string[], options?: CompileOptions): Promise<CompileResult[]>;
+/**
+ * Compile all workflow files matching a glob pattern
+ *
+ * Uses the glob library to find matching files and compiles them in parallel.
+ *
+ * @param pattern - Glob pattern (e.g., "src/**\/*.ts")
+ * @param options - Compilation options applied to all files
+ * @returns Array of CompileResults for each matched file
+ *
+ * @example
+ * ```typescript
+ * // Compile all workflow files in src directory
+ * const results = await compilePattern('src/**\/*.ts');
+ *
+ * // Compile with custom options
+ * const results = await compilePattern('workflows/**\/*.ts', {
+ *   generate: { production: true }
+ * });
+ * ```
+ */
+export declare function compilePattern(pattern: string, options?: CompileOptions): Promise<CompileResult[]>;
+//# sourceMappingURL=compile.d.ts.map