@api-client/core 0.18.16 → 0.18.18

package/src/modeling/DomainSerialization.ts

@@ -1,6 +1,15 @@
 import type { JsonEdge, Node } from '@api-client/graph/graph/types.js'
 import { Graph } from '@api-client/graph/graph/Graph.js'
-import type { DataDomainGraph, DomainGraphEdge, DomainGraphNodeType, SerializedGraph } from './types.js'
+import type {
+  DataDomainGraph,
+  DomainGraphEdge,
+  DomainGraphNodeType,
+  SerializedGraph,
+  DeserializationMode,
+  DeserializationResult,
+  DeserializationIssue,
+  DeserializeOptions,
+} from './types.js'
 import {
   DomainAssociationKind,
   DomainEntityKind,
@@ -78,7 +87,152 @@ function writeEdges(g: DataDomainGraph, domainKey: string): JsonEdge<DomainGraph
   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: DataDomainGraph, domainKey: string): void {
+  const validationErrors: string[] = []
+
+  // Get all nodes that belong to this domain
+  const domainNodes = new Set<string>()
+  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 as DomainAssociation
+      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: DataDomainGraph, domainKey: string): SerializedGraph {
+  // Validate graph consistency before serialization
+  validateGraphConsistency(g, domainKey)
+
   const json: SerializedGraph = {
     options: {
       directed: g.isDirected(),
@@ -198,43 +352,124 @@ function findEdgeParent(child: string, edges: JsonEdge<DomainGraphEdge>[]): stri
  * @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: DataDomain, entry: unknown, edges: JsonEdge<DomainGraphEdge>[]): DomainGraphNodeType {
+function prepareNode(
+  root: DataDomain,
+  entry: unknown,
+  edges: JsonEdge<DomainGraphEdge>[],
+  mode: DeserializationMode,
+  issues: DeserializationIssue[]
+): DomainGraphNodeType | undefined {
   if (!entry) {
-    throw new Error(`Unable to restore data domain graph. Malformed node entry`)
+    const issue: DeserializationIssue = {
+      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 as { kind?: string }
+
+  const domainElement = entry as { kind?: string; key?: string }
   if (!domainElement.kind) {
-    throw new Error(`Unable to restore data domain graph. Malformed node entry`)
-  }
-  if (domainElement.kind === DomainNamespaceKind) {
-    return new DomainNamespace(root, domainElement as DomainNamespaceSchema)
-  }
-  if (domainElement.kind === DomainModelKind) {
-    return new DomainModel(root, domainElement as DomainModelSchema)
-  }
-  if (domainElement.kind === DomainEntityKind) {
-    return new DomainEntity(root, domainElement as DomainEntitySchema)
-  }
-  if (domainElement.kind === DomainPropertyKind) {
-    const typed = domainElement as DomainPropertySchema
-    const parent = findEdgeParent(typed.key, edges)
-    if (!parent) {
-      throw new Error(`Unable to restore data domain graph. Malformed node entry`)
+    const issue: DeserializationIssue = {
+      type: 'malformed_entry',
+      severity: 'error',
+      message: 'Unable to restore data domain graph. Node entry missing kind property',
+      affectedKey: domainElement.key,
     }
-    return new DomainProperty(root, parent, typed)
+    issues.push(issue)
+
+    if (mode === 'strict') {
+      throw new Error(issue.message)
+    }
+    return undefined
   }
-  if (domainElement.kind === DomainAssociationKind) {
-    const typed = domainElement as DomainAssociationSchema
-    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 as DomainNamespaceSchema)
+    }
+    if (domainElement.kind === DomainModelKind) {
+      return new DomainModel(root, domainElement as DomainModelSchema)
+    }
+    if (domainElement.kind === DomainEntityKind) {
+      return new DomainEntity(root, domainElement as DomainEntitySchema)
+    }
+    if (domainElement.kind === DomainPropertyKind) {
+      const typed = domainElement as DomainPropertySchema
+      const parent = findEdgeParent(typed.key, edges)
+      if (!parent) {
+        const issue: DeserializationIssue = {
+          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 as DomainAssociationSchema
+      const parent = findEdgeParent(typed.key, edges)
+      if (!parent) {
+        const issue: DeserializationIssue = {
+          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: DeserializationIssue = {
+      type: 'unknown_kind',
+      severity: 'error',
+      message: `Unknown node kind: ${domainElement.kind}`,
+      affectedKey: domainElement.key,
     }
-    return new DomainAssociation(root, parent, typed)
+    issues.push(issue)
+
+    if (mode === 'strict') {
+      throw new Error(`Unable to restore data domain graph. Unknown node kind ${domainElement.kind}`)
+    }
+    return undefined
+  } catch (error) {
+    const issue: DeserializationIssue = {
+      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 undefined
   }
-  throw new Error(`Unable to restore data domain graph. Unknown node kind ${domainElement.kind}`)
 }
 
 /**
@@ -246,74 +481,223 @@ function prepareNode(root: DataDomain, entry: unknown, edges: JsonEdge<DomainGra
  *
  * @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: DataDomain, json?: SerializedGraph, dependencies?: DataDomain[]): DataDomainGraph {
+export function deserialize(root: DataDomain, options: DeserializeOptions = {}): DeserializationResult {
+  const { json, dependencies, mode = 'strict' } = options
   const g = new Graph<unknown, DomainGraphNodeType, DomainGraphEdge>({
     compound: true,
     multigraph: true,
     directed: true,
   })
+  const issues: DeserializationIssue[] = []
   let foreignNodes = new Set<string>()
   let foreignEdges = new Set<string>()
+
+  // 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])
-      }
-      if (result.nodes.size) {
-        foreignNodes = new Set([...foreignNodes, ...result.nodes])
+      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)
+      } 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: DeserializationIssue = {
+          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<string, string[]>()
     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: DeserializationIssue = {
+          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: DeserializationIssue = {
+            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: DeserializationIssue = {
+            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: DeserializationIssue = {
+          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: DeserializationIssue = {
+            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: DeserializationIssue = {
+            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: DeserializationIssue = {
+            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: DeserializationIssue = {
+            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: DeserializationIssue = {
+          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,
+  }
 }

package/src/modeling/types.ts

@@ -13,6 +13,7 @@ import type {
   DomainAssociationKind,
   DataDomainKind,
 } from '../models/kinds.js'
+import type { DataDomain } from './DataDomain.js'
 
 export interface DataDomainRemoveOptions {
   /**
@@ -55,7 +56,7 @@ export interface DomainGraphEdge {
   /**
    * The type of the edge.
    * - `association` The edge is to an association object.
-   *   - When coming **from** an entiry (the `v` property), that entity owns the association.
+   *   - When coming **from** an entity (the `v` property), that entity owns the association.
    *   - When coming **to** an entity (the `w` property), that entity is the target of the association.
    *     An association can have multiple targets.
    * - `property` The edge is to a property object. Can only be created between an entity and a property.
@@ -684,7 +685,7 @@ export interface MatchUserPropertyAccessRule extends BaseAccessRule {
 /**
  * The action is allowed if the authenticated user's email domain matches a specific domain.
  * This is used to restrict access based on the user's email address.
- * For example, only users with an email address from "mycompany.com" can access certain resources.
+ * For example, only users with an email address from "my-company.com" can access certain resources.
  */
 export interface MatchEmailDomainAccessRule extends BaseAccessRule {
   type: 'matchEmailDomain'
@@ -822,3 +823,73 @@ export interface DomainImpactItem {
    */
   parent?: string
 }
+
+export interface DeserializeOptions {
+  /**
+   * The mode to use for deserialization.
+   */
+  mode?: DeserializationMode
+  /**
+   * The serialized graph to deserialize.
+   * This is the JSON representation of the graph.
+   */
+  json?: SerializedGraph
+  /**
+   * The list of foreign domains that this domain depends on.
+   */
+  dependencies?: DataDomain[]
+}
+
+/**
+ * Describes the mode for deserializing a domain graph.
+ */
+export type DeserializationMode = 'strict' | 'lenient'
+
+/**
+ * Describes an issue found during deserialization.
+ */
+export interface DeserializationIssue {
+  /**
+   * The type of issue encountered.
+   */
+  type: 'missing_node' | 'missing_edge' | 'invalid_parent' | 'missing_dependency' | 'malformed_entry' | 'unknown_kind'
+  /**
+   * The severity of the issue.
+   */
+  severity: 'error' | 'warning' | 'info'
+  /**
+   * A human-readable description of the issue.
+   */
+  message: string
+  /**
+   * The key of the affected node, edge, or entity if applicable.
+   */
+  affectedKey?: string
+  /**
+   * Additional context about the issue.
+   */
+  context?: Record<string, unknown>
+  /**
+   * The action taken to handle this issue in lenient mode.
+   */
+  resolution?: string
+}
+
+/**
+ * The result of a deserialization operation.
+ */
+export interface DeserializationResult {
+  /**
+   * The deserialized graph.
+   */
+  graph: DataDomainGraph
+  /**
+   * Issues encountered during deserialization.
+   */
+  issues: DeserializationIssue[]
+  /**
+   * Whether the deserialization was successful.
+   * This is set to true when a critical failures occurred.
+   */
+  success: boolean
+}

package/src/models/Thing.ts

@@ -1,6 +1,6 @@
 import { ThingKind } from './kinds.js'
 import { ModelValidationOptions } from './types.js'
-import { observed } from '../modeling/observed.js'
+import { observed } from '../decorators/observed.js'
 
 /**
  * An interface describing a base metadata of a thing.