@api-client/core 0.14.6 → 0.14.8

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

@@ -42062,10 +42062,10 @@
 "@id": "#209"
 },
 {
-"@id": "#191"
+"@id": "#194"
 },
 {
-"@id": "#194"
+"@id": "#191"
 },
 {
 "@id": "#197"
@@ -42810,6 +42810,9 @@
 "@id": "#219"
 },
 {
+"@id": "#219"
+},
+{
 "@id": "#210"
 },
 {
@@ -42817,9 +42820,6 @@
 },
 {
 "@id": "#213"
-},
-{
-"@id": "#219"
 }
 ],
 "doc:root": false,
@@ -43436,7 +43436,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "countryCode: \"BE\"\ngraydonEnterpriseId: 1057155523\nregistrationId: \"0422319093\"\nvatNumber: \"BE0422319093\"\ngraydonCompanyId: \"0422319093\"\nisBranchOffice: false\n",
+"doc:raw": "addressType: 'REGISTERED-OFFICE-ADDRESS'\nstreetName: 'UITBREIDINGSTRAAT'\nhouseNumber: '84'\nhouseNumberAddition: '/1'\npostalCode: '2600'\ncity: 'BERCHEM (ANTWERPEN)'\ncountry: 'Belgium'\ncountryCode: 'BE'\nfullFormatedAddress: \"UITBREIDINGSTRAAT 84 /1, 2600 BERCHEM (ANTWERPEN), BELIUM\"\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43457,7 +43457,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "addressType: 'REGISTERED-OFFICE-ADDRESS'\nstreetName: 'UITBREIDINGSTRAAT'\nhouseNumber: '84'\nhouseNumberAddition: '/1'\npostalCode: '2600'\ncity: 'BERCHEM (ANTWERPEN)'\ncountry: 'Belgium'\ncountryCode: 'BE'\nfullFormatedAddress: \"UITBREIDINGSTRAAT 84 /1, 2600 BERCHEM (ANTWERPEN), BELIUM\"\n",
+"doc:raw": "countryCode: \"BE\"\ngraydonEnterpriseId: 1057155523\nregistrationId: \"0422319093\"\nvatNumber: \"BE0422319093\"\ngraydonCompanyId: \"0422319093\"\nisBranchOffice: false\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44232,7 +44232,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": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '21'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)21 302099'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44253,7 +44253,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\"\nvalue: \"www.company.be\"\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44274,7 +44274,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '21'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)21 302099'\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": [
 {
@@ -44295,7 +44295,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: \"GENERAL\"\nvalue: \"www.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": [
 {
@@ -44756,12 +44756,12 @@
 {
 "@id": "#193/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#193",
-"sourcemaps:value": "[(1,0)-(7,0)]"
+"sourcemaps:value": "[(1,0)-(10,0)]"
 },
 {
 "@id": "#196/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#196",
-"sourcemaps:value": "[(1,0)-(10,0)]"
+"sourcemaps:value": "[(1,0)-(7,0)]"
 },
 {
 "@id": "#199/source-map/lexical/element_0",
@@ -45121,17 +45121,17 @@
 {
 "@id": "#215/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#215",
-"sourcemaps:value": "[(1,0)-(7,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#218/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#218",
-"sourcemaps:value": "[(1,0)-(6,0)]"
+"sourcemaps:value": "[(1,0)-(7,0)]"
 },
 {
 "@id": "#221/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#221",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(6,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.14.6",
+  "version": "0.14.8",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {

package/src/amf/ApiSchemaValues.ts

@@ -15,7 +15,7 @@ import {
   IApiScalarShape,
   IShapeUnion,
 } from './definitions/Shapes.js'
-import { ILoremWordInit, ITypeHashInit, ITypeNumberInit } from '@pawel-up/data-mock/types.js'
+import type { ILoremWordInit, ITypeHashInit, ITypeNumberInit } from '@pawel-up/data-mock/types.js'
 
 export interface IApiSchemaReadOptions {
   /**

package/src/modeling/ApiModel.ts

@@ -1,18 +1,20 @@
 import { nanoid } from '../nanoid.js'
-import { ApiModelKind } from '../models/kinds.js'
+import { ApiModelKind, DataDomainKind } from '../models/kinds.js'
 import { type IThing, Thing } from '../models/Thing.js'
 import type {
   AccessRule,
   AuthenticationConfiguration,
   AuthorizationConfiguration,
   ExposedEntity,
-  ForeignDomainDependency,
   RateLimitingConfiguration,
+  RolesBasedAccessControl,
   SessionConfiguration,
+  UsernamePasswordConfiguration,
 } from './types.js'
-import { DataDomain, type DataDomainSchema } from './DataDomain.js'
+import { DataDomain } from './DataDomain.js'
+import { DependentModel, type DomainDependency, type DependentModelSchema } from './DependentModel.js'
 
-export interface ApiModelSchema {
+export interface ApiModelSchema extends DependentModelSchema {
   /**
    * The data domain kind recognizable by the ecosystem.
    */
@@ -35,12 +37,6 @@ export interface ApiModelSchema {
    */
   userKey?: string
 
-  /**
-   * Reference to the stable, version-controlled data definition from the
-   * Data Catalog. When not set, the model cannot be published.
-   */
-  domain?: ForeignDomainDependency
-
   /**
    * Configuration for how users prove their identity.
    * The API model is invalid if this is not set.
@@ -80,7 +76,7 @@ export interface ApiModelSchema {
   rateLimiting?: RateLimitingConfiguration
 }
 
-export class ApiModel extends EventTarget {
+export class ApiModel extends DependentModel {
   /**
    * The data domain kind recognizable by the ecosystem.
    */
@@ -103,12 +99,6 @@ export class ApiModel extends EventTarget {
    */
   userKey?: string
 
-  /**
-   * Reference to the stable, version-controlled data definition from the
-   * Data Catalog. When not set, the model cannot be published.
-   */
-  domain?: ForeignDomainDependency
-
   /**
    * Configuration for how users prove their identity.
    * The API model is invalid if this is not set.
@@ -161,9 +151,20 @@ export class ApiModel extends EventTarget {
   #notifying = false
 
   /**
-   * A reference to the published data domain.
+   * A convenience getter that returns the DataDomain associated with this API model.
+   * Since the API model can have only one DataDomain,
+   * this getter returns the first dependency in the list.
+   *
+   * The parent interface `DependentModel` allows for multiple dependencies,
+   * to unify the dependency management across different models.
    */
-  dataDomain?: DataDomain
+  get domain(): DataDomain | undefined {
+    if (this.dependencyList.length === 0) {
+      return undefined
+    }
+    const domain = this.dependencyList[0]
+    return this.dependencies.get(domain.key)
+  }
 
   static createSchema(input: Partial<ApiModelSchema> = {}): ApiModelSchema {
     const { key = nanoid(), exposes = [] } = input
@@ -177,8 +178,8 @@ export class ApiModel extends EventTarget {
     if (input.userKey) {
       result.userKey = input.userKey
     }
-    if (input.domain) {
-      result.domain = input.domain
+    if (input.dependencyList) {
+      result.dependencyList = structuredClone(input.dependencyList)
     }
     if (input.authentication) {
       result.authentication = input.authentication
@@ -198,16 +199,21 @@ export class ApiModel extends EventTarget {
     return result
   }
 
-  constructor(state?: Partial<ApiModelSchema>, domain?: DataDomainSchema) {
-    super()
+  constructor(state?: Partial<ApiModelSchema>, domain?: DomainDependency) {
     const init = ApiModel.createSchema(state)
+    const instances: DataDomain[] = []
+    if (domain instanceof DataDomain) {
+      instances.push(domain)
+    } else if (typeof domain === 'object' && domain.kind === DataDomainKind) {
+      instances.push(new DataDomain(domain))
+    } else if (domain) {
+      throw new Error(`Invalid domain provided. Expected a DataDomain instance or schema.`)
+    }
+    super(init.dependencyList, instances)
     this.kind = init.kind
     this.key = init.key
     this.info = new Thing(init.info)
     this.userKey = init.userKey
-    if (init.domain) {
-      this.domain = structuredClone(init.domain)
-    }
     if (init.authentication) {
       this.authentication = structuredClone(init.authentication)
     }
@@ -228,9 +234,6 @@ export class ApiModel extends EventTarget {
     if (init.rateLimiting) {
       this.rateLimiting = structuredClone(init.rateLimiting)
     }
-    if (domain) {
-      this.dataDomain = new DataDomain(domain)
-    }
     this.#initializing = false
     this.info.addEventListener('change', () => {
       this.notifyChange()
@@ -247,8 +250,8 @@ export class ApiModel extends EventTarget {
     if (this.userKey) {
       result.userKey = this.userKey
     }
-    if (this.domain) {
-      result.domain = structuredClone(this.domain)
+    if (this.dependencyList.length > 0) {
+      result.dependencyList = structuredClone(this.dependencyList)
     }
     if (this.authentication) {
       result.authentication = structuredClone(this.authentication)
@@ -324,4 +327,44 @@ export class ApiModel extends EventTarget {
   getExposedEntity(entityKey: string): ExposedEntity | undefined {
     return this.exposes.find((e) => e.key === entityKey)
   }
+
+  /**
+   * Clears the API model for a new entity change.
+   * This method resets the dependencies, exposes, userKey,
+   * authentication, authorization, and session properties.
+   */
+  cleanForEntityChange(): void {
+    this.dependencies.clear()
+    this.dependencyList = []
+    this.exposes = []
+    this.userKey = undefined
+    if (this.session) {
+      this.session.properties = []
+    }
+    if (this.authentication && this.authentication.strategy === 'UsernamePassword') {
+      const typed = this.authentication as UsernamePasswordConfiguration
+      typed.passwordKey = undefined
+    }
+    if (this.authorization && this.authorization.strategy == 'RBAC') {
+      const typed = this.authorization as RolesBasedAccessControl
+      typed.roleKey = ''
+    }
+  }
+
+  /**
+   * Attaches a DataDomain to this API model.
+   * This method clears any existing dependencies and sets the new domain.
+   *
+   * @param domain The DataDomain to attach to this API model.
+   * @throws Error if the domain does not have a version set in its info.
+   */
+  attachDataDomain(domain: DataDomain): void {
+    if (!domain.info.version) {
+      throw new Error(`Cannot attach DataDomain without a version. Please set the version in the domain info.`)
+    }
+    this.cleanForEntityChange()
+    this.dependencies.set(domain.key, domain)
+    this.dependencyList = [{ key: domain.key, version: domain.info.version }]
+    this.notifyChange()
+  }
 }

package/src/modeling/DataDomain.ts

@@ -8,13 +8,7 @@ import {
   DomainNamespaceKind,
   DomainPropertyKind,
 } from '../models/kinds.js'
-import type {
-  AssociationAddOptions,
-  DomainGraphEdge,
-  DomainGraphNodeType,
-  ForeignDomainDependency,
-  SerializedGraph,
-} from './types.js'
+import type { AssociationAddOptions, DomainGraphEdge, DomainGraphNodeType, SerializedGraph } from './types.js'
 import { type DomainNamespaceSchema, DomainNamespace, type NamespaceOrderedItem } from './DomainNamespace.js'
 import { type DomainModelSchema, DomainModel } from './DomainModel.js'
 import { type DomainEntitySchema, DomainEntity } from './DomainEntity.js'
@@ -23,13 +17,13 @@ import { DomainProperty, DomainPropertySchema } from './DomainProperty.js'
 import { type IThing, Thing } from '../models/Thing.js'
 import { removeGraphNode } from './GraphUtils.js'
 import { serialize, deserialize, mergeGraph, removeForeignGraph } from './DomainSerialization.js'
+import { DependentModel, type DependentModelSchema, type DomainDependency } from './DependentModel.js'
 
-export interface DataDomainSchema {
+export interface DataDomainSchema extends DependentModelSchema {
   info: IThing
   kind: typeof DataDomainKind
   key: string
   graph?: SerializedGraph
-  dependencyList?: ForeignDomainDependency[]
   /**
    * The ordered list of fields (namespace and models) in the schema.
    * These only keep references to define the order of these properties
@@ -104,7 +98,7 @@ export interface DataDomainSchema {
  * @todo: Implement a mechanism to move an entity to a new
  * parent model.
  */
-export class DataDomain extends EventTarget {
+export class DataDomain extends DependentModel {
   /**
    * The kind of the domain element.
    */
@@ -119,18 +113,6 @@ export class DataDomain extends EventTarget {
    */
   graph: Graph<unknown, DomainGraphNodeType, DomainGraphEdge>
 
-  /**
-   * A map of foreign data domains.
-   * Key: The unique identifier of the foreign domain.
-   * Value: The foreign DataDomain instance.
-   */
-  dependencies: Map<string, DataDomain> = new Map<string, DataDomain>()
-
-  /**
-   * The list of foreign domain dependencies.
-   */
-  dependencyList: ForeignDomainDependency[] = []
-
   /**
    * The description of the domain property.
    */
@@ -196,13 +178,24 @@ export class DataDomain extends EventTarget {
    * @param state The previously serialized state of the graph.
    * @param dependencies An array of foreign data domains to register with this domain.
    */
-  constructor(state?: Partial<DataDomainSchema>, dependencies?: DataDomain[]) {
-    super()
+  constructor(state?: Partial<DataDomainSchema>, dependencies: DomainDependency[] = []) {
     const init = DataDomain.createSchema(state)
+    const instances: DataDomain[] = []
+    for (const dep of dependencies) {
+      if (dep instanceof DataDomain) {
+        instances.push(dep)
+      } else if (typeof dep === 'object' && dep.kind === DataDomainKind && dep.key) {
+        const domain = new DataDomain(dep)
+        instances.push(domain)
+      } else {
+        throw new Error(`Invalid foreign domain dependency: ${dep}`)
+      }
+    }
+    super(init.dependencyList, instances)
     this.kind = init.kind
     this.key = init.key
     this.info = new Thing(init.info)
-    this.graph = deserialize(this, init.graph, dependencies)
+    this.graph = deserialize(this, init.graph, instances)
     if (Array.isArray(init.fields)) {
       this.fields = [...init.fields]
     } else {
@@ -438,10 +431,41 @@ export class DataDomain extends EventTarget {
     }
   }
 
+  /**
+   * Builds a reference key for a domain object.
+   *
+   * If the namespace is provided and it is different from the domain key,
+   * it will return the key in the format `namespace:key`. The foreign namespace
+   * must be registered in the domain's dependencies otherwise an error will be thrown.
+   *
+   * @param key The key of the namespace or model.
+   * @param namespace The namespace to search in. When different from the domain key, it looks for a foreign namespace.
+   * @returns The reference key in the format `namespace:key` or just `key` if no namespace is provided.
+   * @throws Error When the foreign domain is not found.
+   * @example
+   * ```typescript
+   * const refKey = dataDomain.buildReferenceKey('userModel', 'domainKey');
+   * ```
+   */
+  buildReferenceKey(key: string, namespace?: string): string {
+    if (namespace && namespace !== this.key) {
+      if (typeof namespace !== 'string' || namespace.length === 0) {
+        throw new Error(`Invalid namespace key. Expected a string, got ${typeof namespace}`)
+      }
+      const foreignDomain = this.dependencies.get(namespace)
+      if (!foreignDomain) {
+        throw new Error(`Foreign domain ${namespace} not found`)
+      }
+      return `${namespace}:${key}`
+    }
+    return key
+  }
+
   /**
    * Finds a namespace by its key.
    *
    * @param key The key of the namespace to find.
+   * @param namespace The namespace to search in. When different from the domain key, it looks for a foreign namespace.
    * @returns The namespace instance or undefined if not
    *   found.
    * @example
@@ -452,8 +476,8 @@ export class DataDomain extends EventTarget {
    * }
    * ```
    */
-  findNamespace(key: string): DomainNamespace | undefined {
-    const result = this.graph.node(key) as DomainNamespace | undefined
+  findNamespace(key: string, namespace?: string): DomainNamespace | undefined {
+    const result = this.graph.node(this.buildReferenceKey(key, namespace)) as DomainNamespace | undefined
     if (result && result.kind === DomainNamespaceKind) {
       return result
     }
@@ -696,6 +720,7 @@ export class DataDomain extends EventTarget {
    * Finds a data model by its key.
    *
    * @param key The key of the data model to find.
+   * @param namespace The namespace to search in. When different from the domain key, it looks for a foreign entity.
    * @returns The data model instance or undefined if not
    *   found.
    * @example
@@ -706,8 +731,8 @@ export class DataDomain extends EventTarget {
    * }
    * ```
    */
-  findModel(key: string): DomainModel | undefined {
-    const value = this.graph.node(key) as DomainModel | undefined
+  findModel(key: string, namespace?: string): DomainModel | undefined {
+    const value = this.graph.node(this.buildReferenceKey(key, namespace)) as DomainModel | undefined
     if (value && value.kind === DomainModelKind) {
       return value
     }
@@ -884,6 +909,7 @@ export class DataDomain extends EventTarget {
    * Finds an entity by its key.
    *
    * @param key The key of the entity to find.
+   * @param namespace The namespace to search in. When different from the domain key, it looks for a foreign entity.
    * @returns The entity instance or undefined if not found.
    * @example
    * ```typescript
@@ -893,8 +919,8 @@ export class DataDomain extends EventTarget {
    * }
    * ```
    */
-  findEntity(key: string): DomainEntity | undefined {
-    const node = this.graph.node(key) as DomainEntity | undefined
+  findEntity(key: string, namespace?: string): DomainEntity | undefined {
+    const node = this.graph.node(this.buildReferenceKey(key, namespace)) as DomainEntity | undefined
     if (node && node.kind === DomainEntityKind) {
       return node
     }
@@ -1012,6 +1038,7 @@ export class DataDomain extends EventTarget {
    * Finds an association by its key.
    *
    * @param key The key of the association to find.
+   * @param namespace The namespace to search in. When different from the domain key, it looks for a foreign association
    * @returns The association instance or undefined if not
    *   found.
    * @example
@@ -1022,8 +1049,8 @@ export class DataDomain extends EventTarget {
    * }
    * ```
    */
-  findAssociation(key: string): DomainAssociation | undefined {
-    const node = this.graph.node(key) as DomainAssociation | undefined
+  findAssociation(key: string, namespace?: string): DomainAssociation | undefined {
+    const node = this.graph.node(this.buildReferenceKey(key, namespace)) as DomainAssociation | undefined
     if (node && node.kind === DomainAssociationKind) {
       return node
     }
@@ -1097,6 +1124,7 @@ export class DataDomain extends EventTarget {
    * Finds a property by its key.
    *
    * @param key The key of the property to find.
+   * @param namespace The namespace to search in. When different from the domain key, it looks for a foreign property
    * @returns The property instance or undefined if not
    *   found.
    * @example
@@ -1107,8 +1135,8 @@ export class DataDomain extends EventTarget {
    * }
    * ```
    */
-  findProperty(key: string): DomainProperty | undefined {
-    const node = this.graph.node(key) as DomainProperty | undefined
+  findProperty(key: string, namespace?: string): DomainProperty | undefined {
+    const node = this.graph.node(this.buildReferenceKey(key, namespace)) as DomainProperty | undefined
     if (node && node.kind === DomainPropertyKind) {
       return node
     }
@@ -1182,6 +1210,8 @@ export class DataDomain extends EventTarget {
    *   console.log(foreignUser.key);
    * }
    * ```
+   * @deprecated Use `findEntity` with the `namespace` parameter instead.
+   * This method is kept for backward compatibility but will be removed in the future.
    */
   findForeignEntity(entityKey: string, domainKey: string): DomainEntity | undefined {
     const foreignDomain = this.dependencies.get(domainKey)

package/src/modeling/DependentModel.ts

@@ -0,0 +1,36 @@
+import type { DataDomain, DataDomainSchema } from './DataDomain.js'
+import type { ForeignDomainDependency } from './types.js'
+
+export type DomainDependency = DataDomain | DataDomainSchema
+
+export interface DependentModelSchema {
+  /**
+   * A list of foreign domain dependencies.
+   */
+  dependencyList?: ForeignDomainDependency[]
+}
+
+/**
+ * A base model that has dependencies on foreign data domains.
+ */
+export class DependentModel extends EventTarget {
+  /**
+   * A map of foreign data domains.
+   * Key: The unique identifier of the foreign domain.
+   * Value: The foreign DataDomain instance.
+   */
+  dependencies: Map<string, DataDomain> = new Map<string, DataDomain>()
+
+  /**
+   * The list of foreign domain dependencies.
+   */
+  dependencyList: ForeignDomainDependency[] = []
+
+  constructor(items: ForeignDomainDependency[] = [], instances: DataDomain[] = []) {
+    super()
+    this.dependencyList = [...items]
+    for (const dep of instances) {
+      this.dependencies.set(dep.key, dep)
+    }
+  }
+}

package/src/modeling/types.ts

@@ -337,6 +337,8 @@ export interface SessionConfiguration {
   /**
    * The properties from the `User` entity to be encoded into the session payload (JWT/cookie).
    * These properties become available in the `request.auth` object at runtime.
+   *
+   * In practice, these are the ids of the properties in the `User` entity.
    */
   properties: string[]
   /**