@api-client/core 0.11.0 → 0.11.2

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

@@ -42470,13 +42470,13 @@
 "@id": "#219"
 },
 {
-"@id": "#219"
+"@id": "#213"
 },
 {
 "@id": "#210"
 },
 {
-"@id": "#213"
+"@id": "#219"
 },
 {
 "@id": "#216"
@@ -43913,7 +43913,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "-\n  type: 'GENERAL'\n  value: 'info@company.be'\n-\n  type: 'IT_DEPT'\n  value: 'it-service@company.be'\n",
+"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '22'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)22 000000'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43955,7 +43955,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '22'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)22 000000'\n",
+"doc:raw": "-\n  type: 'GENERAL'\n  value: 'info@company.be'\n-\n  type: 'IT_DEPT'\n  value: 'it-service@company.be'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44781,7 +44781,7 @@
 {
 "@id": "#215/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#215",
-"sourcemaps:value": "[(1,0)-(7,0)]"
+"sourcemaps:value": "[(1,0)-(6,0)]"
 },
 {
 "@id": "#218/source-map/lexical/element_0",
@@ -44791,7 +44791,7 @@
 {
 "@id": "#221/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#221",
-"sourcemaps:value": "[(1,0)-(6,0)]"
+"sourcemaps:value": "[(1,0)-(7,0)]"
 },
 {
 "@id": "#338/source-map/synthesized-field/element_1",

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.11.0",
+  "version": "0.11.2",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {
@@ -58,7 +58,7 @@
     "@pawel-up/data-mock": "^0.3.2",
     "@pawel-up/jexl": "^3.0.0",
     "@xmldom/xmldom": "^0.9.7",
-    "amf-json-ld-lib": "^0.0.14",
+    "amf-json-ld-lib": "^0.0.15",
     "console-table-printer": "^2.11.2",
     "dompurify": "^3.1.5",
     "idb-keyval": "^6.2.1",
@@ -94,7 +94,7 @@
     "@web/test-runner": "^0.20.0",
     "@web/test-runner-commands": "^0.9.0",
     "@web/test-runner-playwright": "^0.11.0",
-    "amf-client-js": "^5.5.2-0",
+    "amf-client-js": "^5.7.0",
     "c8": "^10.1.3",
     "cors": "^2.8.5",
     "eslint": "^9.20.1",
@@ -121,6 +121,7 @@
     "wireit": "^0.14.4"
   },
   "scripts": {
+    "build:test": "wireit",
     "build:ts": "wireit",
     "build": "npm run build:ts && npm run lint && npm run copy:assets",
     "lint": "wireit",
@@ -192,6 +193,19 @@
         ".tsbuildinfo"
       ]
     },
+    "build:test": {
+      "command": "tsc --project tsconfig.browser.json",
+      "clean": "if-file-deleted",
+      "files": [
+        "src/**/*.ts",
+        "test/**/*.ts",
+        "tsconfig.browser.json"
+      ],
+      "output": [
+        ".tmp/testing/**",
+        ".tsbuildinfo"
+      ]
+    },
     "lint": {
       "command": "eslint --color --cache --cache-location .eslintcache .",
       "files": [

package/src/amf/AmfMixin.ts

@@ -13,9 +13,7 @@ WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 License for the specific language governing permissions and limitations under
 the License.
 */
-
-// @ts-expect-error This library has no proper types defined.
-import { AmfModelExpander, JsonLdOptions, JsonLd } from 'amf-json-ld-lib'
+import { AmfModelExpander } from 'amf-json-ld-lib'
 import {
   IAmfDocument,
   IAmfDomainElement,
@@ -78,7 +76,7 @@ export declare class AmfMixinInterface {
   /**
    * Expands flattened AMF model
    */
-  _expand(amf: any): any
+  _expand(amf: unknown): IAmfDocument
 
   /**
    * Returns compact model key for given value.
@@ -94,7 +92,7 @@ export declare class AmfMixinInterface {
    * @param amf AMF json/ld model
    * @returns The API spec
    */
-  _ensureAmfModel(amf: any): IAmfDocument | undefined
+  _ensureAmfModel(amf: unknown): IAmfDocument | undefined
 
   /**
    * Ensures that the value is an array.
@@ -525,31 +523,20 @@ export declare class AmfMixinInterface {
 export const AmfMixin = <T extends Constructor<any>>(superClass: T): Constructor<AmfMixinInterface> & T => {
   class AmfMixin extends superClass {
     _amf?: IAmfDocument
-    _flattenedAmf?: any
     __cachedKeys?: any
+    __lastSetValue?: unknown
 
     get amf(): IAmfDocument | undefined {
       return this._amf
     }
 
     set amf(value: IAmfDocument | undefined) {
-      const old = this._amf
-      if (old === value) {
+      if (this._amf === value || this.__lastSetValue === value) {
         return
       }
-      let expanded
-      if (!value || AmfModelExpander.isInExpandedForm(value)) {
-        this._flattenedAmf = undefined
-        expanded = value
-      } else {
-        const oldFlattened = this._flattenedAmf
-        if (oldFlattened === value) {
-          return
-        }
-        this._flattenedAmf = value
-        expanded = this._expand(value)
-      }
-      // Cached keys cannot be static as this element can be using in the sane
+      this.__lastSetValue = value
+      const expanded = value ? this._expand(value) : undefined
+      // Cached keys cannot be static as this element can be used in the sane
       // document with different AMF models
       this.__cachedKeys = {}
       this._amf = expanded
@@ -569,16 +556,8 @@ export const AmfMixin = <T extends Constructor<any>>(superClass: T): Constructor
     /**
      * Expands flattened AMF model
      */
-    _expand(amf: any): any {
-      AmfModelExpander.preprocessLegacyRootNodeId(amf)
-      const linkEmbeddingFilter = (key: string): boolean => !key.endsWith('fixPoint')
-      const rootNode = amf['@context'] ? '' : 'amf://id'
-      const options = JsonLdOptions.apply()
-        .withEmbeddedLinks(linkEmbeddingFilter)
-        .withCompactedIris()
-        .withExpandedStructure()
-        .withRootNode(rootNode)
-      return JsonLd.process(amf, options)
+    _expand(amf: any): IAmfDocument {
+      return AmfModelExpander.expand(amf) as IAmfDocument
     }
 
     /**

package/src/modeling/DataAssociation.ts

@@ -8,6 +8,7 @@ import { DataNamespace } from './DataNamespace.js'
 import { type FieldValidationMessage, ValidationError } from '../exceptions/validation_error.js'
 import { DataAssociationKind } from '../models/kinds.js'
 import type { AssociationBinding, AssociationBindings, AssociationWebBindings } from './Bindings.js'
+import { DataAttributeAttributes, type DataAttributeAttribute } from './DataFormat.js'
 
 /**
  * Describes association target of an entity
@@ -484,6 +485,18 @@ export class DataAssociation {
     return this.schema
   }
 
+  /**
+   * Checks whether the passed value is one of the supported data proprty attributes.
+   * @param value The value to test
+   * @returns True when the passed value is one of the supported data proprty attributes.
+   */
+  static isValidAttribute(value: unknown): value is DataAttributeAttribute {
+    if (typeof value !== 'string') {
+      return false
+    }
+    return DataAttributeAttributes.includes(value as DataAttributeAttribute)
+  }
+
   /**
    * Creates if not existing and returns web bindings definition.
    * @returns The web binding definition

package/src/modeling/DataEntity.ts

@@ -17,6 +17,11 @@ import { ValidationError, type FieldValidationMessage } from '../exceptions/vali
 import { RemoveEntityException } from '../exceptions/remove_entity_exception.js'
 import { ForeignAssociationException } from '../exceptions/foreign_association_exception.js'
 
+interface OrderedItem {
+  type: 'property' | 'association'
+  key: string
+}
+
 /**
  * Data entity is the smallest description of a data in the system
  * It contains properties and associations. At least one entity describe a data model.
@@ -54,6 +59,14 @@ export interface IDataEntity {
    */
   associations?: string[]
 
+  /**
+   * The ordered list of fields (properties and associations) in the schema.
+   * These only keep references to the properties and associations.
+   * The order of the fields is important as it defines the order of the
+   * properties in the schema.
+   */
+  fields?: OrderedItem[]
+
   /**
    * The list of keys of entities that are parents to this entity.
    *
@@ -62,6 +75,9 @@ export interface IDataEntity {
    * with the same name to shadow parent property. When the property is
    * not shadowed this may cause unexpected results as the processing could result
    * with inconsistent definition of a schema because the last read property wins.
+   *
+   * @todo(jarrodek): This should also hold a reference to a namespace to support
+   * foreign entities as parents.
    */
   parents?: string[]
 
@@ -112,6 +128,14 @@ export class DataEntity {
    */
   associations: DataAssociation[] = []
 
+  /**
+   * The ordered list of fields (properties and associations) in the schema.
+   * These only keep references to the properties and associations.
+   * The order of the fields is important as it defines the order of the
+   * properties in the schema.
+   */
+  fields: OrderedItem[] = []
+
   /**
    * The list of keys of entities that are parents to this entity.
    *
@@ -167,6 +191,7 @@ export class DataEntity {
       parents,
       properties,
       associations,
+      fields,
       deprecated,
     } = init
     this.kind = kind
@@ -209,6 +234,11 @@ export class DataEntity {
         }
       })
     }
+    if (Array.isArray(fields)) {
+      this.fields = [...fields]
+    } else {
+      this.fields = this.createOrderedFields()
+    }
     if (typeof deprecated === 'boolean') {
       this.deprecated = deprecated
     } else {
@@ -216,6 +246,23 @@ export class DataEntity {
     }
   }
 
+  private createOrderedFields(): OrderedItem[] {
+    const result: OrderedItem[] = []
+    this.properties.forEach((i) => {
+      result.push({
+        type: 'property',
+        key: i.key,
+      })
+    })
+    this.associations.forEach((i) => {
+      result.push({
+        type: 'association',
+        key: i.key,
+      })
+    })
+    return result
+  }
+
   static validate(input: unknown): void {
     const typed = input as IDataEntity
     const messages: FieldValidationMessage[] = []
@@ -260,6 +307,15 @@ export class DataEntity {
     if (Array.isArray(this.associations) && this.associations.length) {
       result.associations = this.associations.map((i) => i.key)
     }
+    if (Array.isArray(this.fields) && this.fields.length) {
+      result.fields = [...this.fields]
+    }
+    if (Array.isArray(this.taxonomy) && this.taxonomy.length) {
+      result.taxonomy = [...this.taxonomy]
+    }
+    if (Array.isArray(this.tags) && this.tags.length) {
+      result.tags = [...this.tags]
+    }
     if (typeof this.deprecated === 'boolean') {
       result.deprecated = this.deprecated
     }
@@ -286,6 +342,7 @@ export class DataEntity {
     }
     this.root.definitions.properties.push(property)
     this.properties.push(property)
+    this.fields.push({ type: 'property', key: property.key })
     return property
   }
 
@@ -298,6 +355,7 @@ export class DataEntity {
     const property = DataProperty.fromName(this.root, name)
     this.root.definitions.properties.push(property)
     this.properties.push(property)
+    this.fields.push({ type: 'property', key: property.key })
     return property
   }
 
@@ -316,24 +374,70 @@ export class DataEntity {
     if (defIndex >= 0) {
       this.root.definitions.properties.splice(defIndex, 1)
     }
+    this.removeField(key)
     propertyToRemove.remove()
   }
 
+  private removeField(key: string): void {
+    this.fields = this.fields.filter((item) => item.key !== key)
+  }
+
   /**
    * Lists all properties for this Entity.
    * @returns The list of properties that belong to this entity.
    */
   listProperties(): DataProperty[] {
-    const result: DataProperty[] = []
-    for (const prop of this.properties) {
-      this.root.definitions.properties.find((p) => p.key === prop.key)
-      if (prop) {
-        result.push(prop)
+    return [...this.properties]
+  }
+
+  /**
+   * Lists all associations for this Entity.
+   * @returns The list of associations that belong to this entity.
+   */
+  listAssociations(): DataAssociation[] {
+    return [...this.associations]
+  }
+
+  /**
+   * Generates an ordered list of fields (properties and associations) for this entity.
+   *
+   * @returns The list of fields (properties and associations) that belong to this entity.
+   */
+  listFields(): (DataAssociation | DataProperty)[] {
+    const result: (DataAssociation | DataProperty)[] = []
+    this.fields.forEach((i) => {
+      if (i.type === 'property') {
+        const property = this.properties.find((p) => p.key === i.key)
+        if (property) {
+          result.push(property)
+        }
+      } else if (i.type === 'association') {
+        const association = this.associations.find((a) => a.key === i.key)
+        if (association) {
+          result.push(association)
+        }
       }
-    }
+    })
     return result
   }
 
+  /**
+   * Moves the field to a new index.
+   * @param key The key of the field to move.
+   * @param toIndex The new index to which move the field to.
+   */
+  moveField(key: string, toIndex: number): void {
+    const fromIndex = this.fields.findIndex((i) => i.key === key)
+    if (fromIndex < 0) {
+      throw new ValidationError([{ field: 'fields', message: `Field ${key} not found.`, rule: 'not-found' }])
+    }
+    if (toIndex < 0 || toIndex >= this.fields.length) {
+      throw new ValidationError([{ field: 'fields', message: `Invalid index ${toIndex}.`, rule: 'invalid' }])
+    }
+    const [item] = this.fields.splice(fromIndex, 1)
+    this.fields.splice(toIndex, 0, item)
+  }
+
   /**
    * Creates an association for a given name, adds it to definitions, and returns it.
    * @param name The name of the association
@@ -343,6 +447,7 @@ export class DataEntity {
     const result = DataAssociation.fromName(this.root, name)
     this.root.definitions.associations.push(result)
     this.associations.push(result)
+    this.fields.push({ type: 'association', key: result.key })
     return result
   }
 
@@ -367,6 +472,7 @@ export class DataEntity {
     }
     this.root.definitions.associations.push(result)
     this.associations.push(result)
+    this.fields.push({ type: 'association', key: result.key })
     return result
   }
 
@@ -395,6 +501,7 @@ export class DataEntity {
     }
     this.root.definitions.associations.push(result)
     this.associations.push(result)
+    this.fields.push({ type: 'association', key: result.key })
     return result
   }
 
@@ -414,6 +521,7 @@ export class DataEntity {
     if (defIndex >= 0) {
       this.root.definitions.associations.splice(defIndex, 1)
     }
+    this.removeField(key)
     associationToRemove.remove()
   }
 
@@ -511,6 +619,12 @@ export class DataEntity {
     return this.root.definitions.models.find((m) => m.entities.some((e) => e === this))
   }
 
+  /**
+   * Adds a parent reference to this entity.
+   * This will not add the parent to the namespace. It only adds a reference to the parent.
+   * @param key The key of the parent entity to add.
+   * @returns `this` for chaining.
+   */
   addParent(key: string): this {
     // Prevent adding self as parent
     if (key === this.key) {
@@ -555,6 +669,20 @@ export class DataEntity {
         { message }
       )
     }
+    const has = this.parents.some((i) => i === key)
+    if (has) {
+      const message = `Parent ${key} already exists.`
+      throw new ValidationError(
+        [
+          {
+            field: 'parents',
+            message,
+            rule: 'exists',
+          },
+        ],
+        { message }
+      )
+    }
     this.parents.push(key)
     return this
   }
@@ -622,19 +750,27 @@ export class DataEntity {
   }
 
   /**
-   * Returns a list of entities that are associated with this entity through an association
-   * that the target property points to this entity.
+   * Returns a list of entities that are associated with this entity as a target.
    *
-   * In other words, if entity `A` has association target with `B`, then asking `B` for related entities will
-   * result with `[A]`.
+   * This method identifies entities that have an association where this entity is a target.
+   * In other words, it finds entities that "point to" this entity through an association.
+   *
+   * For example, consider the following relationships:
    *
    * ```plain
-   * A -> B -> C
-   * D -> C
+   * A -> B  (A has an association that targets B)
+   * C -> B  (C has an association that targets B)
+   * B -> D  (B has an association that targets D)
    *
-   * C => [B, D]
-   * B => [A, C]
+   * Calling `getRelatedEntities()` on B would return [A, C]
+   * Calling `getRelatedEntities()` on D would return [B]
+   * Calling `getRelatedEntities()` on A would return []
    * ```
+   *
+   * Note, this method only returns entities that are directly associated with this entity as a target.
+   * It does not traverse the association graph to find indirectly related entities.
+   *
+   * @returns An array of `DataEntity` instances that have an association targeting this entity.
    */
   getRelatedEntities(): DataEntity[] {
     const { key, root } = this
@@ -650,9 +786,9 @@ export class DataEntity {
     return result
   }
 
-  static getRelatedEntities(namespace: DataNamespace, entity: string): DataEntity[] {
+  static getRelatedEntities(namespace: DataNamespace, entityKey: string): DataEntity[] {
     const result: DataEntity[] = []
-    const inverse = namespace.definitions.associations.filter((i) => i.targets.some((j) => j.key === entity))
+    const inverse = namespace.definitions.associations.filter((i) => i.targets.some((j) => j.key === entityKey))
     inverse.forEach((assoc) => {
       const entity = namespace.definitions.entities.find((e) => e.associations.includes(assoc))
       if (entity && !result.includes(entity)) {

package/src/modeling/DataFormat.ts

@@ -45,6 +45,9 @@ export enum DataPropertyList {
   file = 'binary',
 }
 
+/**
+ * The data property "attributes".
+ */
 export type DataPropertyAttribute =
   | 'required'
   | 'multiple'
@@ -64,6 +67,13 @@ export const DataPropertyAttributes: DataPropertyAttribute[] = [
   'deprecated',
 ]
 
+/**
+ * The data attribute "attributes".
+ */
+export type DataAttributeAttribute = 'required' | 'multiple'
+
+export const DataAttributeAttributes: DataAttributeAttribute[] = ['required', 'multiple']
+
 /**
  * Note, OAS supports the `integer` data type and not format.
  * We need to account for that.

package/src/modeling/DataNamespace.ts

@@ -24,8 +24,11 @@ interface IDataDefinitions {
 
 interface DataDefinitions {
   models: DataModel[]
+  // @todo: This should be a map of entities with a key of the entity key.
   entities: DataEntity[]
+  // @todo: This should be a map of properties with a key of the property key.
   properties: DataProperty[]
+  // @todo: This should be a map of associations with a key of the association key.
   associations: DataAssociation[]
   namespaces: DataNamespace[]
   /**
@@ -672,6 +675,16 @@ export class DataNamespace extends DataNamespaceParent {
     return definitions.properties.find((i) => i.key === key)
   }
 
+  /**
+   * Finds an association by its key.
+   * @param key The key of the property to find
+   * @returns The property or undefined if not found.
+   */
+  findAssociation(key: string): DataAssociation | undefined {
+    const { definitions } = this.root || this
+    return definitions.associations.find((i) => i.key === key)
+  }
+
   /**
    * Searches for entities for association targets.
    * This is a helper function to discover entities in the current and foreign namespaces.