@api-client/core 0.18.16 → 0.18.18

package/build/src/modeling/DomainSerialization.js

@@ -55,7 +55,125 @@ function writeEdges(g, domainKey) {
     }
     return result;
 }
+/**
+ * Validates the graph consistency before serialization.
+ * Ensures that all required edges exist for properties and associations.
+ * @param g The graph to validate
+ * @param domainKey The domain key to validate
+ * @throws Error if the graph is inconsistent
+ */
+function validateGraphConsistency(g, domainKey) {
+    const validationErrors = [];
+    // Get all nodes that belong to this domain
+    const domainNodes = new Set();
+    for (const nodeId of g.nodes()) {
+        const node = g.node(nodeId);
+        if (node && node.domain.key === domainKey) {
+            domainNodes.add(nodeId);
+        }
+    }
+    // Validate that properties and associations have parent edges
+    for (const nodeId of domainNodes) {
+        const node = g.node(nodeId);
+        if (!node)
+            continue;
+        if (node.kind === DomainPropertyKind || node.kind === DomainAssociationKind) {
+            // These nodes must have exactly one incoming edge from their parent entity
+            const incomingEdges = [...g.inEdges(nodeId)];
+            const parentEdges = incomingEdges.filter((edge) => {
+                const sourceNode = g.node(edge.v);
+                return sourceNode && sourceNode.domain.key === domainKey;
+            });
+            if (parentEdges.length === 0) {
+                const nodeType = node.kind === DomainPropertyKind ? 'Property' : 'Association';
+                validationErrors.push(`${nodeType} "${node.info.name}" (${nodeId}) has no parent entity edge. ` +
+                    `This will cause deserialization to fail.`);
+            }
+            else if (parentEdges.length > 1) {
+                const nodeType = node.kind === DomainPropertyKind ? 'Property' : 'Association';
+                const parentIds = parentEdges.map((e) => e.v).join(', ');
+                validationErrors.push(`${nodeType} "${node.info.name}" (${nodeId}) has multiple parent edges: ${parentIds}. ` +
+                    `This may cause deserialization issues.`);
+            }
+            else {
+                // Validate that the parent is actually an entity
+                const parentEdge = parentEdges[0];
+                const parentNode = g.node(parentEdge.v);
+                if (!parentNode || parentNode.kind !== DomainEntityKind) {
+                    const nodeType = node.kind === DomainPropertyKind ? 'Property' : 'Association';
+                    validationErrors.push(`${nodeType} "${node.info.name}" (${nodeId}) has a parent that is not an entity. ` +
+                        `Parent: ${parentNode?.kind || 'unknown'} (${parentEdge.v})`);
+                }
+            }
+        }
+        // Validate that entities have model parents
+        if (node.kind === DomainEntityKind) {
+            const parents = [...g.parents(nodeId)];
+            const hasModelParent = parents.some((parentId) => {
+                const parent = g.node(parentId);
+                return parent && parent.kind === DomainModelKind;
+            });
+            if (!hasModelParent) {
+                validationErrors.push(`Entity "${node.info.name}" (${nodeId}) has no model parent. ` + `Entities must belong to a model.`);
+            }
+        }
+        // Validate that models have either namespace parents or are at root level
+        if (node.kind === DomainModelKind) {
+            const parents = [...g.parents(nodeId)];
+            const hasNamespaceParent = parents.some((parentId) => {
+                const parent = g.node(parentId);
+                return parent && parent.kind === DomainNamespaceKind;
+            });
+            // Models can either be at root level (no parents) or have a namespace parent
+            // They should not have other types of parents
+            if (parents.length > 0 && !hasNamespaceParent) {
+                const invalidParents = parents
+                    .map((parentId) => {
+                    const parent = g.node(parentId);
+                    return `${parent?.kind || 'unknown'} (${parentId})`;
+                })
+                    .join(', ');
+                validationErrors.push(`Model "${node.info.name}" (${nodeId}) has invalid parent types: ${invalidParents}. ` +
+                    `Models can only belong to namespaces or be at root level.`);
+            }
+        }
+    }
+    // Validate association targets exist
+    for (const nodeId of domainNodes) {
+        const node = g.node(nodeId);
+        if (node && node.kind === DomainAssociationKind) {
+            const association = node;
+            const outgoingEdges = [...g.outEdges(nodeId)];
+            // Check that association has target edges
+            const targetEdges = outgoingEdges.filter((edge) => {
+                const edgeData = g.edge(edge);
+                return edgeData && edgeData.type === 'association';
+            });
+            if (targetEdges.length === 0) {
+                // This is general warning message, do not an error.
+                // We can serialize and deserialize associations without targets.
+            }
+            // Validate that all target entities exist
+            for (const targetEdge of targetEdges) {
+                const targetNode = g.node(targetEdge.w);
+                if (!targetNode) {
+                    validationErrors.push(`Association "${association.info.name}" (${nodeId}) references non-existent target: ${targetEdge.w}`);
+                }
+                else if (targetNode.kind !== DomainEntityKind) {
+                    validationErrors.push(`Association "${association.info.name}" (${nodeId}) references non-entity target: ` +
+                        `${targetNode.kind} (${targetEdge.w})`);
+                }
+            }
+        }
+    }
+    if (validationErrors.length > 0) {
+        throw new Error(`Graph consistency validation failed for domain "${domainKey}":\n` +
+            validationErrors.map((error) => `  - ${error}`).join('\n'));
+    }
+}
 export function serialize(g, domainKey) {
+    // Validate graph consistency before serialization
+    validateGraphConsistency(g, domainKey);
     const json = {
         options: {
             directed: g.isDirected(),
@@ -173,43 +291,111 @@ function findEdgeParent(child, edges) {
  * @param root The DataDomain instance to use as the root for the graph
  * @param entry The node entry to restore
  * @param edges The list of serialized graph edges
- * @returns The restored node instance
- * @throws Error if the entry is malformed or the kind is unknown
+ * @param mode The deserialization mode
+ * @param issues Array to collect issues in lenient mode
+ * @returns The restored node instance or undefined if failed in lenient mode
+ * @throws Error if the entry is malformed or the kind is unknown in strict mode
  */
-function prepareNode(root, entry, edges) {
+function prepareNode(root, entry, edges, mode, issues) {
     if (!entry) {
-        throw new Error(`Unable to restore data domain graph. Malformed node entry`);
+        const issue = {
+            type: 'malformed_entry',
+            severity: 'error',
+            message: 'Unable to restore data domain graph. Malformed node entry',
+        };
+        issues.push(issue);
+        if (mode === 'strict') {
+            throw new Error(issue.message);
+        }
+        return undefined;
     }
     const domainElement = entry;
     if (!domainElement.kind) {
-        throw new Error(`Unable to restore data domain graph. Malformed node entry`);
-    }
-    if (domainElement.kind === DomainNamespaceKind) {
-        return new DomainNamespace(root, domainElement);
-    }
-    if (domainElement.kind === DomainModelKind) {
-        return new DomainModel(root, domainElement);
-    }
-    if (domainElement.kind === DomainEntityKind) {
-        return new DomainEntity(root, domainElement);
+        const issue = {
+            type: 'malformed_entry',
+            severity: 'error',
+            message: 'Unable to restore data domain graph. Node entry missing kind property',
+            affectedKey: domainElement.key,
+        };
+        issues.push(issue);
+        if (mode === 'strict') {
+            throw new Error(issue.message);
+        }
+        return undefined;
     }
-    if (domainElement.kind === DomainPropertyKind) {
-        const typed = domainElement;
-        const parent = findEdgeParent(typed.key, edges);
-        if (!parent) {
-            throw new Error(`Unable to restore data domain graph. Malformed node entry`);
+    try {
+        if (domainElement.kind === DomainNamespaceKind) {
+            return new DomainNamespace(root, domainElement);
         }
-        return new DomainProperty(root, parent, typed);
+        if (domainElement.kind === DomainModelKind) {
+            return new DomainModel(root, domainElement);
+        }
+        if (domainElement.kind === DomainEntityKind) {
+            return new DomainEntity(root, domainElement);
+        }
+        if (domainElement.kind === DomainPropertyKind) {
+            const typed = domainElement;
+            const parent = findEdgeParent(typed.key, edges);
+            if (!parent) {
+                const issue = {
+                    type: 'missing_edge',
+                    severity: 'error',
+                    message: `Property "${typed.info?.name || typed.key}" has no parent entity edge`,
+                    affectedKey: typed.key,
+                    resolution: mode === 'lenient' ? 'Property will be skipped' : undefined,
+                };
+                issues.push(issue);
+                if (mode === 'strict') {
+                    throw new Error(`Unable to restore data domain graph. Malformed node entry`);
+                }
+                return undefined;
+            }
+            return new DomainProperty(root, parent, typed);
+        }
+        if (domainElement.kind === DomainAssociationKind) {
+            const typed = domainElement;
+            const parent = findEdgeParent(typed.key, edges);
+            if (!parent) {
+                const issue = {
+                    type: 'missing_edge',
+                    severity: 'error',
+                    message: `Association "${typed.info?.name || typed.key}" has no parent entity edge`,
+                    affectedKey: typed.key,
+                    resolution: mode === 'lenient' ? 'Association will be skipped' : undefined,
+                };
+                issues.push(issue);
+                if (mode === 'strict') {
+                    throw new Error(`Unable to restore data domain graph. Malformed node entry`);
+                }
+                return undefined;
+            }
+            return new DomainAssociation(root, parent, typed);
+        }
+        const issue = {
+            type: 'unknown_kind',
+            severity: 'error',
+            message: `Unknown node kind: ${domainElement.kind}`,
+            affectedKey: domainElement.key,
+        };
+        issues.push(issue);
+        if (mode === 'strict') {
+            throw new Error(`Unable to restore data domain graph. Unknown node kind ${domainElement.kind}`);
+        }
+        return undefined;
     }
-    if (domainElement.kind === DomainAssociationKind) {
-        const typed = domainElement;
-        const parent = findEdgeParent(typed.key, edges);
-        if (!parent) {
-            throw new Error(`Unable to restore data domain graph. Malformed node entry`);
+    catch (error) {
+        const issue = {
+            type: 'malformed_entry',
+            severity: 'error',
+            message: `Failed to create node: ${error instanceof Error ? error.message : String(error)}`,
+            affectedKey: domainElement.key,
+        };
+        issues.push(issue);
+        if (mode === 'strict') {
+            throw error;
         }
-        return new DomainAssociation(root, parent, typed);
+        return undefined;
     }
-    throw new Error(`Unable to restore data domain graph. Unknown node kind ${domainElement.kind}`);
 }
 /**
  * To deserialize a graph:
@@ -220,75 +406,211 @@ function prepareNode(root, entry, edges) {
  *
  * @param root The DataDomain instance to use as the root for the graph
  * @param json The previously serialized graph
- * @returns Deserialized graph instance
+ * @param dependencies An array of foreign data domains to register with this domain
+ * @param mode The deserialization mode - 'strict' throws errors, 'lenient' collects issues
+ * @returns DeserializationResult with graph, issues, and success status
+ * @throws Error in strict mode when any issue is encountered
  */
-export function deserialize(root, json, dependencies) {
+export function deserialize(root, options = {}) {
+    const { json, dependencies, mode = 'strict' } = options;
     const g = new Graph({
         compound: true,
         multigraph: true,
         directed: true,
     });
+    const issues = [];
     let foreignNodes = new Set();
     let foreignEdges = new Set();
+    // Process dependencies
     if (dependencies) {
         for (const dependency of dependencies) {
-            const result = mergeGraph(g, dependency.graph, dependency.key);
-            if (result.edges.size) {
-                foreignEdges = new Set([...foreignEdges, ...result.edges]);
+            try {
+                const result = mergeGraph(g, dependency.graph, dependency.key);
+                if (result.edges.size) {
+                    foreignEdges = new Set([...foreignEdges, ...result.edges]);
+                }
+                if (result.nodes.size) {
+                    foreignNodes = new Set([...foreignNodes, ...result.nodes]);
+                }
+                root.dependencies.set(dependency.key, dependency);
             }
-            if (result.nodes.size) {
-                foreignNodes = new Set([...foreignNodes, ...result.nodes]);
+            catch (error) {
+                const message = `Failed to merge dependency "${dependency.key}": ${error instanceof Error ? error.message : String(error)}`;
+                if (mode === 'strict') {
+                    throw new Error(message);
+                }
+                const issue = {
+                    type: 'missing_dependency',
+                    severity: 'error',
+                    message,
+                    affectedKey: dependency.key,
+                    resolution: 'Dependency will be skipped',
+                };
+                issues.push(issue);
             }
-            root.dependencies.set(dependency.key, dependency);
         }
     }
     if (!json) {
-        return g;
+        return {
+            graph: g,
+            issues,
+            success: true,
+        };
     }
+    // Process nodes
     if (Array.isArray(json.nodes)) {
         // 1st pass - set up nodes
         const parentInfo = new Map();
         for (const entry of json.nodes) {
-            g.setNode(entry.v, prepareNode(root, entry.value, json.edges));
-            if (entry.parents) {
-                parentInfo.set(entry.v, entry.parents);
+            const node = prepareNode(root, entry.value, json.edges, mode, issues);
+            if (node) {
+                g.setNode(entry.v, node);
+                if (entry.parents) {
+                    parentInfo.set(entry.v, entry.parents);
+                }
             }
+            // Note: prepareNode throws in strict mode, so we won't reach here if there's an error
         }
         // 2nd pass - set up parents
         for (const [key, parents] of parentInfo) {
-            // In data domain graph, all nodes that can have parents can only have a single parent.
-            // It's the business logic of the library.
-            // Parent-child relationships:
-            // - Namespace -> Namespace
-            // - Namespace -> Model
-            // - Model -> Entity
-            // Entities and Association are associated with the parent entity through edges.
+            // Verify the node still exists (might have been skipped in lenient mode)
+            if (!g.hasNode(key)) {
+                const issue = {
+                    type: 'missing_node',
+                    severity: 'warning',
+                    message: `Cannot set parents for missing node: ${key}`,
+                    affectedKey: key,
+                    resolution: 'Parent relationship will be skipped',
+                };
+                issues.push(issue);
+                continue;
+            }
             for (const parent of parents) {
-                g.setParent(key, parent);
+                // Verify parent exists
+                if (!g.hasNode(parent)) {
+                    const issue = {
+                        type: 'missing_node',
+                        severity: 'warning',
+                        message: `Parent node "${parent}" not found for child "${key}"`,
+                        affectedKey: key,
+                        context: { parentKey: parent },
+                        resolution: 'Parent relationship will be skipped',
+                    };
+                    issues.push(issue);
+                    continue;
+                }
+                try {
+                    g.setParent(key, parent);
+                }
+                catch (error) {
+                    const message = `Failed to set parent "${parent}" for child "${key}": ${error instanceof Error ? error.message : String(error)}`;
+                    const issue = {
+                        type: 'invalid_parent',
+                        severity: 'warning',
+                        message,
+                        affectedKey: key,
+                        context: { parentKey: parent },
+                        resolution: 'Parent relationship will be skipped',
+                    };
+                    issues.push(issue);
+                }
             }
         }
     }
+    // Process edges
     if (Array.isArray(json.edges)) {
         for (const entry of json.edges) {
             if (!entry.value) {
-                throw new Error(`Unable to restore data domain graph. Malformed edge entry`);
+                const message = 'Edge entry missing value';
+                if (mode === 'strict') {
+                    throw new Error(message);
+                }
+                const issue = {
+                    type: 'malformed_entry',
+                    severity: 'error',
+                    message,
+                    context: { edge: entry },
+                };
+                issues.push(issue);
+                continue;
             }
+            // Handle foreign edges
             if (entry.value.foreign) {
                 // The `v` has to be local to the graph. The `w` must be foreign.
                 if (!foreignNodes.has(entry.w)) {
-                    // console.warn(`Missing foreign node: ${entry.w}. Skipping edge.`)
+                    // Note, we don't consider this an error, just a warning.
+                    // Because of that, we don't throw an error here.
+                    const issue = {
+                        type: 'missing_node',
+                        severity: 'warning',
+                        message: `Missing foreign node: ${entry.w}`,
+                        affectedKey: entry.w,
+                        resolution: 'Edge will be skipped',
+                    };
+                    issues.push(issue);
                     continue;
                 }
             }
+            // Check if nodes exist for the edge
             if (foreignNodes.has(entry.v) || foreignNodes.has(entry.w)) {
                 if (!g.hasNode(entry.v) || !g.hasNode(entry.w)) {
-                    // console.warn(`Missing foreign node: ${entry.v} or ${entry.w}. Skipping edge.`)
+                    const issue = {
+                        type: 'missing_node',
+                        severity: 'warning',
+                        message: `Missing foreign node for edge: ${entry.v} -> ${entry.w}`,
+                        context: { sourceNode: entry.v, targetNode: entry.w },
+                        resolution: 'Edge will be skipped',
+                    };
+                    issues.push(issue);
+                    continue;
+                }
+            }
+            else {
+                // Both nodes should be local - verify they exist
+                if (!g.hasNode(entry.v)) {
+                    const issue = {
+                        type: 'missing_node',
+                        severity: 'warning',
+                        message: `Source node not found for edge: ${entry.v}`,
+                        affectedKey: entry.v,
+                        resolution: 'Edge will be skipped',
+                    };
+                    issues.push(issue);
+                    continue;
+                }
+                if (!g.hasNode(entry.w)) {
+                    const issue = {
+                        type: 'missing_node',
+                        severity: 'warning',
+                        message: `Target node not found for edge: ${entry.w}`,
+                        affectedKey: entry.w,
+                        resolution: 'Edge will be skipped',
+                    };
+                    issues.push(issue);
                     continue;
                 }
             }
-            g.setEdge({ v: entry.v, w: entry.w, name: entry.name }, entry.value);
+            try {
+                g.setEdge({ v: entry.v, w: entry.w, name: entry.name }, entry.value);
+            }
+            catch (error) {
+                const message = `Failed to create edge ${entry.v} -> ${entry.w}: ${error instanceof Error ? error.message : String(error)}`;
+                const issue = {
+                    type: 'malformed_entry',
+                    severity: 'warning',
+                    message,
+                    context: { sourceNode: entry.v, targetNode: entry.w },
+                    resolution: 'Edge will be skipped',
+                };
+                issues.push(issue);
+            }
         }
     }
-    return g;
+    const hasErrors = issues.some((issue) => issue.severity === 'error');
+    return {
+        graph: g,
+        issues,
+        success: !hasErrors,
+    };
 }
 //# sourceMappingURL=DomainSerialization.js.map