@bian-womp/spark-graph 0.3.31 → 0.3.32

package/lib/cjs/index.cjs

@@ -18,19 +18,42 @@ function getTypedOutputValue(v) {
         return v.__spark_value;
     return v;
 }
-function getInputTypeId(inputs, handle) {
+/**
+ * Get the full declared type(s) for an input handle (supports union types)
+ * Returns the typeId as-is: string for single type, string[] for union types
+ */
+function getInputDeclaredTypes(inputs, handle) {
     const v = inputs ? inputs[handle] : undefined;
     if (!v)
         return undefined;
-    return typeof v === "string" ? v : v.typeId;
+    if (typeof v === "string")
+        return v;
+    if (Array.isArray(v))
+        return v;
+    return v.typeId;
+}
+/**
+ * Get the primary (first) type ID for an input handle.
+ * For union types, returns the first type in the array.
+ * This maintains backward compatibility for code that expects a single type.
+ */
+function getInputTypeId(inputs, handle) {
+    const decl = getInputDeclaredTypes(inputs, handle);
+    if (!decl)
+        return undefined;
+    return Array.isArray(decl) ? decl[0] : decl;
 }
 function isInputPrivate(inputs, handle) {
     const v = inputs ? inputs[handle] : undefined;
-    return !!(v && typeof v === "object" && v.private);
+    if (!v || typeof v === "string" || Array.isArray(v))
+        return false;
+    // At this point, v must be an object with optional private/metadata fields
+    return !!(typeof v === "object" && v !== null && "private" in v && v.private);
 }
 /**
  * Merge two InputHandleDescriptor values, with dynamic taking precedence.
  * If both have metadata, merge the metadata objects (dynamic overrides static).
+ * Supports union types (arrays) in both static and dynamic descriptors.
  */
 function mergeInputHandleDescriptors(staticDesc, dynamicDesc) {
     // If only one exists, return it
@@ -38,12 +61,17 @@ function mergeInputHandleDescriptors(staticDesc, dynamicDesc) {
         return dynamicDesc;
     if (!dynamicDesc)
         return staticDesc;
-    // If both are strings, dynamic wins
-    if (typeof staticDesc === "string" && typeof dynamicDesc === "string") {
+    // If both are primitive (string or array), dynamic wins
+    if ((typeof staticDesc === "string" || Array.isArray(staticDesc)) &&
+        (typeof dynamicDesc === "string" || Array.isArray(dynamicDesc))) {
         return dynamicDesc;
     }
-    const staticObj = typeof staticDesc === "string" ? { typeId: staticDesc } : staticDesc;
-    const dynamicObj = typeof dynamicDesc === "string" ? { typeId: dynamicDesc } : dynamicDesc;
+    const staticObj = typeof staticDesc === "string" || Array.isArray(staticDesc)
+        ? { typeId: staticDesc }
+        : staticDesc;
+    const dynamicObj = typeof dynamicDesc === "string" || Array.isArray(dynamicDesc)
+        ? { typeId: dynamicDesc }
+        : dynamicDesc;
     // Merge: dynamic takes precedence, but merge metadata objects
     const merged = {
         typeId: dynamicObj.typeId ?? staticObj.typeId,
@@ -64,7 +92,7 @@ function mergeInputHandleDescriptors(staticDesc, dynamicDesc) {
  */
 function getInputHandleMetadata(inputs, handle) {
     const v = inputs ? inputs[handle] : undefined;
-    if (!v || typeof v === "string")
+    if (!v || typeof v === "string" || Array.isArray(v))
         return undefined;
     return v.metadata;
 }
@@ -259,7 +287,11 @@ class Registry {
         if (cached)
             return cached;
         if (fromTypeId === toTypeId) {
-            const res = { kind: "sync", convert: (v) => v };
+            const res = {
+                kind: "sync",
+                convert: (v) => v,
+                cost: { edges: 0, async: 0 },
+            };
             this.resolvedCache.set(cacheKey, res);
             return res;
         }
@@ -269,6 +301,7 @@ class Registry {
             const res = {
                 kind: "sync",
                 convert: directSync.convert,
+                cost: { edges: 1, async: 0 },
             };
             this.resolvedCache.set(cacheKey, res);
             return res;
@@ -278,6 +311,7 @@ class Registry {
             const res = {
                 kind: "async",
                 convertAsync: directAsync.convertAsync,
+                cost: { edges: 1, async: 1 },
             };
             this.resolvedCache.set(cacheKey, res);
             return res;
@@ -334,6 +368,10 @@ class Registry {
             const cur = queue.shift();
             if (cur.node === toTypeId) {
                 // Compose
+                const cost = {
+                    edges: cur.cost.edges,
+                    async: cur.cost.async,
+                };
                 const hasAsync = cur.path.some((s) => s.kind === "async");
                 if (!hasAsync) {
                     const convert = (value) => {
@@ -344,7 +382,11 @@ class Registry {
                         }
                         return acc;
                     };
-                    const res = { kind: "sync", convert };
+                    const res = {
+                        kind: "sync",
+                        convert,
+                        cost,
+                    };
                     this.resolvedCache.set(cacheKey, res);
                     return res;
                 }
@@ -361,7 +403,11 @@ class Registry {
                         }
                         return acc;
                     };
-                    const res = { kind: "async", convertAsync };
+                    const res = {
+                        kind: "async",
+                        convertAsync,
+                        cost,
+                    };
                     this.resolvedCache.set(cacheKey, res);
                     return res;
                 }
@@ -818,9 +864,6 @@ class Graph {
         const edge = this.edges.find((e) => e.id === edgeId);
         if (!edge)
             return;
-        if (updates.effectiveTypeId !== undefined) {
-            edge.effectiveTypeId = updates.effectiveTypeId;
-        }
         if (updates.dstDeclared !== undefined) {
             edge.dstDeclared = updates.dstDeclared;
         }
@@ -1414,14 +1457,13 @@ function buildEdges(def, registry, resolvedByNode) {
     return def.edges.map((e) => {
         const srcNode = def.nodes.find((n) => n.nodeId === e.source.nodeId);
         const dstNode = def.nodes.find((n) => n.nodeId === e.target.nodeId);
-        const { srcDeclared, dstDeclared, effectiveTypeId } = extractEdgeTypes(e.source.nodeId, e.source.handle, e.target.nodeId, e.target.handle, resolvedByNode, e.typeId);
+        const { srcDeclared, dstDeclared } = extractEdgeTypes(e.source.nodeId, e.source.handle, e.target.nodeId, e.target.handle, resolvedByNode);
         const { convert, convertAsync } = buildEdgeConverters(srcDeclared, dstDeclared, registry, `buildEdges: ${srcNode?.typeId || ""}.${e.source.nodeId}.${e.source.handle} -> ${dstNode?.typeId || ""}.${e.target.nodeId}.${e.target.handle}`);
         return {
             id: e.id,
             source: { ...e.source },
             target: { ...e.target },
             typeId: e.typeId, // Preserve original (may be undefined)
-            effectiveTypeId, // Always present
             convert,
             convertAsync,
             srcUnionTypes: Array.isArray(srcDeclared) ? [...srcDeclared] : undefined,
@@ -1433,37 +1475,79 @@ function buildEdges(def, registry, resolvedByNode) {
 /**
  * Extract edge type information from resolved handles
  * Used by both buildEdges and updateNodeHandles to avoid duplication
+ * Now supports union types on both source (output) and destination (input) handles
  */
-function extractEdgeTypes(sourceNodeId, sourceHandle, targetNodeId, targetHandle, resolvedByNode, explicitTypeId) {
+function extractEdgeTypes(sourceNodeId, sourceHandle, targetNodeId, targetHandle, resolvedByNode) {
     const srcResolved = resolvedByNode.get(sourceNodeId);
     const dstResolved = resolvedByNode.get(targetNodeId);
     const srcDeclared = srcResolved
         ? srcResolved.outputs[sourceHandle]
         : undefined;
     const dstDeclared = dstResolved
-        ? getInputTypeId(dstResolved.inputs, targetHandle)
+        ? getInputDeclaredTypes(dstResolved.inputs, targetHandle)
         : undefined;
-    let effectiveTypeId = explicitTypeId;
-    if (!effectiveTypeId) {
-        // Infer if not explicitly set
-        effectiveTypeId = Array.isArray(srcDeclared) ? srcDeclared[0] : srcDeclared;
-    }
     return {
         srcDeclared,
         dstDeclared,
-        effectiveTypeId: effectiveTypeId ?? "untyped",
     };
 }
 // Static helper: build edge converters for type coercion
+// Now supports union types on both source (output) and destination (input) handles
 function buildEdgeConverters(srcDeclared, dstDeclared, registry, edgeLabel) {
     if (!dstDeclared || !srcDeclared) {
         return {};
     }
-    const isUnion = Array.isArray(srcDeclared);
-    const srcTypes = isUnion ? srcDeclared : [srcDeclared];
-    // Helper to get the coercion for a specific type
-    const getCoercion = (typeId) => {
-        return registry.resolveCoercion(typeId, dstDeclared);
+    const isSrcUnion = Array.isArray(srcDeclared);
+    const srcTypes = isSrcUnion ? srcDeclared : [srcDeclared];
+    const isDstUnion = Array.isArray(dstDeclared);
+    const dstTypes = isDstUnion ? dstDeclared : [dstDeclared];
+    // Helper to compare coercion costs (sync preferred, then fewer steps)
+    const compareCost = (a, b) => {
+        // Prefer sync over async
+        if (a.kind === "sync" && b.kind === "async")
+            return -1;
+        if (a.kind === "async" && b.kind === "sync")
+            return 1;
+        // If same kind, prefer fewer edges
+        if (a.cost.edges !== b.cost.edges)
+            return a.cost.edges - b.cost.edges;
+        // If same edges, prefer fewer async steps
+        return a.cost.async - b.cost.async;
+    };
+    // Helper to find the best coercion from a source type to any destination type
+    const getCoercion = (srcTypeId) => {
+        const candidates = [];
+        // Try all destination types and collect valid coercions
+        for (const dstTypeId of dstTypes) {
+            const coercion = registry.resolveCoercion(srcTypeId, dstTypeId);
+            if (coercion) {
+                candidates.push({
+                    dstType: dstTypeId,
+                    coercion,
+                });
+            }
+        }
+        if (candidates.length === 0)
+            return null;
+        // Select best by cost: sync preferred, then fewer edges, then fewer async steps
+        const best = candidates.reduce((best, cur) => {
+            return compareCost(cur.coercion, best.coercion) < 0 ? cur : best;
+        });
+        if (best.coercion.kind === "sync") {
+            return {
+                kind: "sync",
+                convert: best.coercion.convert,
+                dstType: best.dstType,
+            };
+        }
+        else {
+            return {
+                kind: "async",
+                convert: (v) => v, // placeholder, not used for async
+                convertAsync: best.coercion.convertAsync,
+                dstType: best.dstType,
+            };
+        }
     };
     // Resolve coercions for all source types
     const coercions = srcTypes.map(getCoercion);
@@ -1472,7 +1556,7 @@ function buildEdgeConverters(srcDeclared, dstDeclared, registry, edgeLabel) {
     const extractPayload = (v) => {
         const typeId = getTypedOutputTypeId(v);
         const payload = getTypedOutputValue(v);
-        if (isUnion) {
+        if (isSrcUnion) {
             if (!typeId) {
                 throw new Error(`Typed output required for union source (${edgeLabel}); allowed: ${srcTypes.join("|")}`);
             }
@@ -1486,17 +1570,27 @@ function buildEdgeConverters(srcDeclared, dstDeclared, registry, edgeLabel) {
         }
         return { typeId: typeId || srcTypes[0], payload };
     };
+    const wrapIfDstUnion = (dstType, val) => {
+        if (!isDstUnion || !dstType)
+            return val;
+        return typed(dstType, val);
+    };
     if (hasAsync) {
         return {
             convertAsync: async (v, signal) => {
                 const { typeId, payload } = extractPayload(v);
                 const res = getCoercion(typeId);
-                if (!res)
-                    return payload;
-                if (res.kind === "async") {
-                    return await res.convertAsync(payload, signal);
+                if (!res) {
+                    const fallbackType = isDstUnion && typeId && dstTypes.includes(typeId)
+                        ? typeId
+                        : undefined;
+                    return wrapIfDstUnion(fallbackType, payload);
                 }
-                return res.convert(payload);
+                if (res.kind === "async" && res.convertAsync) {
+                    const converted = await res.convertAsync(payload, signal);
+                    return wrapIfDstUnion(res.dstType, converted);
+                }
+                return wrapIfDstUnion(res.dstType, res.convert(payload));
             },
         };
     }
@@ -1509,12 +1603,17 @@ function buildEdgeConverters(srcDeclared, dstDeclared, registry, edgeLabel) {
         convert: (v) => {
             const { typeId, payload } = extractPayload(v);
             const res = getCoercion(typeId);
-            if (!res)
-                return payload;
+            if (!res) {
+                const fallbackType = isDstUnion && typeId && dstTypes.includes(typeId)
+                    ? typeId
+                    : undefined;
+                return wrapIfDstUnion(fallbackType, payload);
+            }
             if (res.kind === "async") {
                 throw new Error(`Async coercion required but convert used (${edgeLabel})`);
             }
-            return res.convert(payload);
+            const converted = res.convert(payload);
+            return wrapIfDstUnion(res.dstType, converted);
         },
     };
 }
@@ -1617,12 +1716,11 @@ class HandleResolver {
             const dstNode = this.graph.getNode(e.target.nodeId);
             const oldDstDeclared = e.dstDeclared;
             // Extract edge types using shared helper (handles both source and target updates)
-            const { srcDeclared, dstDeclared, effectiveTypeId } = extractEdgeTypes(e.source.nodeId, e.source.handle, e.target.nodeId, e.target.handle, resolvedByNode, e.typeId);
+            const { srcDeclared, dstDeclared } = extractEdgeTypes(e.source.nodeId, e.source.handle, e.target.nodeId, e.target.handle, resolvedByNode);
             // Update converters
             const conv = buildEdgeConverters(srcDeclared, dstDeclared, registry, `updateNodeHandles: ${srcNode?.typeId || ""}.${e.source.nodeId}.${e.source.handle} -> ${dstNode?.typeId || ""}.${e.target.nodeId}.${e.target.handle}`);
             // Update edge properties via Graph
             this.graph.updateEdgeProperties(e.id, {
-                effectiveTypeId: !e.typeId ? effectiveTypeId : undefined,
                 dstDeclared,
                 srcUnionTypes: Array.isArray(srcDeclared)
                     ? [...srcDeclared]
@@ -3468,20 +3566,12 @@ class GraphBuilder {
             return { inputs, outputs };
         };
         const normOut = (decl) => Array.isArray(decl) ? decl : decl ? [decl] : [];
-        const inferEdgeType = (srcDeclared, dstDeclared, explicit) => {
-            if (explicit)
-                return explicit;
-            if (Array.isArray(srcDeclared) && dstDeclared)
-                return dstDeclared;
-            if (srcDeclared)
-                return Array.isArray(srcDeclared) ? srcDeclared[0] : srcDeclared;
-            return undefined;
-        };
         const canFlow = (from, to) => {
             if (!to || !from)
                 return true;
-            const arr = Array.isArray(from) ? from : [from];
-            return arr.every((s) => s === to || !!this.registry.canCoerce(s, to));
+            const srcTypes = Array.isArray(from) ? from : [from];
+            const dstTypes = Array.isArray(to) ? to : [to];
+            return srcTypes.some((s) => dstTypes.some((t) => s === t || !!this.registry.canCoerce(s, t)));
         };
         // Helper to validate enum value
         const validateEnumValue = (typeId, value, nodeId, handle) => {
@@ -3592,37 +3682,29 @@ class GraphBuilder {
             };
             const dstEff = effByNodeId.get(e.target.nodeId) || {
                 inputs: {}};
-            const _srcDeclared = srcNode
-                ? srcEff.outputs[e.source.handle]
-                : undefined;
-            const _dstDeclared = dstNode
-                ? getInputTypeId(dstEff.inputs, e.target.handle)
-                : undefined;
-            // Effective edge type
-            const effectiveTypeId = inferEdgeType(_srcDeclared, _dstDeclared, e.typeId);
-            const type = effectiveTypeId
-                ? this.registry.types.get(effectiveTypeId)
-                : undefined;
-            if (!type) {
-                pushIssue("error", "TYPE_MISSING", `Edge ${e.id} type missing or unknown`, {
-                    edgeId: e.id,
-                });
+            // Validate explicit type if provided
+            if (e.typeId) {
+                const type = this.registry.types.get(e.typeId);
+                if (!type) {
+                    pushIssue("error", "TYPE_MISSING", `Edge ${e.id} explicit type ${e.typeId} is missing or unknown`, { edgeId: e.id });
+                }
             }
             if (srcNode) {
                 if (!(e.source.handle in srcEff.outputs)) {
                     pushIssue("error", "OUTPUT_MISSING", `Edge ${e.id} source output ${e.source.handle} missing on ${srcNode.typeId}`, { edgeId: e.id, nodeId: srcNode.nodeId, output: e.source.handle });
                 }
                 const declaredArr = normOut(srcEff.outputs[e.source.handle]);
-                if (declaredArr.length > 0 &&
-                    effectiveTypeId &&
-                    !canFlow(declaredArr, effectiveTypeId)) {
-                    pushIssue("error", "TYPE_MISMATCH_OUTPUT", `Edge ${e.id} type ${effectiveTypeId} mismatches source output ${srcNode.typeId}.${e.source.handle} (${declaredArr.join("|")}) and no coercion exists`, {
-                        edgeId: e.id,
-                        nodeId: srcNode.nodeId,
-                        output: e.source.handle,
-                        declared: declaredArr.join("|"),
-                        effectiveTypeId,
-                    });
+                if (declaredArr.length > 0) {
+                    // Check if explicit type matches source output
+                    if (e.typeId && !canFlow(declaredArr, e.typeId)) {
+                        pushIssue("error", "TYPE_MISMATCH_OUTPUT", `Edge ${e.id} explicit type ${e.typeId} mismatches source output ${srcNode.typeId}.${e.source.handle} (${declaredArr.join("|")}) and no coercion exists`, {
+                            edgeId: e.id,
+                            nodeId: srcNode.nodeId,
+                            output: e.source.handle,
+                            declared: declaredArr.join("|"),
+                            typeId: e.typeId,
+                        });
+                    }
                 }
             }
             if (dstNode) {
@@ -3633,30 +3715,30 @@ class GraphBuilder {
                 if (isInputPrivate(dstEff.inputs, e.target.handle)) {
                     pushIssue("error", "INPUT_PRIVATE", `Edge ${e.id} targets private input ${dstNode.typeId}.${e.target.handle}`, { edgeId: e.id, nodeId: dstNode.nodeId, input: e.target.handle });
                 }
-                const declaredIn = getInputTypeId(dstEff.inputs, e.target.handle);
-                if (declaredIn && effectiveTypeId) {
+                const declaredIn = getInputDeclaredTypes(dstEff.inputs, e.target.handle);
+                const declaredInArr = normOut(declaredIn);
+                if (declaredInArr.length > 0) {
                     if (srcNode) {
                         const srcDeclared = srcEff.outputs[e.source.handle];
-                        const srcArr = normOut(srcDeclared).length
-                            ? normOut(srcDeclared)
-                            : [effectiveTypeId];
-                        if (!canFlow(srcArr, declaredIn)) {
-                            pushIssue("error", "TYPE_MISMATCH_INPUT", `Edge ${e.id} output type ${srcArr.join("|")} not convertible to target input ${dstNode.typeId}.${e.target.handle} (${declaredIn})`, {
+                        const srcArr = normOut(srcDeclared);
+                        if (srcArr.length > 0 && !canFlow(srcArr, declaredInArr)) {
+                            pushIssue("error", "TYPE_MISMATCH_INPUT", `Edge ${e.id} output type ${srcArr.join("|")} not convertible to target input ${dstNode.typeId}.${e.target.handle} (${declaredInArr.join("|")})`, {
                                 edgeId: e.id,
                                 nodeId: dstNode.nodeId,
                                 input: e.target.handle,
-                                declared: declaredIn,
-                                effectiveTypeId: srcArr.join("|"),
+                                declared: declaredInArr.join("|"),
+                                typeId: srcArr.join("|"),
                             });
                         }
                     }
-                    else if (!canFlow(effectiveTypeId, declaredIn)) {
-                        pushIssue("error", "TYPE_MISMATCH_INPUT", `Edge ${e.id} type ${effectiveTypeId} mismatches target input ${dstNode.typeId}.${e.target.handle} (${declaredIn}) and no coercion exists`, {
+                    else if (e.typeId && !canFlow([e.typeId], declaredInArr)) {
+                        // External source with explicit type
+                        pushIssue("error", "TYPE_MISMATCH_INPUT", `Edge ${e.id} explicit type ${e.typeId} mismatches target input ${dstNode.typeId}.${e.target.handle} (${declaredInArr.join("|")}) and no coercion exists`, {
                             edgeId: e.id,
                             nodeId: dstNode.nodeId,
                             input: e.target.handle,
-                            declared: declaredIn,
-                            effectiveTypeId,
+                            declared: declaredInArr.join("|"),
+                            typeId: e.typeId,
                         });
                     }
                 }
@@ -5592,9 +5674,17 @@ function buildTypeMaps(def) {
         const nodeOutputTypes = new Map();
         if (node.resolvedHandles?.inputs) {
             for (const [handleId, handleDesc] of Object.entries(node.resolvedHandles.inputs)) {
-                const typeId = typeof handleDesc === "string"
-                    ? handleDesc
-                    : handleDesc?.typeId;
+                let typeId;
+                if (typeof handleDesc === "string") {
+                    typeId = handleDesc;
+                }
+                else if (Array.isArray(handleDesc)) {
+                    typeId = handleDesc[0]; // Use first type for type map (backward compat)
+                }
+                else {
+                    const descTypeId = handleDesc.typeId;
+                    typeId = Array.isArray(descTypeId) ? descTypeId[0] : descTypeId;
+                }
                 if (typeId)
                     nodeInputTypes.set(handleId, typeId);
             }
@@ -5617,9 +5707,17 @@ function buildTypeMaps(def) {
                 if (!nodeInputTypes.has(handleId) && node.resolvedHandles?.inputs) {
                     const inputDesc = node.resolvedHandles.inputs[handleId];
                     if (inputDesc) {
-                        const typeId = typeof inputDesc === "string"
-                            ? inputDesc
-                            : inputDesc?.typeId;
+                        let typeId;
+                        if (typeof inputDesc === "string") {
+                            typeId = inputDesc;
+                        }
+                        else if (Array.isArray(inputDesc)) {
+                            typeId = inputDesc[0]; // Use first type for type map (backward compat)
+                        }
+                        else {
+                            const descTypeId = inputDesc.typeId;
+                            typeId = Array.isArray(descTypeId) ? descTypeId[0] : descTypeId;
+                        }
                         if (typeId)
                             nodeInputTypes.set(handleId, typeId);
                     }
@@ -6078,6 +6176,7 @@ exports.createValidationGraphDef = createValidationGraphDef;
 exports.createValidationGraphRegistry = createValidationGraphRegistry;
 exports.findMatchingPaths = findMatchingPaths;
 exports.generateId = generateId;
+exports.getInputDeclaredTypes = getInputDeclaredTypes;
 exports.getInputHandleMetadata = getInputHandleMetadata;
 exports.getInputTypeId = getInputTypeId;
 exports.getTypedOutputTypeId = getTypedOutputTypeId;