@api-client/core 0.12.1 → 0.12.3

package/src/modeling/DataDomain.ts

@@ -868,6 +868,18 @@ export class DataDomain extends EventTarget {
     }
   }
 
+  /**
+   * Lists all entities in the graph that are not part of this domain.
+   */
+  *listForeignEntities(): Generator<DomainEntity> {
+    for (const node of this.graph.nodes()) {
+      const value = this.graph.node(node) as DomainGraphNodeType
+      if (value.kind === DomainEntityKind && value.domain.key !== this.key) {
+        yield value
+      }
+    }
+  }
+
   /**
    * Finds an entity by its key.
    *

package/src/modeling/DomainAssociation.ts

@@ -150,7 +150,7 @@ export class DomainAssociation extends DomainElement {
    */
   static createSchema(input: Partial<DomainAssociationSchema> = {}): DomainAssociationSchema {
     const { key = nanoid() } = input
-    const info = Thing.fromJSON(input.info, { name: 'New association' }).toJSON()
+    const info = Thing.fromJSON(input.info, { name: 'new_association' }).toJSON()
     const result: DomainAssociationSchema = {
       kind: DomainAssociationKind,
       key,

package/src/modeling/DomainEntity.ts

@@ -92,6 +92,35 @@ export interface DomainEntitySchema extends DomainElementSchema {
  * const userModel = dataDomain.addModel({ key: 'userModel' });
  * const userEntity = userModel.addEntity({ key: 'user' });
  * ```
+ *
+ * Entity Validation Rules:
+ *
+ * - **Primary Key:** An entity must have a primary key selected. This can come from a parent
+ *   entity or be defined in the current entity.
+ * - **Parent Entity:** The parent entity must exist in the graph.
+ * - **Circular Dependency:** Adding a parent entity that creates a circular dependency is not allowed.
+ * - **Unique Parent:** An entity cannot have the same parent more than once.
+ * - **Property Shadowing:** A property can shadow a parent property. This means that if a property
+ *   with the same key exists in both the parent and child entity, the child property will take precedence.
+ * - **Association Shadowing:** An association can shadow a parent association. This means that if an
+ *   association with the same key exists in both the parent and child entity,
+ *   the child association will take precedence.
+ * - **Property Resolution:** When the same property exists more than one parent and the child entity,
+ *   doesn't explicitly define the property, then:
+ *   - The last parent entity (iterating from the first entity to the last) that has the property
+ *     will be used as the source of the property.
+ * - **Association Resolution:** When the same association exists more than one parent and the child entity,
+ *   doesn't explicitly define the association, then:
+ *   - The last parent entity (iterating from the first entity to the last) that has the association
+ *     will be used as the source of the association.
+ * - **Minimum Required Properties:** An entity must have at least one property defined. Entities without properties
+ *   are ignored in the system.
+ * - **Entity Name**:
+ *   - An entity must have a name defined.
+ *   - The name has to follow the same rules as the names in a SQL database. This means that the name must be unique
+ *     within the data domain and cannot contain special characters.
+ * - **Association Targets:** An association must have a target entity defined.
+ *   This means that the association must point to at least one entity.
  */
 export class DomainEntity extends DomainElement {
   /**
@@ -291,6 +320,13 @@ export class DomainEntity extends DomainElement {
     this.root.notifyChange()
   }
 
+  /**
+   * A shortcut to `listProperties()`.
+   */
+  get properties(): Generator<DomainProperty> {
+    return this.listProperties()
+  }
+
   /**
    * Lists all properties of this entity.
    *
@@ -333,6 +369,13 @@ export class DomainEntity extends DomainElement {
     return this.fields.some((item) => item.type === 'property')
   }
 
+  /**
+   * A shortcut to `listParents()`.
+   */
+  get parents(): Generator<DomainEntity> {
+    return this.listParents()
+  }
+
   /**
    * Lists all parent entities of this entity.
    *
@@ -622,6 +665,13 @@ export class DomainEntity extends DomainElement {
     this.root.notifyChange()
   }
 
+  /**
+   * A shortcut to `listAssociations()`.
+   */
+  get associations(): Generator<DomainAssociation> {
+    return this.listAssociations()
+  }
+
   /**
    * Lists all associations of this entity.
    *
@@ -766,4 +816,29 @@ export class DomainEntity extends DomainElement {
     }
     return parent.isChildOf(key)
   }
+
+  /**
+   * Finds the primary key property of this entity.
+   * @returns The primary key property of this entity or undefined if not found.
+   */
+  primaryKey(): DomainProperty | undefined {
+    for (const property of this.properties) {
+      if (property.primary) {
+        return property
+      }
+    }
+    let property: DomainProperty | undefined
+    for (const parent of this.listParents()) {
+      const prop = parent.primaryKey()
+      if (prop) {
+        // According to the validation rules, the last parent
+        // that has the property will be used as the source of
+        // the property.
+        // In the future, we may add a schema definition to the entity that
+        // will explicitly define which property to use.
+        property = prop
+      }
+    }
+    return property
+  }
 }

package/src/modeling/DomainImpactAnalysis.ts

@@ -7,6 +7,9 @@ import {
   DataDomainKind,
 } from '../models/kinds.js'
 import type { DataDomain } from './DataDomain.js'
+import { AssociationValidation } from './validation/association_validation.js'
+import { EntityValidation } from './validation/entity_validation.js'
+import { PropertyValidation } from './validation/property_validation.js'
 
 export type DomainImpactKinds =
   | typeof DomainNamespaceKind
@@ -55,14 +58,26 @@ export interface DomainImpactItem {
    *
    * - `delete` - The data object would be deleted.
    */
-  type: 'delete'
+  type: 'delete' | 'publish'
   /**
    * The impact description.
+   * Explains what will happen to the impacted data object.
+   * This is a human-readable description of the impact.
+   * It should be clear and concise.
    */
   impact: string
+  /**
+   * The severity of the impact.
+   *
+   * - `info` - The impact is informational.
+   * - `warning` - The impact can potentially cause problems but is not a blocker.
+   * - `error` - The impact is a blocker and needs to be resolved before proceeding.
+   */
+  severity: 'info' | 'warning' | 'error'
   /**
    * Whether the impact is blocking the operation.
    * If true, the operation cannot proceed.
+   * @deprecated Use `severity` instead.
    */
   blocking: boolean
   /**
@@ -73,6 +88,11 @@ export interface DomainImpactItem {
    * The resolution of the conflict if the change will be forced.
    */
   resolution?: string
+  /**
+   * The optional parent of the impacted data object.
+   * For example, if the impacted item is a property, this will be the entity it belongs to.
+   */
+  parent?: string
 }
 
 /**
@@ -317,7 +337,7 @@ export class DomainImpactAnalysis {
       impact: [],
       canProceed: true,
     }
-    this.report.impact = this.createDeleteImpact(key, kind, key)
+    this.createDeleteImpact(key, kind, key)
     return this.report
   }
 
@@ -333,83 +353,156 @@ export class DomainImpactAnalysis {
       impact: [],
       canProceed: true,
     }
-    this.report.impact = this.createRemoveForeignNamespaceImpact(key)
+    this.createRemoveForeignNamespaceImpact(key)
+    return this.report
+  }
+
+  /**
+   * Analyzes the data domain for publishing. Essentially, it performs a validation of the data domain
+   * and returns a report of the impact.
+   * @returns The publish impact analysis report.
+   */
+  publishAnalysis(): DomainImpactReport {
+    this.report = {
+      key: '',
+      kind: DataDomainKind,
+      impact: [],
+      canProceed: true,
+    }
+    const entityValidator = new EntityValidation(this.root)
+    const propertyValidator = new PropertyValidation(this.root)
+    const associationValidator = new AssociationValidation(this.root)
+    for (const entity of this.root.listEntities()) {
+      if (entity.domain.key !== this.root.key) {
+        // we don't need to validate foreign entities
+        continue
+      }
+      const report = entityValidator.validate(entity)
+      for (const item of report) {
+        const blocking = item.severity === 'error'
+        this.report.canProceed = this.report.canProceed && !blocking
+        this.report.impact.push({
+          key: item.key,
+          kind: item.kind,
+          type: 'publish',
+          impact: item.message,
+          blocking,
+          resolution: item.help,
+          severity: item.severity,
+          parent: item.parent,
+        })
+      }
+      for (const property of entity.properties) {
+        const report = propertyValidator.validate(property)
+        for (const item of report) {
+          const blocking = item.severity === 'error'
+          this.report.canProceed = this.report.canProceed && !blocking
+          this.report.impact.push({
+            key: item.key,
+            kind: item.kind,
+            type: 'publish',
+            impact: item.message,
+            blocking,
+            resolution: item.help,
+            severity: item.severity,
+            parent: item.parent,
+          })
+        }
+      }
+      for (const association of entity.associations) {
+        const report = associationValidator.validate(association)
+        for (const item of report) {
+          const blocking = item.severity === 'error'
+          this.report.canProceed = this.report.canProceed && !blocking
+          this.report.impact.push({
+            key: item.key,
+            kind: item.kind,
+            type: 'publish',
+            impact: item.message,
+            blocking,
+            resolution: item.help,
+            severity: item.severity,
+            parent: item.parent,
+          })
+        }
+      }
+    }
     return this.report
   }
 
-  protected createDeleteImpact(key: string, kind: DomainImpactKinds, rootKey: string): DomainImpactItem[] {
+  protected createDeleteImpact(key: string, kind: DomainImpactKinds, rootKey: string): void {
     switch (kind) {
       case DomainNamespaceKind:
-        return this.deleteNamespaceAnalysis(key, rootKey)
+        this.deleteNamespaceAnalysis(key, rootKey)
+        break
       case DomainModelKind:
-        return this.deleteDataModelAnalysis(key, rootKey)
+        this.deleteDataModelAnalysis(key, rootKey)
+        break
       case DomainEntityKind:
-        return this.deleteEntityAnalysis(key, rootKey)
+        this.deleteEntityAnalysis(key, rootKey)
+        break
       case DomainPropertyKind:
-        return this.deletePropertyAnalysis(key)
+        this.deletePropertyAnalysis(key)
+        break
       case DomainAssociationKind:
-        return this.deleteAssociationAnalysis(key)
+        this.deleteAssociationAnalysis(key)
+        break
       default:
-        return []
+      // ignore unknown kinds
     }
   }
 
-  protected deleteNamespaceAnalysis(key: string, rootKey: string): DomainImpactItem[] {
-    const result: DomainImpactItem[] = []
+  protected deleteNamespaceAnalysis(key: string, rootKey: string): void {
     const ns = this.root.findNamespace(key)
     if (!ns) {
-      return result
+      return
     }
-    result.push({
+    this.report.impact.push({
       key: ns.key,
       kind: ns.kind,
       type: 'delete',
       impact: `The ${ns.info.getLabel()} ${this.kindToLabel(DomainNamespaceKind)} will be deleted.`,
       blocking: false,
+      severity: 'info',
     })
     for (const child of ns.listNamespaces()) {
-      const items = this.deleteNamespaceAnalysis(child.key, rootKey)
-      result.push(...items)
+      this.deleteNamespaceAnalysis(child.key, rootKey)
     }
     for (const child of ns.listModels()) {
-      const items = this.deleteDataModelAnalysis(child.key, rootKey)
-      result.push(...items)
+      this.deleteDataModelAnalysis(child.key, rootKey)
     }
-    return result
   }
 
-  protected deleteDataModelAnalysis(key: string, rootKey: string): DomainImpactItem[] {
-    const result: DomainImpactItem[] = []
+  protected deleteDataModelAnalysis(key: string, rootKey: string): void {
     const model = this.root.findModel(key)
     if (!model) {
-      return result
+      return
     }
-    result.push({
+    this.report.impact.push({
       key: model.key,
       kind: model.kind,
       type: 'delete',
       impact: `The ${model.info.getLabel()} ${this.kindToLabel(DomainModelKind)} will be deleted.`,
       blocking: false,
+      severity: 'info',
     })
     for (const child of model.listEntities()) {
-      const items = this.deleteEntityAnalysis(child.key, rootKey)
-      result.push(...items)
+      this.deleteEntityAnalysis(child.key, rootKey)
     }
-    return result
   }
 
-  protected deleteEntityAnalysis(key: string, rootKey: string): DomainImpactItem[] {
-    const result: DomainImpactItem[] = []
+  protected deleteEntityAnalysis(key: string, rootKey: string): void {
     const entity = this.root.findEntity(key)
     if (!entity) {
-      return result
+      return
     }
-    result.push({
+    this.report.impact.push({
       key: entity.key,
       kind: entity.kind,
       type: 'delete',
       impact: `The ${entity.info.getLabel()} ${this.kindToLabel(DomainEntityKind)} will be deleted.`,
       blocking: false,
+      severity: 'info',
     })
 
     // We need to know whether the entity is a parent of another entity
@@ -428,14 +521,15 @@ export class DomainImpactAnalysis {
       }
       const pLabel = entity.info.getLabel()
       const cLabel = childEntity.info.getLabel()
-      result.push({
+      this.report.impact.push({
         key: childEntity.key,
         kind: childEntity.kind,
         type: 'delete',
         impact: `The "${cLabel}" ${this.kindToLabel(DomainEntityKind)} will become an orphan because it is a child of the "${pLabel}" entity.`,
         resolution: `The "${pLabel}" entity will be removed as the parent of the "${cLabel}" entity.`,
-        blocking: true,
+        blocking: false,
         relationship: 'child',
+        severity: 'error',
       })
       this.report.canProceed = false
     }
@@ -460,57 +554,53 @@ export class DomainImpactAnalysis {
 
       const aLabel = association.info.getLabel()
       const eLabel = entity.info.getLabel()
-      result.push({
+      this.report.impact.push({
         key: association.key,
         kind: association.kind,
         type: 'delete',
         impact: `The ${aLabel} ${this.kindToLabel(DomainAssociationKind)} will be broken because it has a target to ${eLabel}.`,
         resolution: `The ${aLabel} ${this.kindToLabel(DomainAssociationKind)} will be removed from ${eLabel}.`,
         blocking: true,
+        severity: 'error',
       })
       this.report.canProceed = false
     }
     for (const child of entity.listProperties()) {
-      const items = this.deletePropertyAnalysis(child.key)
-      result.push(...items)
+      this.deletePropertyAnalysis(child.key)
     }
     for (const child of entity.listAssociations()) {
-      const items = this.deleteAssociationAnalysis(child.key)
-      result.push(...items)
+      this.deleteAssociationAnalysis(child.key)
     }
-    return result
   }
 
-  protected deletePropertyAnalysis(key: string): DomainImpactItem[] {
-    const result: DomainImpactItem[] = []
+  protected deletePropertyAnalysis(key: string): void {
     const property = this.root.findProperty(key)
     if (!property) {
-      return result
+      return
     }
-    result.push({
+    this.report.impact.push({
       key: property.key,
       kind: property.kind,
       type: 'delete',
       impact: `The ${property.info.getLabel()} ${this.kindToLabel(DomainPropertyKind)} will be deleted.`,
       blocking: false,
+      severity: 'info',
     })
-    return result
   }
 
-  protected deleteAssociationAnalysis(key: string): DomainImpactItem[] {
-    const result: DomainImpactItem[] = []
+  protected deleteAssociationAnalysis(key: string): void {
     const association = this.root.findAssociation(key)
     if (!association) {
-      return result
+      return
     }
-    result.push({
+    this.report.impact.push({
       key: association.key,
       kind: association.kind,
       type: 'delete',
       impact: `The ${association.info.getLabel()} ${this.kindToLabel(DomainAssociationKind)} will be deleted.`,
       blocking: false,
+      severity: 'info',
     })
-    return result
   }
 
   protected kindToLabel(kind: DomainImpactKinds): string {
@@ -530,11 +620,10 @@ export class DomainImpactAnalysis {
     }
   }
 
-  protected createRemoveForeignNamespaceImpact(key: string): DomainImpactItem[] {
-    const result: DomainImpactItem[] = []
+  protected createRemoveForeignNamespaceImpact(key: string): void {
     const foreignNamespace = this.root.dependencies.get(key)
     if (!foreignNamespace) {
-      return result
+      return
     }
     // Check for parent relationships to foreign entities
     for (const entity of this.root.listEntities()) {
@@ -551,7 +640,7 @@ export class DomainImpactAnalysis {
           }
           const eLabel = entity.info.getLabel()
           const pLabel = parentEntity.info.getLabel()
-          result.push({
+          this.report.impact.push({
             key: entity.key,
             kind: entity.kind,
             type: 'delete',
@@ -559,6 +648,7 @@ export class DomainImpactAnalysis {
             resolution: `The "${pLabel}" entity will be removed as the parent of the "${eLabel}" entity.`,
             blocking: true,
             relationship: 'child',
+            severity: 'error',
           })
           this.report.canProceed = false
         } else if (edge.type === 'association') {
@@ -576,13 +666,14 @@ export class DomainImpactAnalysis {
               const aLabel = association.info.getLabel()
               const eLabel = entity.info.getLabel()
               const tLabel = targetEntity.info.getLabel()
-              result.push({
+              this.report.impact.push({
                 key: association.key,
                 kind: association.kind,
                 type: 'delete',
                 impact: `The "${aLabel}" ${this.kindToLabel(DomainAssociationKind)} from "${eLabel}" will be broken because it targets "${tLabel}" in the foreign namespace "${foreignNamespace.key}".`,
                 resolution: `The "${aLabel}" ${this.kindToLabel(DomainAssociationKind)} will be removed from "${eLabel}".`,
                 blocking: true,
+                severity: 'error',
               })
               this.report.canProceed = false
             }
@@ -590,6 +681,5 @@ export class DomainImpactAnalysis {
         }
       }
     }
-    return result
   }
 }

package/src/modeling/DomainProperty.ts

@@ -242,7 +242,7 @@ export class DomainProperty extends DomainElement {
         throw new Error(`Invalid data property type ${type}`)
       }
     }
-    const info = Thing.fromJSON(input.info, { name: 'New property' }).toJSON()
+    const info = Thing.fromJSON(input.info, { name: 'new_property' }).toJSON()
     const result: DomainPropertySchema = {
       kind: DomainPropertyKind,
       key,

package/src/modeling/validation/association_validation.ts

@@ -0,0 +1,109 @@
+import { DomainAssociationKind } from '../../models/kinds.js'
+import type { DataDomain } from '../DataDomain.js'
+import type { DomainAssociation } from '../DomainAssociation.js'
+import type { DomainEntity } from '../DomainEntity.js'
+import { type DomainValidation, validatePropertyName } from './rules.js'
+
+/**
+ * AssociationValidation is a class that performs validation on associations in a data domain.
+ * Note that an association in most cases is a property of an entity.
+ */
+export class AssociationValidation {
+  constructor(protected domain: DataDomain) {}
+  /**
+   * Performs all the validation rules on the association.
+   * If you are interested in a specific rule, use the specific method.
+   * @param target The target association to validate. Can be a string with
+   *               the association key or a DomainAssociation object.
+   */
+  validate(target: string | DomainAssociation): DomainValidation[] {
+    const results: DomainValidation[] = []
+    let association: DomainAssociation | undefined
+    if (typeof target === 'string') {
+      association = this.domain.findAssociation(target)
+    } else {
+      association = target
+    }
+    if (!association) {
+      const message = `The "${target}" association does not exist.`
+      const help = `The association must be defined in the domain.`
+      results.push({
+        field: '*',
+        rule: 'exists',
+        message,
+        help,
+        key: target as string,
+        kind: DomainAssociationKind,
+        severity: 'error',
+      })
+      return results
+    }
+    const name = this.validateName(association)
+    results.push(...name)
+    const targets = this.validateTargets(association)
+    results.push(...targets)
+    return results
+  }
+
+  /**
+   * Validates the association name.
+   *
+   * @remarks
+   * - A association must have a name defined.
+   * - The name has to follow the same rules as the names in a PostgreSQL database.
+   *   - Column names can only contain letters (a-z, A-Z), numbers (0-9), and underscores (_).
+   *   - The name must start with a letter (a-z, A-Z) or an underscore (_).
+   *   - PostgreSQL limits column names to a maximum of 59 characters.
+   *   - (our rule) Column names are case insensitive.
+   *   - (recommendation) Column names should be in lower case.
+   * @param association The association to validate
+   */
+  validateName(association: DomainAssociation): DomainValidation[] {
+    return validatePropertyName(association)
+  }
+
+  /**
+   * Validates the association targets.
+   * @param association The association to validate
+   */
+  validateTargets(association: DomainAssociation): DomainValidation[] {
+    const results: DomainValidation[] = []
+    const label = association.info.getLabel()
+    const parentEntity = association.getParentInstance() as DomainEntity
+    if (!association.targets.length) {
+      const message = `The "${label}" association has no target.`
+      const help = `An association must have at least one target.`
+      results.push({
+        field: 'targets',
+        rule: 'required',
+        message,
+        help,
+        severity: 'error',
+        key: association.key,
+        kind: association.kind,
+        parent: parentEntity.key,
+      })
+      return results
+    }
+    for (const target of association.targets) {
+      const entity = target.domain
+        ? this.domain.findForeignEntity(target.key, target.domain)
+        : this.domain.findEntity(target.key)
+      if (!entity) {
+        const message = `The "${label}" association has an invalid target "${target.key}".`
+        const help = `The target must be defined in the domain.`
+        results.push({
+          field: 'targets',
+          rule: 'exists',
+          message,
+          help,
+          severity: 'error',
+          key: association.key,
+          kind: association.kind,
+          parent: parentEntity.key,
+        })
+      }
+    }
+    return results
+  }
+}