@api-client/core 0.14.0 → 0.14.1

package/data/models/example-generator-api.json

@@ -41728,16 +41728,16 @@
 "@id": "#194"
 },
 {
-"@id": "#197"
+"@id": "#200"
 },
 {
-"@id": "#206"
+"@id": "#197"
 },
 {
-"@id": "#200"
+"@id": "#203"
 },
 {
-"@id": "#203"
+"@id": "#206"
 },
 {
 "@id": "#209"
@@ -43138,7 +43138,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: '5'\ndescription: 'Limited company'\n",
+"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43159,7 +43159,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: 'J'\ndescription: 'Information and communication'\n",
+"doc:raw": "code: '5'\ndescription: 'Limited company'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43180,7 +43180,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: '7487'\ndescription: 'Financial and insurance activities'\ntype: \"PRIMARY\"\nclassificationCode: 'BE_NACEBEL2008'\nactivityGroupCode: 'ABCDE'\n",
+"doc:raw": "code: 'J'\ndescription: 'Information and communication'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43201,7 +43201,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
+"doc:raw": "code: '7487'\ndescription: 'Financial and insurance activities'\ntype: \"PRIMARY\"\nclassificationCode: 'BE_NACEBEL2008'\nactivityGroupCode: 'ABCDE'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44426,7 +44426,7 @@
 {
 "@id": "#199/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#199",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(5,0)]"
 },
 {
 "@id": "#202/source-map/lexical/element_0",
@@ -44436,12 +44436,12 @@
 {
 "@id": "#205/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#205",
-"sourcemaps:value": "[(1,0)-(6,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#208/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#208",
-"sourcemaps:value": "[(1,0)-(5,0)]"
+"sourcemaps:value": "[(1,0)-(6,0)]"
 },
 {
 "@id": "#223/source-map/lexical/element_0",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-client/core",
   "description": "The API Client's core client library. Works in NodeJS and in a ES enabled browser.",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {

package/src/amf/AmfTypes.ts

@@ -103,7 +103,7 @@ export const IAmfExampleTypes = [
 ]
 
 /**
- * Translates the DataProperty type to an AMF data type.
+ * Translates the DomainProperty type to an AMF data type.
  * @param type The property data type
  * @returns AMF shape dataType
  */

package/src/amf/Utils.ts

@@ -1,4 +1,3 @@
-import { UrlEncoder } from '../lib/parsers/UrlEncoder.js'
 import { AmfNamespace } from './definitions/Namespace.js'
 import { IApiNodeShape, IApiPropertyShape, IShapeUnion, IApiUnionShape } from './definitions/Shapes.js'
 
@@ -45,20 +44,6 @@ export function formatXmlValue(fill: string, value: unknown): string {
   return formatted
 }
 
-/**
- * @param str A key or value to encode as x-www-form-urlencoded.
- * @param replacePlus When set it replaces `%20` with `+`.
- * @deprecated Use `UrlEncoder.encodeQueryString()` instead.
- */
-export function wwwFormUrlEncode(str: string, replacePlus?: boolean): string {
-  // Spec says to normalize newlines to \r\n and replace %20 spaces with +.
-  // jQuery does this as well, so this is likely to be widely compatible.
-  if (str === undefined) {
-    return ''
-  }
-  return UrlEncoder.encodeQueryString(String(str), replacePlus)
-}
-
 /**
  * Processes a value that should be a number.
  */

package/src/modeling/Bindings.ts

@@ -139,7 +139,7 @@ export type PropertyBindings = PropertyWebBindings | PropertyProtobufBindings
 export interface PropertyBinding extends Binding {
   /**
    * The definition of the bindings.
-   * The bindings tells how to translated the DataProperty to a specific format.
+   * The bindings tells how to translated the DomainProperty to a specific format.
    * For example, it allows to define the `dataType` and `format` for RAML / OAS (via the AMF shapes)
    * or the field number for protocol buffer.
    */

package/src/modeling/DataDomain.ts

@@ -800,7 +800,7 @@ export class DataDomain extends EventTarget {
    */
   addEntity(parent: string, input?: Partial<DomainEntitySchema>): DomainEntity {
     if (!parent) {
-      throw new Error(`An entity expects a DataModel parent`)
+      throw new Error(`An entity expects a DomainModel parent`)
     }
     if (!this.graph.hasNode(parent)) {
       throw new Error(`The parent ${parent} does not exist`)
@@ -1047,7 +1047,7 @@ export class DataDomain extends EventTarget {
    */
   addProperty(parent: string, property?: Partial<DomainPropertySchema>): DomainProperty {
     if (!parent) {
-      throw new Error(`A property expects a DataEntity parent`)
+      throw new Error(`A property expects a DomainEntity parent`)
     }
     if (!this.graph.hasNode(parent)) {
       throw new Error(`Parent entity ${parent} does not exist`)

package/src/modeling/DataFormat.ts

@@ -9,11 +9,6 @@ export type DomainPropertyType =
   // | 'any'
   | 'binary'
 
-/**
- * @deprecated Use the {@link DomainPropertyType} instead.
- */
-export type DataPropertyType = DomainPropertyType
-
 export const DomainPropertyTypes: DomainPropertyType[] = [
   'string',
   'number',
@@ -36,11 +31,6 @@ export const DomainPropertyTypes: DomainPropertyType[] = [
   'binary',
 ]
 
-/**
- * @deprecated Use the {@link DomainPropertyTypes} instead.
- */
-export const DataPropertyTypes: DataPropertyType[] = DomainPropertyTypes
-
 export enum DomainPropertyList {
   string = 'string',
   number = 'number',
@@ -53,21 +43,6 @@ export enum DomainPropertyList {
   file = 'binary',
 }
 
-/**
- * @deprecated Use the {@link DomainPropertyList} instead.
- */
-export enum DataPropertyList {
-  string = 'string',
-  number = 'number',
-  // nil = 'nil',
-  boolean = 'boolean',
-  date = 'date',
-  datetime = 'datetime',
-  time = 'time',
-  // any = 'any',
-  file = 'binary',
-}
-
 /**
  * The data property "attributes".
  */
@@ -80,11 +55,6 @@ export type DomainPropertyAttribute =
   | 'writeOnly'
   | 'deprecated'
 
-/**
- * @deprecated Use the {@link DomainPropertyAttribute} instead.
- */
-export type DataPropertyAttribute = DomainPropertyAttribute
-
 export const DomainPropertyAttributes: DomainPropertyAttribute[] = [
   'required',
   'multiple',
@@ -95,26 +65,12 @@ export const DomainPropertyAttributes: DomainPropertyAttribute[] = [
   'deprecated',
 ]
 
-/**
- * @deprecated Use the {@link DomainPropertyAttributes} instead.
- */
-export const DataPropertyAttributes: DataPropertyAttribute[] = DomainPropertyAttributes
-
 /**
  * The data attribute "attributes".
  */
 export type DomainAttributeAttribute = 'required' | 'multiple'
 
-/**
- * @deprecated Use the {@link DomainAttributeAttribute} instead.
- */
-export type DataAttributeAttribute = DomainAttributeAttribute
-
 export const DomainAttributeAttributes: DomainAttributeAttribute[] = ['required', 'multiple']
-/**
- * @deprecated Use the {@link DomainAttributeAttributes} instead.
- */
-export const DataAttributeAttributes: DataAttributeAttribute[] = DomainAttributeAttributes
 
 /**
  * Note, OAS supports the `integer` data type and not format.
@@ -138,7 +94,3 @@ export type BinaryFormat = 'hex' | 'base64'
 export const BinaryFormats: BinaryFormat[] = ['hex', 'base64']
 
 export type DomainPropertyFormat = NumberFormat | BinaryFormat
-/**
- * @deprecated Use the {@link DomainPropertyFormat} instead.
- */
-export type DataPropertyFormat = NumberFormat | BinaryFormat

package/src/modeling/DomainAssociation.ts

@@ -10,6 +10,7 @@ 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'
 
 export interface DomainAssociationSchema extends DomainElementSchema {
   kind: typeof DomainAssociationKind
@@ -47,6 +48,12 @@ 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[]
 }
 
 /**
@@ -141,6 +148,11 @@ export class DomainAssociation extends DomainElement {
    */
   @observed({ deep: true }) accessor targets: AssociationTarget[]
 
+  /**
+   * Semantics applied to this association.
+   */
+  @observed({ deep: true }) accessor semantics: AppliedDataSemantic[] = []
+
   /**
    * Creates a full data association schema with defaults.
    *
@@ -148,13 +160,16 @@ 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.schema) {
       result.schema = structuredClone(input.schema)
     }
@@ -207,6 +222,11 @@ export class DomainAssociation extends DomainElement {
     } else {
       this.targets = []
     }
+    if (Array.isArray(init.semantics)) {
+      this.semantics = init.semantics.map((item) => structuredClone(item))
+    } else {
+      this.semantics = []
+    }
   }
 
   /**
@@ -230,10 +250,13 @@ 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))
     }
     return result
   }
@@ -472,4 +495,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' },
  * });