@api-client/core 0.12.0 → 0.12.2

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/legacy/DataAssociation.ts

@@ -1,7 +1,7 @@
 import { Json } from '@api-client/json'
 import { AmfShapeGenerator } from '../../amf/AmfShapeGenerator.js'
 import { IApiAssociationShape, IApiPropertyShape } from '../../amf/definitions/Shapes.js'
-import v4 from '../../lib/uuid.js'
+import { nanoid } from 'nanoid'
 import { IThing, Thing } from '../../models/Thing.js'
 import { DataEntity, IDataEntity } from './DataEntity.js'
 import { DataNamespace } from './DataNamespace.js'
@@ -230,7 +230,7 @@ export class DataAssociation {
     } else {
       init = {
         kind: DataAssociationKind,
-        key: v4(),
+        key: nanoid(),
         info: Thing.fromName('Unnamed association').toJSON(),
       }
     }
@@ -244,7 +244,7 @@ export class DataAssociation {
    */
   new(init: IDataAssociation): this {
     DataAssociation.validate(init)
-    const { info, key = v4(), kind = DataAssociationKind, schema, multiple, required, targets, bindings } = init
+    const { info, key = nanoid(), kind = DataAssociationKind, schema, multiple, required, targets, bindings } = init
     this.kind = kind
     this.key = key
     if (info) {

package/src/modeling/legacy/DataEntity.ts

@@ -1,5 +1,5 @@
 import { IThing, Thing } from '../../models/Thing.js'
-import v4 from '../../lib/uuid.js'
+import { nanoid } from 'nanoid'
 import { DataNamespace } from './DataNamespace.js'
 import { DataProperty } from './DataProperty.js'
 import { type DataPropertyType } from '../DataFormat.js'
@@ -185,7 +185,7 @@ export class DataEntity {
     } else {
       init = {
         kind: DataEntityKind,
-        key: v4(),
+        key: nanoid(),
         info: Thing.fromName('').toJSON(),
       }
     }
@@ -196,7 +196,7 @@ export class DataEntity {
     DataEntity.validate(init)
     const {
       info,
-      key = v4(),
+      key = nanoid(),
       kind = DataEntityKind,
       tags,
       taxonomy,

package/src/modeling/legacy/DataEntityBuilder.ts

@@ -2,7 +2,7 @@ import { DataEntity } from './DataEntity.js'
 import { DataNamespace } from './DataNamespace.js'
 import { type DataPropertyType } from '../DataFormat.js'
 import { type IThing, Thing } from '../../models/Thing.js'
-import v4 from '../../lib/uuid.js'
+import { nanoid } from 'nanoid'
 
 /**
  * A fluent builder for constructing `DataEntity` instances.
@@ -228,7 +228,7 @@ export class DataEntityBuilder {
    */
   build(): DataEntity {
     if (!this.entity.key) {
-      this.entity.key = v4()
+      this.entity.key = nanoid()
     }
     this.root.definitions.entities.push(this.entity)
     return this.entity

package/src/modeling/legacy/DataModel.ts

@@ -1,5 +1,5 @@
 import { IThing, Thing } from '../../models/Thing.js'
-import v4 from '../../lib/uuid.js'
+import { nanoid } from 'nanoid'
 import { DataEntity, IDataEntity } from './DataEntity.js'
 import type { DataItemAdaptingOptions, DataNamespace } from './DataNamespace.js'
 import { FileBreadcrumb } from '../../models/store/File.js'
@@ -73,7 +73,7 @@ export class DataModel {
     } else {
       init = {
         kind: DataModelKind,
-        key: v4(),
+        key: nanoid(),
         info: Thing.fromName('').toJSON(),
         entities: [],
       }
@@ -85,7 +85,7 @@ export class DataModel {
     if (!DataModel.isDataModel(init)) {
       throw new Error(`Not a data model.`)
     }
-    const { info, key = v4(), kind = DataModelKind, entities } = init
+    const { info, key = nanoid(), kind = DataModelKind, entities } = init
     this.kind = kind
     this.key = key
     if (info) {

package/src/modeling/legacy/DataNamespace.ts

@@ -11,7 +11,7 @@ import {
   DataPropertyKind,
   DataAssociationKind,
 } from '../../models/kinds.js'
-import v4 from '../../lib/uuid.js'
+import { nanoid } from 'nanoid'
 import type { DataDomainRemoveOptions } from '../types.js'
 
 /**
@@ -288,7 +288,7 @@ export class DataNamespace {
     } else {
       init = {
         kind: DataNamespaceKind,
-        key: v4(),
+        key: nanoid(),
         definitions: {},
         items: [],
         info: Thing.fromName('').toJSON(),
@@ -301,7 +301,7 @@ export class DataNamespace {
     if (!init || !init.definitions || !init.items) {
       throw new Error(`Not a data namespace.`)
     }
-    const { key = v4(), definitions = {}, items, info } = init
+    const { key = nanoid(), definitions = {}, items, info } = init
     this.key = key
     if (info) {
       this.info = new Thing(info)

package/src/modeling/legacy/DataProperty.ts

@@ -1,6 +1,6 @@
 import { Json } from '@api-client/json'
 import { IThing, Thing } from '../../models/Thing.js'
-import v4 from '../../lib/uuid.js'
+import { nanoid } from 'nanoid'
 import { DataNamespace } from './DataNamespace.js'
 import { IApiPropertyShape } from '../../amf/definitions/Shapes.js'
 import { AmfShapeGenerator } from '../../amf/AmfShapeGenerator.js'
@@ -304,7 +304,7 @@ export class DataProperty {
     } else {
       init = {
         kind: DataPropertyKind,
-        key: v4(),
+        key: nanoid(),
         info: Thing.fromName('').toJSON(),
         type: 'string',
       }
@@ -318,7 +318,7 @@ export class DataProperty {
     }
     const {
       info,
-      key = v4(),
+      key = nanoid(),
       kind = DataPropertyKind,
       multiple,
       required,

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
+  }
+}