@api-client/core 0.14.0 → 0.14.2

package/src/modeling/DomainAssociation.ts

@@ -10,6 +10,27 @@ import type { AssociationBinding, AssociationBindings, AssociationWebBindings }
 import { DomainAttributeAttribute, DomainAttributeAttributes } from './DataFormat.js'
 import type { AssociationTarget, DomainGraphEdge } from './types.js'
 import { ShapeGenerator } from './amf/ShapeGenerator.js'
+import { DataSemantics, isAssociationSemantic, type SemanticType, type AppliedDataSemantic } from './Semantics.js'
+
+/**
+ * Defines the behavior when a parent entity in an association is deleted.
+ *
+ * - `restrict`: Prevents the deletion of a parent entity if it has any associated child entities.
+ *               The generated API should return a clear and specific error message (e.g., 409 Conflict).
+ *   - _Example_: Do not allow a Department to be deleted if it still has Employees.
+ * - `cascade`: Automatically deletes all associated child entities when the parent entity is deleted.
+ *   - _Example_: Deleting a User will also delete all their associated Posts and Comments.
+ * - `setNull`: Sets the foreign key of the associated child entities to NULL. This is only valid if the
+ *   association property on the child entity is nullable.
+ *   - _Example_: When a `Project` is deleted, the `project_id` on associated `Tasks` is set to NULL,
+ *   making them unassigned but not deleting them.
+ * - `doNothing`: No action is taken on the associated child entities when the parent entity is deleted.
+ *   - _Example_: Deleting a `Category` does not affect associated `Products`, which remain in the database
+ *               but may become orphaned.
+ *               This is useful when the association is optional or when child entities should not be deleted
+ *               or modified upon the deletion of a parent entity.
+ */
+export type OnDeleteRule = 'restrict' | 'cascade' | 'setNull' | 'doNothing'
 
 export interface DomainAssociationSchema extends DomainElementSchema {
   kind: typeof DomainAssociationKind
@@ -47,6 +68,20 @@ export interface DomainAssociationSchema extends DomainElementSchema {
    * When multiple associations are set then we are dealing with an union.
    */
   targets?: AssociationTarget[]
+  /**
+   * The semantics applied to this association.
+   * This is a list of applied semantics that can be used to
+   * describe the association in more detail.
+   */
+  semantics?: AppliedDataSemantic[]
+  /**
+   * Defines the behavior when a parent entity in an association is deleted.
+   */
+  onDelete?: OnDeleteRule
+  /**
+   * Whether the association is read-only.
+   */
+  readOnly?: boolean
 }
 
 /**
@@ -141,6 +176,21 @@ export class DomainAssociation extends DomainElement {
    */
   @observed({ deep: true }) accessor targets: AssociationTarget[]
 
+  /**
+   * Semantics applied to this association.
+   */
+  @observed({ deep: true }) accessor semantics: AppliedDataSemantic[] = []
+
+  /**
+   * Defines the behavior when a parent entity in an association is deleted.
+   */
+  @observed() accessor onDelete: OnDeleteRule | undefined
+
+  /**
+   * Whether the association is read-only.
+   */
+  @observed() accessor readOnly: boolean | undefined
+
   /**
    * Creates a full data association schema with defaults.
    *
@@ -148,13 +198,22 @@ export class DomainAssociation extends DomainElement {
    * @returns The data association schema.
    */
   static createSchema(input: Partial<DomainAssociationSchema> = {}): DomainAssociationSchema {
-    const { key = nanoid() } = input
+    const { key = nanoid(), semantics = [] } = input
     const info = Thing.fromJSON(input.info, { name: 'new_association' }).toJSON()
     const result: DomainAssociationSchema = {
       kind: DomainAssociationKind,
       key,
       info,
     }
+    if (Array.isArray(semantics)) {
+      result.semantics = [...semantics]
+    }
+    if (input.onDelete) {
+      result.onDelete = input.onDelete
+    }
+    if (typeof input.readOnly === 'boolean') {
+      result.readOnly = input.readOnly
+    }
     if (input.schema) {
       result.schema = structuredClone(input.schema)
     }
@@ -207,6 +266,17 @@ export class DomainAssociation extends DomainElement {
     } else {
       this.targets = []
     }
+    if (Array.isArray(init.semantics)) {
+      this.semantics = init.semantics.map((item) => structuredClone(item))
+    } else {
+      this.semantics = []
+    }
+    if (init.onDelete) {
+      this.onDelete = init.onDelete
+    }
+    if (typeof init.readOnly === 'boolean') {
+      this.readOnly = init.readOnly
+    }
   }
 
   /**
@@ -230,10 +300,19 @@ export class DomainAssociation extends DomainElement {
       result.required = this.required
     }
     if (Array.isArray(this.bindings) && this.bindings.length) {
-      result.bindings = (toRaw(this, this.bindings) as AssociationBinding[]).map((i) => structuredClone(i))
+      result.bindings = toRaw(this, this.bindings)?.map((i) => structuredClone(i))
     }
     if (Array.isArray(this.targets) && this.targets.length) {
-      result.targets = (toRaw(this, this.targets) as AssociationTarget[]).map((i) => ({ ...i }))
+      result.targets = toRaw(this, this.targets)?.map((i) => ({ ...i }))
+    }
+    if (Array.isArray(this.semantics) && this.semantics.length) {
+      result.semantics = toRaw(this, this.semantics)?.map((i) => structuredClone(i))
+    }
+    if (this.onDelete) {
+      result.onDelete = this.onDelete
+    }
+    if (typeof this.readOnly === 'boolean' && this.readOnly) {
+      result.readOnly = this.readOnly
     }
     return result
   }
@@ -472,4 +551,44 @@ export class DomainAssociation extends DomainElement {
     const serializer = new ShapeGenerator()
     return serializer.associationProperty(this)
   }
+
+  /**
+   * Adds or updates a semantic to the association.
+   * @param semantic The semantic to add to the association.
+   * @throws Error if the semantic is not an association semantic.
+   */
+  addSemantic(semantic: AppliedDataSemantic): void {
+    const sem = DataSemantics[semantic.id]
+    if (!isAssociationSemantic(sem)) {
+      throw new Error(`Invalid semantic type: ${semantic.id}. Expected an association semantic.`)
+    }
+    const index = this.semantics.findIndex((s) => s.id === semantic.id)
+    if (index >= 0) {
+      this.semantics[index] = semantic
+    } else {
+      this.semantics.push(semantic)
+    }
+    this.domain.notifyChange()
+  }
+
+  /**
+   * Removes a semantic from the association.
+   * @param semanticId The ID of the semantic to remove.
+   */
+  removeSemantic(semanticId: SemanticType): void {
+    const index = this.semantics.findIndex((s) => s.id === semanticId)
+    if (index >= 0) {
+      this.semantics.splice(index, 1)
+      this.domain.notifyChange()
+    }
+  }
+
+  /**
+   * Checks if the association has a specific semantic.
+   * @param semanticId The ID of the semantic to check.
+   * @returns True if the semantic is present, false otherwise.
+   */
+  hasSemantic(semanticId: SemanticType): boolean {
+    return this.semantics.some((s) => s.id === semanticId)
+  }
 }

package/src/modeling/DomainEntity.ts

@@ -17,6 +17,7 @@ import { ShapeGenerator } from './amf/ShapeGenerator.js'
 import type { IShapeRenderOptions } from '../amf/shape/ShapeBase.js'
 import { ApiSchemaGenerator } from '../amf/ApiSchemaGenerator.js'
 import { removeGraphNode } from './GraphUtils.js'
+import { DataSemantics, isEntitySemantic, type SemanticType, type AppliedDataSemantic } from './Semantics.js'
 
 export interface EntityOrderedItem {
   /**
@@ -43,11 +44,11 @@ export interface DomainEntitySchema extends DomainElementSchema {
   tags?: string[]
 
   /**
-   * For future use.
-   *
-   * The keys of the taxonomy items associated with the entity.
+   * The semantics applied to this entity.
+   * This is a list of applied semantics that can be used to
+   * describe the entity in more detail.
    */
-  taxonomy?: string[]
+  semantics?: AppliedDataSemantic[]
 
   /**
    * The ordered list of fields (properties and associations) in the schema.
@@ -76,7 +77,7 @@ export interface DomainEntitySchema extends DomainElementSchema {
  * - **Properties:** Defines the data elements (fields) within the entity.
  * - **Associations:** Defines relationships to other entities.
  * - **Inheritance:** Supports inheriting properties and associations from parent entities.
- * - **Metadata:** Supports tags, taxonomy, and deprecation status.
+ * - **Metadata:** Supports tags, semantics, and deprecation status.
  * - **AMF Shape Generation:** Can be serialized to an AMF (API Modeling Framework) shape.
  * - **Example Generation:** Can generate example databased on its schema.
  *
@@ -139,11 +140,9 @@ export class DomainEntity extends DomainElement {
   @observed({ deep: true }) accessor tags: string[]
 
   /**
-   * Reserved for future use.
-   *
-   * The keys of the taxonomy items associated with the entity.
+   * Semantics applied to this property.
    */
-  @observed({ deep: true }) accessor taxonomy: string[]
+  @observed({ deep: true }) accessor semantics: AppliedDataSemantic[] = []
 
   /**
    * The ordered list of fields (properties and associations) in the schema.
@@ -165,7 +164,7 @@ export class DomainEntity extends DomainElement {
    * @returns The data entity schema.
    */
   static createSchema(input: Partial<DomainEntitySchema> = {}): DomainEntitySchema {
-    const { key = nanoid(), tags, taxonomy, fields, deprecated } = input
+    const { key = nanoid(), tags, semantics, fields, deprecated } = input
     const info = Thing.fromJSON(input.info, { name: 'New entity' }).toJSON()
     const result: DomainEntitySchema = {
       kind: DomainEntityKind,
@@ -175,8 +174,8 @@ export class DomainEntity extends DomainElement {
     if (Array.isArray(tags)) {
       result.tags = [...tags]
     }
-    if (Array.isArray(taxonomy)) {
-      result.taxonomy = [...taxonomy]
+    if (Array.isArray(semantics)) {
+      result.semantics = [...semantics]
     }
     if (Array.isArray(fields)) {
       result.fields = [...fields]
@@ -206,10 +205,10 @@ export class DomainEntity extends DomainElement {
     } else {
       this.tags = []
     }
-    if (Array.isArray(init.taxonomy)) {
-      this.taxonomy = [...init.taxonomy]
+    if (Array.isArray(init.semantics)) {
+      this.semantics = init.semantics.map((item) => structuredClone(item))
     } else {
-      this.taxonomy = []
+      this.semantics = []
     }
     if (Array.isArray(init.fields)) {
       this.fields = [...init.fields]
@@ -235,8 +234,8 @@ export class DomainEntity extends DomainElement {
     if (Array.isArray(this.fields) && this.fields.length) {
       result.fields = [...this.fields]
     }
-    if (Array.isArray(this.taxonomy) && this.taxonomy.length) {
-      result.taxonomy = [...(toRaw(this, this.taxonomy) as string[])]
+    if (Array.isArray(this.semantics) && this.semantics.length) {
+      result.semantics = toRaw(this, this.semantics)?.map((i) => structuredClone(i))
     }
     if (Array.isArray(this.tags) && this.tags.length) {
       result.tags = [...(toRaw(this, this.tags) as string[])]
@@ -841,4 +840,44 @@ export class DomainEntity extends DomainElement {
     }
     return property
   }
+
+  /**
+   * Adds or updates a semantic to the entity.
+   * @param semantic The semantic to add to the entity.
+   * @throws Error if the semantic is not an entity semantic.
+   */
+  addSemantic(semantic: AppliedDataSemantic): void {
+    const sem = DataSemantics[semantic.id]
+    if (!isEntitySemantic(sem)) {
+      throw new Error(`Invalid semantic type: ${semantic.id}. Expected an entity semantic.`)
+    }
+    const index = this.semantics.findIndex((s) => s.id === semantic.id)
+    if (index >= 0) {
+      this.semantics[index] = semantic
+    } else {
+      this.semantics.push(semantic)
+    }
+    this.domain.notifyChange()
+  }
+
+  /**
+   * Removes a semantic from the entity.
+   * @param semanticId The ID of the semantic to remove.
+   */
+  removeSemantic(semanticId: SemanticType): void {
+    const index = this.semantics.findIndex((s) => s.id === semanticId)
+    if (index >= 0) {
+      this.semantics.splice(index, 1)
+      this.domain.notifyChange()
+    }
+  }
+
+  /**
+   * Checks if the entity has a specific semantic.
+   * @param semanticId The ID of the semantic to check.
+   * @returns True if the semantic is present, false otherwise.
+   */
+  hasSemantic(semanticId: SemanticType): boolean {
+    return this.semantics.some((s) => s.id === semanticId)
+  }
 }

package/src/modeling/DomainFile.ts

@@ -19,7 +19,7 @@ export class DomainFile extends File {
   }
 
   /**
-   * Creates the file definition for a DataNamespace contents.
+   * Creates the file definition for a DomainNamespace contents.
    *
    * @param input The data namespace instance or schema.
    */

package/src/modeling/DomainImpactAnalysis.ts

@@ -436,7 +436,7 @@ export class DomainImpactAnalysis {
         this.deleteNamespaceAnalysis(key, rootKey)
         break
       case DomainModelKind:
-        this.deleteDataModelAnalysis(key, rootKey)
+        this.deleteModelAnalysis(key, rootKey)
         break
       case DomainEntityKind:
         this.deleteEntityAnalysis(key, rootKey)
@@ -469,11 +469,11 @@ export class DomainImpactAnalysis {
       this.deleteNamespaceAnalysis(child.key, rootKey)
     }
     for (const child of ns.listModels()) {
-      this.deleteDataModelAnalysis(child.key, rootKey)
+      this.deleteModelAnalysis(child.key, rootKey)
     }
   }
 
-  protected deleteDataModelAnalysis(key: string, rootKey: string): void {
+  protected deleteModelAnalysis(key: string, rootKey: string): void {
     const model = this.root.findModel(key)
     if (!model) {
       return

package/src/modeling/DomainModel.ts

@@ -64,10 +64,10 @@ export interface DomainModelSchema extends DomainElementSchema {
  *
  * ```typescript
  * const dataDomain = new DataDomain();
- * const dataNamespace = dataDomain.addNamespace({
+ * const ns = dataDomain.addNamespace({
  *   key: 'myNamespace',
  * });
- * const userModel = dataNamespace.addModel({
+ * const userModel = ns.addModel({
  *   key: 'userModel',
  *   info: { name: 'User Model' },
  * });

package/src/modeling/DomainProperty.ts

@@ -16,12 +16,13 @@ import {
   type NumberFormat,
   NumberFormats,
 } from './DataFormat.js'
+import { ShapeGenerator } from './amf/ShapeGenerator.js'
 import type { PropertyBinding, PropertyBindings, PropertyWebBindings } from './Bindings.js'
 import type { ModelValidationOptions } from '../models/types.js'
 import type { DomainEntity } from './DomainEntity.js'
 import type { IApiPropertyShape } from '../amf/definitions/Shapes.js'
-import { ShapeGenerator } from './amf/ShapeGenerator.js'
-import { PropertySchema } from './types.js'
+import type { PropertySchema } from './types.js'
+import { DataSemantics, isPropertySemantic, type SemanticType, type AppliedDataSemantic } from './Semantics.js'
 
 export interface DomainPropertySchema extends DomainElementSchema {
   kind: typeof DomainPropertyKind
@@ -62,11 +63,11 @@ export interface DomainPropertySchema extends DomainElementSchema {
    */
   tags?: string[]
   /**
-   * For future use.
-   *
-   * The keys of the taxonomy items associated with the property.
+   * The semantics applied to this property.
+   * This is a list of applied semantics that can be used to
+   * describe the property in more detail.
    */
-  taxonomy?: string[]
+  semantics?: AppliedDataSemantic[]
   /**
    * The data type for this property.
    * Note, not all schemas support the same type. For example, defining `sint32`
@@ -106,21 +107,21 @@ export interface DomainPropertySchema extends DomainElementSchema {
  * -   **Bindings:** Allows defining how the property is
  *     represented in different formats (e.g., web APIs,
  *     protocol buffers).
- * -   **Metadata:** Supports metadata such as tags, taxonomy,
+ * -   **Metadata:** Supports metadata such as tags, semantics,
  *     read-only/write-only status, and deprecation.
  * -   **Schema:** Allows defining a general schema for the
  *     property, which is propagated to all bindings.
  *
  * **Usage:**
  *
- * Use the `DataEntity.addProperty` method to add a new property to an
+ * Use the `DomainEntity.addProperty` method to add a new property to an
  * entity. The property can be created using the constructor, but it
  * won't be added to the graph until you call the `addProperty` method.
  *
  * **Example:**
  *
  * ```typescript
- * const entity = dataModel.addEntity({ key: 'user' });
+ * const entity = domainModel.addEntity({ key: 'user' });
  * const property = entity.addProperty({
  *   key: 'name',
  *   type: 'string',
@@ -185,11 +186,9 @@ export class DomainProperty extends DomainElement {
   @observed({ deep: true }) accessor tags: string[] = []
 
   /**
-   * Reserved for future use.
-   *
-   * The keys of the taxonomy items associated with the property.
+   * Semantics applied to this property.
    */
-  @observed({ deep: true }) accessor taxonomy: string[] = []
+  @observed({ deep: true }) accessor semantics: AppliedDataSemantic[] = []
 
   /**
    * The data type for this property.
@@ -232,7 +231,7 @@ export class DomainProperty extends DomainElement {
       readOnly,
       writeOnly,
       tags,
-      taxonomy,
+      semantics,
       deprecated,
       schema,
       bindings,
@@ -273,8 +272,8 @@ export class DomainProperty extends DomainElement {
     if (Array.isArray(tags)) {
       result.tags = [...tags]
     }
-    if (Array.isArray(taxonomy)) {
-      result.taxonomy = [...taxonomy]
+    if (Array.isArray(semantics)) {
+      result.semantics = [...semantics]
     }
     if (schema) {
       result.schema = structuredClone(schema)
@@ -353,10 +352,10 @@ export class DomainProperty extends DomainElement {
     } else {
       this.tags = []
     }
-    if (Array.isArray(init.taxonomy)) {
-      this.taxonomy = [...init.taxonomy]
+    if (Array.isArray(init.semantics)) {
+      this.semantics = [...init.semantics]
     } else {
-      this.taxonomy = []
+      this.semantics = []
     }
     if (init.schema) {
       this.schema = structuredClone(init.schema)
@@ -419,8 +418,8 @@ export class DomainProperty extends DomainElement {
     if (Array.isArray(this.tags) && this.tags.length) {
       result.tags = [...this.tags]
     }
-    if (Array.isArray(this.taxonomy) && this.taxonomy.length) {
-      result.taxonomy = [...this.taxonomy]
+    if (Array.isArray(this.semantics) && this.semantics.length) {
+      result.semantics = toRaw(this, this.semantics)?.map((i) => structuredClone(i))
     }
     if (this.schema) {
       result.schema = structuredClone(toRaw(this, this.schema))
@@ -545,4 +544,44 @@ export class DomainProperty extends DomainElement {
     const serializer = new ShapeGenerator()
     return serializer.property(this)
   }
+
+  /**
+   * Adds or updates a semantic to the property.
+   * @param semantic The semantic to add to the property.
+   * @throws Error if the semantic is not an property semantic.
+   */
+  addSemantic(semantic: AppliedDataSemantic): void {
+    const sem = DataSemantics[semantic.id]
+    if (!isPropertySemantic(sem)) {
+      throw new Error(`Invalid semantic type: ${semantic.id}. Expected a property semantic.`)
+    }
+    const index = this.semantics.findIndex((s) => s.id === semantic.id)
+    if (index >= 0) {
+      this.semantics[index] = semantic
+    } else {
+      this.semantics.push(semantic)
+    }
+    this.domain.notifyChange()
+  }
+
+  /**
+   * Removes a semantic from the property.
+   * @param semanticId The ID of the semantic to remove.
+   */
+  removeSemantic(semanticId: SemanticType): void {
+    const index = this.semantics.findIndex((s) => s.id === semanticId)
+    if (index >= 0) {
+      this.semantics.splice(index, 1)
+      this.domain.notifyChange()
+    }
+  }
+
+  /**
+   * Checks if the property has a specific semantic.
+   * @param semanticId The ID of the semantic to check.
+   * @returns True if the semantic is present, false otherwise.
+   */
+  hasSemantic(semanticId: SemanticType): boolean {
+    return this.semantics.some((s) => s.id === semanticId)
+  }
 }