@flowdrop/flowdrop 1.4.0 → 1.6.0

package/dist/utils/logger.js

@@ -25,9 +25,9 @@ const LOG_PRIORITY = {
     info: 1,
     warn: 2,
     error: 3,
-    none: 4,
+    none: 4
 };
-let currentLevel = "none";
+let currentLevel = 'none';
 /**
  * Set the minimum log level for FlowDrop library output.
  * Messages below this level are silently discarded.
@@ -54,19 +54,19 @@ function shouldLog(level) {
  */
 export const logger = {
     debug(message, ...args) {
-        if (shouldLog("debug"))
+        if (shouldLog('debug'))
             console.debug(`[FlowDrop] ${message}`, ...args);
     },
     info(message, ...args) {
-        if (shouldLog("info"))
+        if (shouldLog('info'))
             console.info(`[FlowDrop] ${message}`, ...args);
     },
     warn(message, ...args) {
-        if (shouldLog("warn"))
+        if (shouldLog('warn'))
             console.warn(`[FlowDrop] ${message}`, ...args);
     },
     error(message, ...args) {
-        if (shouldLog("error"))
+        if (shouldLog('error'))
             console.error(`[FlowDrop] ${message}`, ...args);
-    },
+    }
 };

package/dist/utils/nodeIds.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared node ID generation and config defaults utilities.
+ * Used by both the visual editor and the workflow adapter to ensure
+ * consistent behavior across all code paths.
+ */
+import type { ConfigSchema } from '../types/index.js';
+/**
+ * Minimal node shape required for ID generation.
+ * Both WorkflowNode and StandardNode satisfy this interface.
+ */
+interface NodeWithMetadata {
+    id: string;
+    data?: {
+        metadata?: {
+            id?: string;
+        };
+    };
+}
+/**
+ * Generate a unique node ID based on node type and existing nodes.
+ * Format: <node_type>.<number>
+ * Example: boolean_gateway.1, calculator.2
+ */
+export declare function generateNodeId(nodeTypeId: string, existingNodes: NodeWithMetadata[]): string;
+/**
+ * Extract default config values from a node's configSchema.
+ * Iterates configSchema.properties and returns an object with each property's
+ * default value (if defined).
+ */
+export declare function extractConfigDefaults(configSchema?: ConfigSchema): Record<string, unknown>;
+export {};

package/dist/utils/nodeIds.js

@@ -0,0 +1,42 @@
+/**
+ * Shared node ID generation and config defaults utilities.
+ * Used by both the visual editor and the workflow adapter to ensure
+ * consistent behavior across all code paths.
+ */
+/**
+ * Generate a unique node ID based on node type and existing nodes.
+ * Format: <node_type>.<number>
+ * Example: boolean_gateway.1, calculator.2
+ */
+export function generateNodeId(nodeTypeId, existingNodes) {
+    // Count how many nodes of this type already exist
+    const existingNodeIds = existingNodes
+        .filter((node) => node.data?.metadata?.id === nodeTypeId)
+        .map((node) => node.id);
+    // Extract the numbers from existing IDs with the same prefix
+    const existingNumbers = existingNodeIds
+        .map((id) => {
+        const match = id.match(new RegExp(`^${nodeTypeId}\\.(\\d+)$`));
+        return match ? parseInt(match[1], 10) : 0;
+    })
+        .filter((num) => num > 0);
+    // Find the next available number (highest + 1)
+    const nextNumber = existingNumbers.length > 0 ? Math.max(...existingNumbers) + 1 : 1;
+    return `${nodeTypeId}.${nextNumber}`;
+}
+/**
+ * Extract default config values from a node's configSchema.
+ * Iterates configSchema.properties and returns an object with each property's
+ * default value (if defined).
+ */
+export function extractConfigDefaults(configSchema) {
+    const config = {};
+    if (!configSchema?.properties)
+        return config;
+    for (const [key, prop] of Object.entries(configSchema.properties)) {
+        if (prop && typeof prop === 'object' && 'default' in prop) {
+            config[key] = prop.default;
+        }
+    }
+    return config;
+}

package/dist/utils/nodeStatus.d.ts

@@ -2,7 +2,7 @@
  * Node Status Utility Functions
  * Provides utilities for managing and displaying node execution status
  */
-import type { NodeExecutionStatus, NodeExecutionInfo } from "../types/index.js";
+import type { NodeExecutionStatus, NodeExecutionInfo } from '../types/index.js';
 /**
  * Get the display color for a node execution status
  */

package/dist/utils/nodeStatus.js

@@ -7,13 +7,13 @@
  */
 export function getStatusColor(status) {
     const statusColors = {
-        idle: "#6b7280", // gray
-        pending: "#f59e0b", // amber
-        running: "#3b82f6", // blue
-        completed: "#10b981", // emerald
-        failed: "#ef4444", // red
-        cancelled: "#6b7280", // gray
-        skipped: "#8b5cf6", // violet
+        idle: '#6b7280', // gray
+        pending: '#f59e0b', // amber
+        running: '#3b82f6', // blue
+        completed: '#10b981', // emerald
+        failed: '#ef4444', // red
+        cancelled: '#6b7280', // gray
+        skipped: '#8b5cf6' // violet
     };
     return statusColors[status] || statusColors.idle;
 }
@@ -22,13 +22,13 @@ export function getStatusColor(status) {
  */
 export function getStatusIcon(status) {
     const statusIcons = {
-        idle: "mdi:circle-outline",
-        pending: "mdi:clock-outline",
-        running: "mdi:loading",
-        completed: "mdi:check-circle",
-        failed: "mdi:alert-circle",
-        cancelled: "mdi:cancel",
-        skipped: "mdi:skip-next",
+        idle: 'mdi:circle-outline',
+        pending: 'mdi:clock-outline',
+        running: 'mdi:loading',
+        completed: 'mdi:check-circle',
+        failed: 'mdi:alert-circle',
+        cancelled: 'mdi:cancel',
+        skipped: 'mdi:skip-next'
     };
     return statusIcons[status] || statusIcons.idle;
 }
@@ -37,13 +37,13 @@ export function getStatusIcon(status) {
  */
 export function getStatusLabel(status) {
     const statusLabels = {
-        idle: "Idle",
-        pending: "Pending",
-        running: "Running",
-        completed: "Completed",
-        failed: "Failed",
-        cancelled: "Cancelled",
-        skipped: "Skipped",
+        idle: 'Idle',
+        pending: 'Pending',
+        running: 'Running',
+        completed: 'Completed',
+        failed: 'Failed',
+        cancelled: 'Cancelled',
+        skipped: 'Skipped'
     };
     return statusLabels[status] || statusLabels.idle;
 }
@@ -52,13 +52,13 @@ export function getStatusLabel(status) {
  */
 export function getStatusBackgroundColor(status) {
     const statusBackgroundColors = {
-        idle: "#f9fafb", // light gray
-        pending: "#fef3c7", // light amber
-        running: "#dbeafe", // light blue
-        completed: "#d1fae5", // light emerald
-        failed: "#fee2e2", // light red
-        cancelled: "#f3f4f6", // light gray
-        skipped: "#ede9fe", // light violet
+        idle: '#f9fafb', // light gray
+        pending: '#fef3c7', // light amber
+        running: '#dbeafe', // light blue
+        completed: '#d1fae5', // light emerald
+        failed: '#fee2e2', // light red
+        cancelled: '#f3f4f6', // light gray
+        skipped: '#ede9fe' // light violet
     };
     return statusBackgroundColors[status] || statusBackgroundColors.idle;
 }
@@ -67,13 +67,13 @@ export function getStatusBackgroundColor(status) {
  */
 export function getStatusTextColor(status) {
     const statusTextColors = {
-        idle: "#6b7280", // gray
-        pending: "#d97706", // amber
-        running: "#1d4ed8", // blue
-        completed: "#059669", // emerald
-        failed: "#dc2626", // red
-        cancelled: "#6b7280", // gray
-        skipped: "#7c3aed", // violet
+        idle: '#6b7280', // gray
+        pending: '#d97706', // amber
+        running: '#1d4ed8', // blue
+        completed: '#059669', // emerald
+        failed: '#dc2626', // red
+        cancelled: '#6b7280', // gray
+        skipped: '#7c3aed' // violet
     };
     return statusTextColors[status] || statusTextColors.idle;
 }
@@ -82,9 +82,9 @@ export function getStatusTextColor(status) {
  */
 export function createDefaultExecutionInfo() {
     return {
-        status: "idle",
+        status: 'idle',
         executionCount: 0,
-        isExecuting: false,
+        isExecuting: false
     };
 }
 /**
@@ -93,8 +93,8 @@ export function createDefaultExecutionInfo() {
 export function updateExecutionStart(executionInfo) {
     return {
         ...executionInfo,
-        status: "running",
-        isExecuting: true,
+        status: 'running',
+        isExecuting: true
     };
 }
 /**
@@ -103,12 +103,12 @@ export function updateExecutionStart(executionInfo) {
 export function updateExecutionComplete(executionInfo, duration) {
     return {
         ...executionInfo,
-        status: "completed",
+        status: 'completed',
         executionCount: executionInfo.executionCount + 1,
         lastExecuted: new Date().toISOString(),
         lastExecutionDuration: duration,
         isExecuting: false,
-        lastError: undefined, // Clear any previous error
+        lastError: undefined // Clear any previous error
     };
 }
 /**
@@ -117,12 +117,12 @@ export function updateExecutionComplete(executionInfo, duration) {
 export function updateExecutionFailed(executionInfo, error, duration) {
     return {
         ...executionInfo,
-        status: "failed",
+        status: 'failed',
         executionCount: executionInfo.executionCount + 1,
         lastExecuted: new Date().toISOString(),
         lastExecutionDuration: duration,
         isExecuting: false,
-        lastError: error,
+        lastError: error
     };
 }
 /**
@@ -131,9 +131,9 @@ export function updateExecutionFailed(executionInfo, error, duration) {
 export function resetExecutionInfo(executionInfo) {
     return {
         ...executionInfo,
-        status: "idle",
+        status: 'idle',
         isExecuting: false,
-        lastError: undefined,
+        lastError: undefined
     };
 }
 /**
@@ -141,7 +141,7 @@ export function resetExecutionInfo(executionInfo) {
  */
 export function formatExecutionDuration(duration) {
     if (!duration)
-        return "N/A";
+        return 'N/A';
     if (duration < 1000) {
         return `${Math.round(duration)}ms`;
     }
@@ -159,13 +159,13 @@ export function formatExecutionDuration(duration) {
  */
 export function formatLastExecuted(timestamp) {
     if (!timestamp)
-        return "Never";
+        return 'Never';
     const date = new Date(timestamp);
     const now = new Date();
     const diffMs = now.getTime() - date.getTime();
     if (diffMs < 60000) {
         // Less than 1 minute
-        return "Just now";
+        return 'Just now';
     }
     else if (diffMs < 3600000) {
         // Less than 1 hour

package/dist/utils/nodeSwap.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Node Swap utilities for FlowDrop
+ *
+ * Provides logic for swapping a workflow node with a different node type
+ * while intelligently remapping compatible port connections.
+ *
+ * @module utils/nodeSwap
+ */
+import type { WorkflowNode, WorkflowEdge, NodeMetadata, NodePort, ConfigSchema, ConfigValues } from '../types/index.js';
+import type { WorkflowValidationResult } from './validation.js';
+import type { PortCompatibilityChecker } from './connections.js';
+/**
+ * Describes how a single port was remapped during a swap.
+ */
+export interface PortMapping {
+    oldHandleId: string;
+    newHandleId: string;
+    oldPortId: string;
+    newPortId: string;
+    direction: 'input' | 'output';
+}
+/**
+ * An edge that could not be remapped and will be dropped.
+ */
+export interface DroppedEdge {
+    edge: WorkflowEdge;
+    reason: string;
+}
+/**
+ * Preview of what a node swap will do before it is executed.
+ */
+export interface SwapPreview {
+    /** Edges that will be preserved with their rewritten versions */
+    keptEdges: Array<{
+        edge: WorkflowEdge;
+        newEdge: WorkflowEdge;
+    }>;
+    /** Edges that will be removed */
+    droppedEdges: DroppedEdge[];
+    /** True if any connected edges will be lost */
+    hasDataLoss: boolean;
+    /** The new node ID that will be generated */
+    newNodeId: string;
+    /** Config keys carried over from the old node */
+    configCarriedOver: string[];
+    /** Config keys reset to defaults on the new node */
+    configReset: string[];
+}
+/**
+ * Result of executing a node swap.
+ */
+export interface SwapResult {
+    updatedNodes: WorkflowNode[];
+    updatedEdges: WorkflowEdge[];
+}
+/** Quality annotation for how a port was matched. */
+export type MatchQuality = 'id' | 'name' | 'type' | 'manual' | 'unmapped';
+/** Manual override for a single port mapping. */
+export interface PortMappingOverride {
+    oldPortId: string;
+    newPortId: string | null;
+    direction: 'input' | 'output';
+}
+/** Manual override for a single config mapping. */
+export interface ConfigMappingOverride {
+    key: string;
+    action: 'carry' | 'reset' | 'set';
+    value?: unknown;
+}
+/** Options bag for advanced swap functions. */
+export interface SwapOptions {
+    checker?: PortCompatibilityChecker | null;
+    portOverrides?: PortMappingOverride[];
+    configOverrides?: ConfigMappingOverride[];
+    strategies?: SwapStrategy[];
+}
+/** Pluggable strategy passed per-call, not registered globally. */
+export interface SwapStrategy {
+    readonly id: string;
+    readonly name: string;
+    canHandle(ctx: SwapStrategyContext): boolean;
+    mapPorts?(ctx: SwapStrategyContext): Record<string, string | null> | undefined;
+    mapConfig?(ctx: SwapStrategyContext): Record<string, {
+        action: 'carry' | 'reset' | 'set';
+        value?: unknown;
+    }> | undefined;
+}
+/** Context passed to swap strategies. */
+export interface SwapStrategyContext {
+    oldNode: WorkflowNode;
+    newMetadata: NodeMetadata;
+    edges: WorkflowEdge[];
+    allNodes: WorkflowNode[];
+    checker: PortCompatibilityChecker | null;
+}
+/** Stable, data-only event context for swap hooks. */
+export interface SwapEventContext {
+    oldNode: WorkflowNode;
+    newMetadata: NodeMetadata;
+    preview: SwapPreview;
+    portOverrides: PortMappingOverride[];
+    configOverrides: ConfigMappingOverride[];
+}
+/** Error class for swap validation failures. */
+export declare class SwapValidationError extends Error {
+    constructor(message: string);
+}
+/** Editable port mapping for the interactive mapping editor. */
+export interface EditablePortMapping {
+    oldPort: NodePort;
+    edge: WorkflowEdge;
+    direction: 'input' | 'output';
+    selectedNewPortId: string | null;
+    matchQuality: MatchQuality;
+    autoSuggestedPortId: string | null;
+    isOverridden: boolean;
+}
+/** Editable config mapping for the interactive mapping editor. */
+export interface EditableConfigMapping {
+    key: string;
+    title: string;
+    oldValue: unknown;
+    newDefault: unknown;
+    carryOver: boolean;
+    autoCarryOver: boolean;
+    /** false for nested objects/arrays — shown as read-only, always reset */
+    isFlat: boolean;
+}
+/** Full interactive swap state for the mapping editor. */
+export interface InteractiveSwapState {
+    oldNode: WorkflowNode;
+    newMetadata: NodeMetadata;
+    newNodeId: string;
+    portMappings: EditablePortMapping[];
+    configMappings: EditableConfigMapping[];
+    availableNewInputs: NodePort[];
+    availableNewOutputs: NodePort[];
+}
+/**
+ * Compare two semver-like version strings.
+ * Returns positive if a > b, negative if a < b, 0 if equal.
+ *
+ * Handles pre-release tags: "2.0.0-beta" < "2.0.0"
+ */
+export declare function compareSemver(a: string, b: string): number;
+/**
+ * Map config values from an old node to a new node's schema.
+ *
+ * - Keys present in both old config and new schema: carry over the old value
+ * - Keys only in the new schema: use the schema default or newDefaults
+ * - Keys only in the old config: discarded
+ * - Dynamic port keys (dynamicInputs, dynamicOutputs, branches): never carried over
+ */
+export declare function mapConfig(oldConfig: ConfigValues, newConfigSchema: ConfigSchema | undefined, newDefaults?: Record<string, unknown>): {
+    config: ConfigValues;
+    carriedOver: string[];
+    reset: string[];
+};
+/**
+ * Compute a preview of what will happen when swapping oldNode with newMetadata.
+ *
+ * This does NOT mutate anything — it returns a preview that can be displayed
+ * to the user for confirmation before executing the swap.
+ */
+export declare function computeSwapPreview(oldNode: WorkflowNode, newMetadata: NodeMetadata, edges: WorkflowEdge[], allNodes: WorkflowNode[], checker?: PortCompatibilityChecker | null): SwapPreview;
+/**
+ * Execute a node swap using a previously computed preview.
+ *
+ * Returns new nodes and edges arrays ready for `workflowActions.batchUpdate()`.
+ */
+export declare function executeSwap(oldNode: WorkflowNode, newMetadata: NodeMetadata, preview: SwapPreview, allNodes: WorkflowNode[], allEdges: WorkflowEdge[]): SwapResult;
+/**
+ * Check if a newer version of the same node type is available.
+ *
+ * Compares the node's embedded metadata.version against the same-ID entry
+ * in the available nodes list (API returns only the latest version).
+ *
+ * @returns The newer NodeMetadata if an upgrade is available, null otherwise
+ */
+export declare function getVersionUpgrade(currentMetadata: NodeMetadata, allNodeTypes: NodeMetadata[]): NodeMetadata | null;
+/**
+ * Compute a swap preview with full options support (strategies, overrides).
+ *
+ * Resolution order:
+ * 1. Check strategies — first canHandle() match wins for mapPorts()/mapConfig()
+ * 2. Fall through to built-in 3-pass for ports not covered by strategy
+ * 3. Apply portOverrides on top (highest priority — user's manual overrides)
+ * 4. Same cascade for config
+ */
+export declare function computeSwapPreviewWithOptions(oldNode: WorkflowNode, newMetadata: NodeMetadata, edges: WorkflowEdge[], allNodes: WorkflowNode[], options: SwapOptions): SwapPreview;
+/**
+ * Compute interactive state for the mapping editor UI.
+ *
+ * Returns EditablePortMapping and EditableConfigMapping entries
+ * with match quality annotations and isFlat flags.
+ */
+export declare function computeInteractiveState(oldNode: WorkflowNode, newMetadata: NodeMetadata, edges: WorkflowEdge[], allNodes: WorkflowNode[], options?: SwapOptions): InteractiveSwapState;
+/**
+ * Convert user-edited InteractiveSwapState back into a SwapPreview
+ * for executeSwap(). Pure function, no side effects.
+ */
+export declare function buildSwapPreviewFromState(state: InteractiveSwapState, allEdges: WorkflowEdge[]): SwapPreview;
+/**
+ * Headless one-shot swap with full validation.
+ *
+ * Guardrails:
+ * - Validates oldNode.id exists in allNodes
+ * - Validates format compatibility if newMetadata.formats is set
+ * - Computes preview → executes → validates → returns result
+ * - Throws SwapValidationError on invalid input
+ */
+export declare function performSwap(oldNode: WorkflowNode, newMetadata: NodeMetadata, allNodes: WorkflowNode[], allEdges: WorkflowEdge[], options?: SwapOptions): SwapResult;
+/**
+ * Validate a swap result for structural integrity.
+ *
+ * Checks:
+ * - No dangling edge references (every edge source/target exists in nodes)
+ * - No duplicate node IDs
+ * - No duplicate edge IDs
+ */
+export declare function validateSwapResult(result: SwapResult): WorkflowValidationResult;