@flowdrop/flowdrop 1.0.0

package/dist/utils/connections.js

@@ -0,0 +1,414 @@
+/**
+ * Connection validation utilities for FlowDrop
+ */
+/**
+ * Loopback port name constant
+ * This is the standard input port name used for loop iteration triggers
+ */
+const LOOPBACK_PORT_NAME = 'loop_back';
+/**
+ * Determines if an edge is a loopback edge.
+ * Loopback edges target the special `loop_back` input port on ForEach nodes.
+ * These edges are used to trigger the next iteration in a loop construct.
+ *
+ * @param edge - The edge to check
+ * @returns True if the edge is a loopback edge
+ *
+ * @example
+ * ```typescript
+ * const edge = { targetHandle: "foreach.1-input-loop_back", ... };
+ * const isLoop = isLoopbackEdge(edge); // true
+ * ```
+ */
+export function isLoopbackEdge(edge) {
+    const targetHandle = edge.targetHandle ?? '';
+    return targetHandle.includes(`-input-${LOOPBACK_PORT_NAME}`);
+}
+/**
+ * Checks if a cycle consists entirely of loopback edges.
+ * A valid loopback cycle only contains edges that target loop_back ports.
+ *
+ * @param cycleEdges - Array of edges that form a cycle
+ * @returns True if all edges in the cycle are loopback edges
+ */
+export function isValidLoopbackCycle(cycleEdges) {
+    return cycleEdges.every((edge) => isLoopbackEdge(edge));
+}
+/**
+ * Configurable port compatibility checker
+ */
+export class PortCompatibilityChecker {
+    portConfig;
+    compatibilityMap;
+    constructor(portConfig) {
+        this.portConfig = portConfig;
+        this.compatibilityMap = new Map();
+        this.buildCompatibilityMap();
+    }
+    /**
+     * Build the compatibility map from configuration rules
+     */
+    buildCompatibilityMap() {
+        this.compatibilityMap.clear();
+        // First, add direct type matches (every type is compatible with itself)
+        for (const dataType of this.portConfig.dataTypes) {
+            if (!this.compatibilityMap.has(dataType.id)) {
+                this.compatibilityMap.set(dataType.id, new Set());
+            }
+            this.compatibilityMap.get(dataType.id).add(dataType.id);
+        }
+        // Then add configured compatibility rules
+        for (const rule of this.portConfig.compatibilityRules) {
+            if (!this.compatibilityMap.has(rule.from)) {
+                this.compatibilityMap.set(rule.from, new Set());
+            }
+            this.compatibilityMap.get(rule.from).add(rule.to);
+        }
+        // Add alias support
+        for (const dataType of this.portConfig.dataTypes) {
+            if (dataType.aliases) {
+                for (const alias of dataType.aliases) {
+                    // Make aliases point to the main type's compatibility set
+                    const mainCompatibility = this.compatibilityMap.get(dataType.id);
+                    if (mainCompatibility) {
+                        this.compatibilityMap.set(alias, new Set(mainCompatibility));
+                        // Also make the main type compatible with the alias
+                        mainCompatibility.add(alias);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Check if two data types are compatible for connection
+     */
+    areDataTypesCompatible(outputType, inputType) {
+        const compatibleTypes = this.compatibilityMap.get(outputType);
+        return compatibleTypes ? compatibleTypes.has(inputType) : false;
+    }
+    /**
+     * Get all compatible target types for a source type
+     */
+    getCompatibleTypes(sourceType) {
+        const compatibleTypes = this.compatibilityMap.get(sourceType);
+        return compatibleTypes ? Array.from(compatibleTypes) : [];
+    }
+    /**
+     * Get data type configuration by ID
+     */
+    getDataTypeConfig(dataTypeId) {
+        return this.portConfig.dataTypes.find((dt) => dt.id === dataTypeId || dt.aliases?.includes(dataTypeId));
+    }
+    /**
+     * Get all enabled data types
+     */
+    getEnabledDataTypes() {
+        return this.portConfig.dataTypes.filter((dt) => dt.enabled !== false);
+    }
+}
+// Global instance - will be initialized with configuration
+let globalCompatibilityChecker = null;
+/**
+ * Initialize the global port compatibility checker
+ */
+export function initializePortCompatibility(portConfig) {
+    globalCompatibilityChecker = new PortCompatibilityChecker(portConfig);
+}
+/**
+ * Get the global port compatibility checker
+ */
+export function getPortCompatibilityChecker() {
+    if (!globalCompatibilityChecker) {
+        throw new Error('Port compatibility checker not initialized. Call initializePortCompatibility() first.');
+    }
+    return globalCompatibilityChecker;
+}
+/**
+ * Get all possible connections from a source node to target nodes
+ */
+export function getPossibleConnections(sourceNode, targetNodes, nodeTypes) {
+    const sourceMetadata = nodeTypes.find((nt) => nt.id === sourceNode.data.metadata.id);
+    if (!sourceMetadata)
+        return [];
+    const possibleConnections = [];
+    // Get all output ports from source node
+    const sourceOutputs = sourceMetadata.outputs;
+    // Get the compatibility checker instance
+    const checker = getPortCompatibilityChecker();
+    // Check each target node
+    for (const targetNode of targetNodes) {
+        if (targetNode.id === sourceNode.id)
+            continue; // Skip self-connection
+        const targetMetadata = nodeTypes.find((nt) => nt.id === targetNode.data.metadata.id);
+        if (!targetMetadata)
+            continue;
+        // Get all input ports from target node
+        const targetInputs = targetMetadata.inputs;
+        // Check each output-input combination
+        for (const sourcePort of sourceOutputs) {
+            for (const targetPort of targetInputs) {
+                const compatible = checker.areDataTypesCompatible(sourcePort.dataType, targetPort.dataType);
+                possibleConnections.push({
+                    sourceNodeId: sourceNode.id,
+                    sourcePortId: sourcePort.id,
+                    sourcePort,
+                    targetNodeId: targetNode.id,
+                    targetPortId: targetPort.id,
+                    targetPort,
+                    compatible
+                });
+            }
+        }
+    }
+    return possibleConnections;
+}
+/**
+ * Validate if a specific connection is valid
+ */
+export function validateConnection(sourceNodeId, sourcePortId, targetNodeId, targetPortId, nodes, nodeTypes) {
+    // Check if nodes exist
+    const sourceNode = nodes.find((n) => n.id === sourceNodeId);
+    const targetNode = nodes.find((n) => n.id === targetNodeId);
+    if (!sourceNode) {
+        return { valid: false, error: 'Source node not found' };
+    }
+    if (!targetNode) {
+        return { valid: false, error: 'Target node not found' };
+    }
+    // Check for self-connection
+    if (sourceNodeId === targetNodeId) {
+        return { valid: false, error: 'Cannot connect node to itself' };
+    }
+    // Get node metadata
+    const sourceMetadata = nodeTypes.find((nt) => nt.id === sourceNode.data.metadata.id);
+    const targetMetadata = nodeTypes.find((nt) => nt.id === targetNode.data.metadata.id);
+    if (!sourceMetadata || !targetMetadata) {
+        return { valid: false, error: 'Node metadata not found' };
+    }
+    // Find ports
+    const sourcePort = sourceMetadata.outputs.find((p) => p.id === sourcePortId);
+    const targetPort = targetMetadata.inputs.find((p) => p.id === targetPortId);
+    if (!sourcePort) {
+        return { valid: false, error: 'Source port not found' };
+    }
+    if (!targetPort) {
+        return { valid: false, error: 'Target port not found' };
+    }
+    // Check data type compatibility using the global checker
+    const checker = getPortCompatibilityChecker();
+    if (!checker.areDataTypesCompatible(sourcePort.dataType, targetPort.dataType)) {
+        return {
+            valid: false,
+            error: `Incompatible data types: ${sourcePort.dataType} cannot connect to ${targetPort.dataType}`
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Get connection suggestions for a node
+ */
+export function getConnectionSuggestions(nodeId, nodes, nodeTypes) {
+    const node = nodes.find((n) => n.id === nodeId);
+    if (!node)
+        return [];
+    const metadata = nodeTypes.find((nt) => nt.id === node.data.metadata.id);
+    if (!metadata)
+        return [];
+    const suggestions = [];
+    // Get all other nodes
+    const otherNodes = nodes.filter((n) => n.id !== nodeId);
+    // Get the compatibility checker instance
+    const checker = getPortCompatibilityChecker();
+    for (const otherNode of otherNodes) {
+        const otherMetadata = nodeTypes.find((nt) => nt.id === otherNode.data.metadata.id);
+        if (!otherMetadata)
+            continue;
+        // Check outputs from other nodes to inputs of current node
+        for (const output of otherMetadata.outputs) {
+            for (const input of metadata.inputs) {
+                const compatible = checker.areDataTypesCompatible(output.dataType, input.dataType);
+                suggestions.push({
+                    nodeId: otherNode.id,
+                    nodeName: otherNode.data.label,
+                    portId: output.id,
+                    portName: output.name,
+                    portType: 'output',
+                    dataType: output.dataType,
+                    compatible
+                });
+            }
+        }
+        // Check outputs from current node to inputs of other nodes
+        for (const output of metadata.outputs) {
+            for (const input of otherMetadata.inputs) {
+                const compatible = checker.areDataTypesCompatible(output.dataType, input.dataType);
+                suggestions.push({
+                    nodeId: otherNode.id,
+                    nodeName: otherNode.data.label,
+                    portId: input.id,
+                    portName: input.name,
+                    portType: 'input',
+                    dataType: input.dataType,
+                    compatible
+                });
+            }
+        }
+    }
+    return suggestions;
+}
+/**
+ * Check if a workflow has any cycles (prevent infinite loops)
+ * Note: This function detects ALL cycles, including valid loopback cycles.
+ * Use `hasInvalidCycles` to check only for cycles that could cause infinite execution.
+ *
+ * @param nodes - Array of workflow nodes
+ * @param edges - Array of workflow edges
+ * @returns True if any cycle exists in the workflow
+ */
+export function hasCycles(nodes, edges) {
+    // Build adjacency map once (O(E)) so the DFS inner loop is O(1) per lookup
+    // instead of scanning all edges on every recursive call (which was O(V*E)).
+    const adjacencyMap = new Map();
+    for (const node of nodes) {
+        adjacencyMap.set(node.id, []);
+    }
+    for (const edge of edges) {
+        const neighbors = adjacencyMap.get(edge.source);
+        if (neighbors) {
+            neighbors.push(edge.target);
+        }
+    }
+    const visited = new Set();
+    const recursionStack = new Set();
+    function hasCycleUtil(nodeId) {
+        if (recursionStack.has(nodeId))
+            return true;
+        if (visited.has(nodeId))
+            return false;
+        visited.add(nodeId);
+        recursionStack.add(nodeId);
+        // Use pre-built adjacency map instead of filtering all edges each call
+        const neighbors = adjacencyMap.get(nodeId) || [];
+        for (const target of neighbors) {
+            if (hasCycleUtil(target))
+                return true;
+        }
+        recursionStack.delete(nodeId);
+        return false;
+    }
+    // Check each node
+    for (const node of nodes) {
+        if (!visited.has(node.id)) {
+            if (hasCycleUtil(node.id))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Check if a workflow has any invalid cycles (non-loopback cycles).
+ * This excludes valid loopback cycles used for ForEach iteration.
+ * Only cycles that could cause infinite execution are detected.
+ *
+ * @param nodes - Array of workflow nodes
+ * @param edges - Array of workflow edges
+ * @returns True if any invalid (non-loopback) cycle exists
+ *
+ * @example
+ * ```typescript
+ * // A cycle through a loopback edge is valid (returns false)
+ * // A cycle through regular data edges is invalid (returns true)
+ * const hasInvalid = hasInvalidCycles(nodes, edges);
+ * ```
+ */
+export function hasInvalidCycles(nodes, edges) {
+    // Filter out loopback edges - these create valid cycles for loop iteration
+    const nonLoopbackEdges = edges.filter((edge) => !isLoopbackEdge(edge));
+    // Build adjacency map from non-loopback edges once (O(E)) so the DFS inner
+    // loop is O(1) per lookup instead of scanning all edges on every recursive
+    // call (which was O(V*E)).
+    const adjacencyMap = new Map();
+    for (const node of nodes) {
+        adjacencyMap.set(node.id, []);
+    }
+    for (const edge of nonLoopbackEdges) {
+        const neighbors = adjacencyMap.get(edge.source);
+        if (neighbors) {
+            neighbors.push(edge.target);
+        }
+    }
+    // Check for cycles using only non-loopback edges
+    const visited = new Set();
+    const recursionStack = new Set();
+    /**
+     * DFS utility to detect cycles in the graph
+     * @param nodeId - Current node being visited
+     * @returns True if a cycle is found from this node
+     */
+    function hasCycleUtil(nodeId) {
+        if (recursionStack.has(nodeId))
+            return true;
+        if (visited.has(nodeId))
+            return false;
+        visited.add(nodeId);
+        recursionStack.add(nodeId);
+        // Use pre-built adjacency map instead of filtering all edges each call
+        const neighbors = adjacencyMap.get(nodeId) || [];
+        for (const target of neighbors) {
+            if (hasCycleUtil(target))
+                return true;
+        }
+        recursionStack.delete(nodeId);
+        return false;
+    }
+    // Check each node for cycles
+    for (const node of nodes) {
+        if (!visited.has(node.id)) {
+            if (hasCycleUtil(node.id))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Get the execution order for a workflow (topological sort)
+ */
+export function getExecutionOrder(nodes, edges) {
+    const inDegree = new Map();
+    const graph = new Map();
+    // Initialize
+    for (const node of nodes) {
+        inDegree.set(node.id, 0);
+        graph.set(node.id, []);
+    }
+    // Build graph and calculate in-degrees
+    for (const edge of edges) {
+        const current = inDegree.get(edge.target) || 0;
+        inDegree.set(edge.target, current + 1);
+        const neighbors = graph.get(edge.source) || [];
+        neighbors.push(edge.target);
+        graph.set(edge.source, neighbors);
+    }
+    // Topological sort
+    const queue = [];
+    const result = [];
+    // Add nodes with no incoming edges
+    for (const [nodeId, degree] of inDegree) {
+        if (degree === 0) {
+            queue.push(nodeId);
+        }
+    }
+    while (queue.length > 0) {
+        const nodeId = queue.shift();
+        result.push(nodeId);
+        const neighbors = graph.get(nodeId) || [];
+        for (const neighbor of neighbors) {
+            const degree = inDegree.get(neighbor) - 1;
+            inDegree.set(neighbor, degree);
+            if (degree === 0) {
+                queue.push(neighbor);
+            }
+        }
+    }
+    return result;
+}

package/dist/utils/errors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Error Handling Utilities
+ *
+ * @module utils/errors
+ */
+/**
+ * Normalize an unknown caught value into an Error instance.
+ *
+ * Use in catch blocks where the error type is `unknown`:
+ * ```typescript
+ * try { ... } catch (error) {
+ *   const err = normalizeError(error);
+ *   logger.error(err.message);
+ * }
+ * ```
+ *
+ * @param error - The caught value (may be Error, string, or anything)
+ * @returns An Error instance with a meaningful message
+ */
+export declare function normalizeError(error: unknown): Error;
+/**
+ * Extract a human-readable message from an unknown error.
+ *
+ * @param error - The caught value
+ * @param fallback - Fallback message if error has no useful info
+ * @returns A string message
+ */
+export declare function getErrorMessage(error: unknown, fallback?: string): string;

package/dist/utils/errors.js

@@ -0,0 +1,44 @@
+/**
+ * Error Handling Utilities
+ *
+ * @module utils/errors
+ */
+/**
+ * Normalize an unknown caught value into an Error instance.
+ *
+ * Use in catch blocks where the error type is `unknown`:
+ * ```typescript
+ * try { ... } catch (error) {
+ *   const err = normalizeError(error);
+ *   logger.error(err.message);
+ * }
+ * ```
+ *
+ * @param error - The caught value (may be Error, string, or anything)
+ * @returns An Error instance with a meaningful message
+ */
+export function normalizeError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    if (typeof error === 'string') {
+        return new Error(error);
+    }
+    return new Error(String(error));
+}
+/**
+ * Extract a human-readable message from an unknown error.
+ *
+ * @param error - The caught value
+ * @param fallback - Fallback message if error has no useful info
+ * @returns A string message
+ */
+export function getErrorMessage(error, fallback = 'Unknown error') {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return fallback;
+}

package/dist/utils/fetchWithAuth.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Fetch authentication utilities
+ *
+ * Shared logic for building HTTP headers with authentication.
+ * Used by components that make authenticated API requests (e.g., FormAutocomplete).
+ *
+ * @module utils/fetchWithAuth
+ */
+import type { AuthProvider } from '../types/auth.js';
+/**
+ * Build fetch headers with optional authentication
+ *
+ * Constructs standard JSON request headers and merges in authentication
+ * headers from the provided AuthProvider, if available.
+ *
+ * @param authProvider - Optional auth provider to get headers from
+ * @returns Promise resolving to a complete headers object
+ *
+ * @example
+ * ```typescript
+ * const headers = await buildFetchHeaders(authProvider);
+ * const response = await fetch(url, { headers });
+ * ```
+ */
+export declare function buildFetchHeaders(authProvider?: AuthProvider): Promise<Record<string, string>>;

package/dist/utils/fetchWithAuth.js

@@ -0,0 +1,34 @@
+/**
+ * Fetch authentication utilities
+ *
+ * Shared logic for building HTTP headers with authentication.
+ * Used by components that make authenticated API requests (e.g., FormAutocomplete).
+ *
+ * @module utils/fetchWithAuth
+ */
+/**
+ * Build fetch headers with optional authentication
+ *
+ * Constructs standard JSON request headers and merges in authentication
+ * headers from the provided AuthProvider, if available.
+ *
+ * @param authProvider - Optional auth provider to get headers from
+ * @returns Promise resolving to a complete headers object
+ *
+ * @example
+ * ```typescript
+ * const headers = await buildFetchHeaders(authProvider);
+ * const response = await fetch(url, { headers });
+ * ```
+ */
+export async function buildFetchHeaders(authProvider) {
+    const headers = {
+        Accept: 'application/json',
+        'Content-Type': 'application/json'
+    };
+    if (authProvider) {
+        const authHeaders = await authProvider.getAuthHeaders();
+        Object.assign(headers, authHeaders);
+    }
+    return headers;
+}

package/dist/utils/handleIds.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Handle ID utilities for FlowDrop
+ *
+ * Handle IDs encode node + direction + port in the format:
+ * `${nodeId}-${direction}-${portId}` (e.g., "node1-output-trigger")
+ *
+ * @module utils/handleIds
+ */
+/**
+ * Build a handle ID from its parts.
+ *
+ * @param nodeId - The node identifier
+ * @param direction - 'input' or 'output'
+ * @param portId - The port identifier
+ * @returns A composite handle ID string
+ */
+export declare function buildHandleId(nodeId: string, direction: 'input' | 'output', portId: string): string;
+/**
+ * Extract the port ID from a composite handle ID.
+ *
+ * Supports two formats:
+ * 1. Standard: `${nodeId}-output-${portId}` or `${nodeId}-input-${portId}`
+ * 2. Short: just the portId itself (returned as-is)
+ *
+ * @param handleId - The handle ID string
+ * @returns The port ID, or null if handleId is empty/undefined
+ */
+export declare function extractPortId(handleId: string | undefined): string | null;
+/**
+ * Extract the direction from a composite handle ID.
+ *
+ * @param handleId - The handle ID string
+ * @returns 'input', 'output', or null if not found
+ */
+export declare function extractDirection(handleId: string | undefined): 'input' | 'output' | null;

package/dist/utils/handleIds.js

@@ -0,0 +1,58 @@
+/**
+ * Handle ID utilities for FlowDrop
+ *
+ * Handle IDs encode node + direction + port in the format:
+ * `${nodeId}-${direction}-${portId}` (e.g., "node1-output-trigger")
+ *
+ * @module utils/handleIds
+ */
+/**
+ * Build a handle ID from its parts.
+ *
+ * @param nodeId - The node identifier
+ * @param direction - 'input' or 'output'
+ * @param portId - The port identifier
+ * @returns A composite handle ID string
+ */
+export function buildHandleId(nodeId, direction, portId) {
+    return `${nodeId}-${direction}-${portId}`;
+}
+/**
+ * Extract the port ID from a composite handle ID.
+ *
+ * Supports two formats:
+ * 1. Standard: `${nodeId}-output-${portId}` or `${nodeId}-input-${portId}`
+ * 2. Short: just the portId itself (returned as-is)
+ *
+ * @param handleId - The handle ID string
+ * @returns The port ID, or null if handleId is empty/undefined
+ */
+export function extractPortId(handleId) {
+    if (!handleId)
+        return null;
+    const outputMatch = handleId.lastIndexOf('-output-');
+    if (outputMatch !== -1) {
+        return handleId.substring(outputMatch + '-output-'.length);
+    }
+    const inputMatch = handleId.lastIndexOf('-input-');
+    if (inputMatch !== -1) {
+        return handleId.substring(inputMatch + '-input-'.length);
+    }
+    // Short format: the handleId IS the port ID
+    return handleId;
+}
+/**
+ * Extract the direction from a composite handle ID.
+ *
+ * @param handleId - The handle ID string
+ * @returns 'input', 'output', or null if not found
+ */
+export function extractDirection(handleId) {
+    if (!handleId)
+        return null;
+    if (handleId.includes('-output-'))
+        return 'output';
+    if (handleId.includes('-input-'))
+        return 'input';
+    return null;
+}

package/dist/utils/handlePositioning.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Utility functions for calculating handle positions on nodes
+ */
+export interface HandlePosition {
+    left: number;
+    top: number;
+}
+/**
+ * Calculate handle position along a circle arc using cos/sin
+ *
+ * Distributes handles evenly along an arc on the left or right side of a circle.
+ * For N handles, they are positioned at angles calculated as:
+ * angle = centerAngle - arcSpan/2 + arcSpan * (index + 1) / (count + 1)
+ *
+ * @param index - The index of the handle (0-based)
+ * @param count - Total number of handles on this side
+ * @param side - 'left' for inputs, 'right' for outputs
+ * @param radius - The radius of the circle (default: 40px for 80px diameter)
+ * @param arcSpan - The arc span in radians (default: 5π/6 = 150°)
+ * @returns Object with left and top pixel values relative to the circle's bounding box
+ *
+ * @example
+ * // Single handle on left side - positioned at center (180°)
+ * getCircleHandlePosition(0, 1, 'left') // { left: 0, top: 36 }
+ *
+ * @example
+ * // Two handles on left side - positioned at 150° and 210°
+ * getCircleHandlePosition(0, 2, 'left') // { left: ~4.8, top: ~18 }
+ * getCircleHandlePosition(1, 2, 'left') // { left: ~4.8, top: ~54 }
+ */
+export declare function getCircleHandlePosition(index: number, count: number, side: 'left' | 'right', radius?: number, arcSpan?: number): HandlePosition;