@synergenius/flow-weaver 0.2.0

package/dist/ast/types.js

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

package/dist/ast/workflow-utils.d.ts

@@ -0,0 +1,54 @@
+import type { TPortDefinition, TWorkflowAST } from "./types.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 declare function extractStartPorts(workflow: TWorkflowAST): Record<string, TPortDefinition>;
+/**
+ * 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 declare function extractExitPorts(workflow: TWorkflowAST): Record<string, TPortDefinition>;
+/**
+ * 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 declare function getNodeType(workflow: TWorkflowAST, nodeName: string): import("./types.js").TNodeTypeAST | undefined;
+/**
+ * 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 declare function getConnectionsFrom(workflow: TWorkflowAST, nodeName: string): import("./types.js").TConnectionAST[];
+/**
+ * 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 declare function getConnectionsTo(workflow: TWorkflowAST, nodeName: string): import("./types.js").TConnectionAST[];
+/**
+ * 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 declare function hasBranching(workflow: TWorkflowAST): boolean;
+//# sourceMappingURL=workflow-utils.d.ts.map

package/dist/ast/workflow-utils.js

@@ -0,0 +1,114 @@
+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

package/dist/body-generator.d.ts

@@ -0,0 +1,31 @@
+import type { TNodeTypeAST, TWorkflowAST } from "./ast/index.js";
+/**
+ * Generates executable function body code from workflow ASTs.
+ * Delegates to the unified control-flow generator for code emission.
+ */
+export declare class BodyGenerator {
+    /**
+     * Generates a workflow function body that uses an execution context for
+     * tracing, error handling, and runtime state management.
+     *
+     * @param workflow - The workflow AST defining the graph structure.
+     * @param nodeTypes - The node type definitions referenced by the workflow.
+     * @param isAsync - Whether to generate async code. Defaults to true.
+     * @param production - If true, omits debug event emissions. Defaults to false.
+     * @param bundleMode - If true, generates code suitable for bundled deployment. Defaults to false.
+     * @returns The generated function body as a string.
+     */
+    generateWithExecutionContext(workflow: TWorkflowAST, nodeTypes: TNodeTypeAST[], isAsync?: boolean, production?: boolean, bundleMode?: boolean): string;
+    /**
+     * Generates a workflow function body using default settings (async, non-production, non-bundled).
+     * Convenience method that wraps {@link generateWithExecutionContext}.
+     *
+     * @param workflow - The workflow AST defining the graph structure.
+     * @param nodeTypes - The node type definitions referenced by the workflow.
+     * @returns The generated function body as a string.
+     */
+    generateDirectCode(workflow: TWorkflowAST, nodeTypes: TNodeTypeAST[]): string;
+}
+/** Pre-instantiated singleton of {@link BodyGenerator} for convenient use. */
+export declare const bodyGenerator: BodyGenerator;
+//# sourceMappingURL=body-generator.d.ts.map

package/dist/body-generator.js

@@ -0,0 +1,35 @@
+import { generateControlFlowWithExecutionContext } from "./generator/unified.js";
+/**
+ * Generates executable function body code from workflow ASTs.
+ * Delegates to the unified control-flow generator for code emission.
+ */
+export class BodyGenerator {
+    /**
+     * Generates a workflow function body that uses an execution context for
+     * tracing, error handling, and runtime state management.
+     *
+     * @param workflow - The workflow AST defining the graph structure.
+     * @param nodeTypes - The node type definitions referenced by the workflow.
+     * @param isAsync - Whether to generate async code. Defaults to true.
+     * @param production - If true, omits debug event emissions. Defaults to false.
+     * @param bundleMode - If true, generates code suitable for bundled deployment. Defaults to false.
+     * @returns The generated function body as a string.
+     */
+    generateWithExecutionContext(workflow, nodeTypes, isAsync = true, production = false, bundleMode = false) {
+        return generateControlFlowWithExecutionContext(workflow, nodeTypes, isAsync, production, bundleMode);
+    }
+    /**
+     * Generates a workflow function body using default settings (async, non-production, non-bundled).
+     * Convenience method that wraps {@link generateWithExecutionContext}.
+     *
+     * @param workflow - The workflow AST defining the graph structure.
+     * @param nodeTypes - The node type definitions referenced by the workflow.
+     * @returns The generated function body as a string.
+     */
+    generateDirectCode(workflow, nodeTypes) {
+        return generateControlFlowWithExecutionContext(workflow, nodeTypes, true, false, false);
+    }
+}
+/** Pre-instantiated singleton of {@link BodyGenerator} for convenient use. */
+export const bodyGenerator = new BodyGenerator();
+//# sourceMappingURL=body-generator.js.map

package/dist/built-in-nodes/delay.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @flowWeaver nodeType
+ * @input duration - Duration to sleep (e.g. "30s", "5m", "1h", "2d")
+ * @output elapsed - Always true after sleep completes
+ */
+export declare function delay(execute: boolean, duration: string): Promise<{
+    onSuccess: boolean;
+    onFailure: boolean;
+    elapsed: boolean;
+}>;
+//# sourceMappingURL=delay.d.ts.map

package/dist/built-in-nodes/delay.js

@@ -0,0 +1,29 @@
+import { getMockConfig } from './mock-types.js';
+/**
+ * @flowWeaver nodeType
+ * @input duration - Duration to sleep (e.g. "30s", "5m", "1h", "2d")
+ * @output elapsed - Always true after sleep completes
+ */
+export async function delay(execute, duration) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, elapsed: false };
+    const mocks = getMockConfig();
+    if (mocks?.fast) {
+        // Fast mode: skip real sleep, keep async behavior with 1ms
+        await new Promise((resolve) => setTimeout(resolve, 1));
+    }
+    else {
+        const ms = parseDuration(duration);
+        await new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    return { onSuccess: true, onFailure: false, elapsed: true };
+}
+function parseDuration(duration) {
+    const match = duration.match(/^(\d+)(ms|s|m|h|d)$/);
+    if (!match)
+        return 0;
+    const [, value, unit] = match;
+    const multipliers = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
+    return parseInt(value) * (multipliers[unit] || 0);
+}
+//# sourceMappingURL=delay.js.map

package/dist/built-in-nodes/index.d.ts

@@ -0,0 +1,5 @@
+export { delay } from './delay.js';
+export { waitForEvent } from './wait-for-event.js';
+export { invokeWorkflow } from './invoke-workflow.js';
+export type { FwMockConfig } from './mock-types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/built-in-nodes/index.js

@@ -0,0 +1,4 @@
+export { delay } from './delay.js';
+export { waitForEvent } from './wait-for-event.js';
+export { invokeWorkflow } from './invoke-workflow.js';
+//# sourceMappingURL=index.js.map

package/dist/built-in-nodes/invoke-workflow.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @flowWeaver nodeType
+ * @input functionId - Inngest function ID (e.g. "my-service/sub-workflow")
+ * @input payload - Data to pass as event.data to the invoked function
+ * @input [timeout] - Max wait time (e.g. "1h")
+ * @output result - Return value from the invoked function
+ */
+export declare function invokeWorkflow(execute: boolean, functionId: string, payload: object, timeout?: string): Promise<{
+    onSuccess: boolean;
+    onFailure: boolean;
+    result: object;
+}>;
+//# sourceMappingURL=invoke-workflow.d.ts.map

package/dist/built-in-nodes/invoke-workflow.js

@@ -0,0 +1,25 @@
+import { getMockConfig } from './mock-types.js';
+/**
+ * @flowWeaver nodeType
+ * @input functionId - Inngest function ID (e.g. "my-service/sub-workflow")
+ * @input payload - Data to pass as event.data to the invoked function
+ * @input [timeout] - Max wait time (e.g. "1h")
+ * @output result - Return value from the invoked function
+ */
+export async function invokeWorkflow(execute, functionId, payload, timeout) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, result: {} };
+    const mocks = getMockConfig();
+    if (mocks) {
+        // Mock mode active — look up result by functionId
+        const mockResult = mocks.invocations?.[functionId];
+        if (mockResult !== undefined) {
+            return { onSuccess: true, onFailure: false, result: mockResult };
+        }
+        // No mock data for this functionId — simulate failure
+        return { onSuccess: false, onFailure: true, result: {} };
+    }
+    // No mocks: original no-op behavior (always succeeds)
+    return { onSuccess: true, onFailure: false, result: {} };
+}
+//# sourceMappingURL=invoke-workflow.js.map

package/dist/built-in-nodes/mock-types.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Type definitions for the mock configuration used during local testing.
+ * When present on globalThis.__fw_mocks__, built-in nodes use mock data
+ * instead of their default no-op/sleep behavior.
+ */
+export interface FwMockConfig {
+    /** Mock event data keyed by event name. Used by waitForEvent. */
+    events?: Record<string, object>;
+    /** Mock invocation results keyed by functionId. Used by invokeWorkflow. */
+    invocations?: Record<string, object>;
+    /** When true, delay nodes skip the real sleep (1ms instead of full duration). */
+    fast?: boolean;
+}
+/**
+ * Read the mock config from globalThis, returning undefined if not set.
+ */
+export declare function getMockConfig(): FwMockConfig | undefined;
+//# sourceMappingURL=mock-types.d.ts.map

package/dist/built-in-nodes/mock-types.js

@@ -0,0 +1,12 @@
+/**
+ * Type definitions for the mock configuration used during local testing.
+ * When present on globalThis.__fw_mocks__, built-in nodes use mock data
+ * instead of their default no-op/sleep behavior.
+ */
+/**
+ * Read the mock config from globalThis, returning undefined if not set.
+ */
+export function getMockConfig() {
+    return globalThis.__fw_mocks__;
+}
+//# sourceMappingURL=mock-types.js.map

package/dist/built-in-nodes/wait-for-event.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @flowWeaver nodeType
+ * @input eventName - Event name to wait for (e.g. "app/approval.received")
+ * @input [match] - Field to match between trigger and waited event (e.g. "data.requestId")
+ * @input [timeout] - Max wait time (e.g. "24h", "7d"). Empty = no timeout
+ * @output eventData - The received event's data payload
+ */
+export declare function waitForEvent(execute: boolean, eventName: string, match?: string, timeout?: string): Promise<{
+    onSuccess: boolean;
+    onFailure: boolean;
+    eventData: object;
+}>;
+//# sourceMappingURL=wait-for-event.d.ts.map

package/dist/built-in-nodes/wait-for-event.js

@@ -0,0 +1,25 @@
+import { getMockConfig } from './mock-types.js';
+/**
+ * @flowWeaver nodeType
+ * @input eventName - Event name to wait for (e.g. "app/approval.received")
+ * @input [match] - Field to match between trigger and waited event (e.g. "data.requestId")
+ * @input [timeout] - Max wait time (e.g. "24h", "7d"). Empty = no timeout
+ * @output eventData - The received event's data payload
+ */
+export async function waitForEvent(execute, eventName, match, timeout) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, eventData: {} };
+    const mocks = getMockConfig();
+    if (mocks) {
+        // Mock mode active — look up event data by name
+        const mockData = mocks.events?.[eventName];
+        if (mockData !== undefined) {
+            return { onSuccess: true, onFailure: false, eventData: mockData };
+        }
+        // No mock data for this event — simulate timeout
+        return { onSuccess: false, onFailure: true, eventData: {} };
+    }
+    // No mocks: original no-op behavior (always succeeds)
+    return { onSuccess: true, onFailure: false, eventData: {} };
+}
+//# sourceMappingURL=wait-for-event.js.map

package/dist/chevrotain-parser/connect-parser.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @module chevrotain-parser/connect-parser
+ *
+ * Parser for @connect declarations using Chevrotain.
+ */
+export interface PortReference {
+    nodeId: string;
+    portName: string;
+    scope?: string;
+}
+export interface ConnectParseResult {
+    source: PortReference;
+    target: PortReference;
+}
+/**
+ * Parse a @connect line and return structured result.
+ * Returns null if the line is not a connect declaration.
+ */
+export declare function parseConnectLine(input: string, warnings: string[]): ConnectParseResult | null;
+/**
+ * Get serialized grammar for documentation/diagram generation.
+ */
+export declare function getConnectGrammar(): import("chevrotain").ISerializedGast[];
+//# sourceMappingURL=connect-parser.d.ts.map

package/dist/chevrotain-parser/connect-parser.js

@@ -0,0 +1,98 @@
+/**
+ * @module chevrotain-parser/connect-parser
+ *
+ * Parser for @connect declarations using Chevrotain.
+ */
+import { CstParser } from 'chevrotain';
+import { JSDocLexer, ConnectTag, Identifier, Arrow, Dot, Colon, allTokens } from './tokens.js';
+// =============================================================================
+// Parser Definition
+// =============================================================================
+class ConnectParser extends CstParser {
+    constructor() {
+        super(allTokens);
+        this.performSelfAnalysis();
+    }
+    // Entry rule for connect line
+    connectLine = this.RULE('connectLine', () => {
+        this.CONSUME(ConnectTag);
+        this.SUBRULE(this.portRef, { LABEL: 'sourceRef' });
+        this.CONSUME(Arrow);
+        this.SUBRULE2(this.portRef, { LABEL: 'targetRef' });
+    });
+    // node.port or node.port:scope
+    portRef = this.RULE('portRef', () => {
+        this.CONSUME(Identifier, { LABEL: 'nodeId' });
+        this.CONSUME(Dot);
+        this.CONSUME2(Identifier, { LABEL: 'portName' });
+        this.OPTION(() => {
+            this.CONSUME(Colon);
+            this.CONSUME3(Identifier, { LABEL: 'scopeName' });
+        });
+    });
+}
+// =============================================================================
+// Parser Instance (singleton)
+// =============================================================================
+const parserInstance = new ConnectParser();
+// =============================================================================
+// CST Visitor
+// =============================================================================
+const BaseVisitor = parserInstance.getBaseCstVisitorConstructor();
+class ConnectVisitor extends BaseVisitor {
+    constructor() {
+        super();
+        this.validateVisitor();
+    }
+    connectLine(ctx) {
+        const source = this.visit(ctx.sourceRef);
+        const target = this.visit(ctx.targetRef);
+        return { source, target };
+    }
+    portRef(ctx) {
+        const nodeId = ctx.nodeId[0].image;
+        const portName = ctx.portName[0].image;
+        const scope = ctx.scopeName?.[0]?.image;
+        return { nodeId, portName, scope };
+    }
+}
+const visitorInstance = new ConnectVisitor();
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Parse a @connect line and return structured result.
+ * Returns null if the line is not a connect declaration.
+ */
+export function parseConnectLine(input, warnings) {
+    const lexResult = JSDocLexer.tokenize(input);
+    if (lexResult.errors.length > 0) {
+        return null;
+    }
+    // Check if starts with @connect
+    if (lexResult.tokens.length === 0) {
+        return null;
+    }
+    const firstToken = lexResult.tokens[0];
+    if (firstToken.tokenType !== ConnectTag) {
+        return null;
+    }
+    parserInstance.input = lexResult.tokens;
+    const cst = parserInstance.connectLine();
+    if (parserInstance.errors.length > 0) {
+        const firstError = parserInstance.errors[0];
+        const truncatedInput = input.length > 60 ? input.substring(0, 60) + '...' : input;
+        warnings.push(`Failed to parse connect line: "${truncatedInput}"\n` +
+            `  Error: ${firstError.message}\n` +
+            `  Expected format: @connect sourceNode.port -> targetNode.port`);
+        return null;
+    }
+    return visitorInstance.visit(cst);
+}
+/**
+ * Get serialized grammar for documentation/diagram generation.
+ */
+export function getConnectGrammar() {
+    return parserInstance.getSerializedGastProductions();
+}
+//# sourceMappingURL=connect-parser.js.map

package/dist/chevrotain-parser/grammar-diagrams.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @module chevrotain-parser/grammar-diagrams
+ *
+ * Generates railroad diagrams for all JSDoc grammars using Chevrotain.
+ */
+import { ISerializedGast } from 'chevrotain';
+export declare function serializedToEBNF(productions: ISerializedGast[]): string;
+export interface GrammarCollection {
+    port: ISerializedGast[];
+    node: ISerializedGast[];
+    connect: ISerializedGast[];
+    position: ISerializedGast[];
+    scope: ISerializedGast[];
+    path: ISerializedGast[];
+}
+/**
+ * Get all grammar productions as serialized GAST (Grammar AST).
+ */
+export declare function getAllGrammars(): GrammarCollection;
+/**
+ * Generate standalone HTML with railroad diagrams for all grammars.
+ * Uses Chevrotain's createSyntaxDiagramsCode which returns a complete HTML page.
+ */
+export declare function generateGrammarDiagrams(): string;
+/**
+ * Generate diagram HTML for a specific grammar.
+ */
+export declare function generateGrammarDiagramFor(grammarName: keyof GrammarCollection): string;
+//# sourceMappingURL=grammar-diagrams.d.ts.map