@api-client/core 0.14.2 → 0.14.3

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

@@ -42071,13 +42071,13 @@
 "@id": "#197"
 },
 {
-"@id": "#200"
+"@id": "#206"
 },
 {
-"@id": "#203"
+"@id": "#200"
 },
 {
-"@id": "#206"
+"@id": "#203"
 },
 {
 "@id": "#209"
@@ -42810,6 +42810,9 @@
 "@id": "#219"
 },
 {
+"@id": "#219"
+},
+{
 "@id": "#210"
 },
 {
@@ -42817,9 +42820,6 @@
 },
 {
 "@id": "#216"
-},
-{
-"@id": "#219"
 }
 ],
 "doc:root": false,
@@ -43499,7 +43499,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
+"doc:raw": "code: 'J'\ndescription: 'Information and communication'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43520,7 +43520,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: 'J'\ndescription: 'Information and communication'\n",
+"doc:raw": "code: '7487'\ndescription: 'Financial and insurance activities'\ntype: \"PRIMARY\"\nclassificationCode: 'BE_NACEBEL2008'\nactivityGroupCode: 'ABCDE'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43541,7 +43541,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: '7487'\ndescription: 'Financial and insurance activities'\ntype: \"PRIMARY\"\nclassificationCode: 'BE_NACEBEL2008'\nactivityGroupCode: 'ABCDE'\n",
+"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\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": "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": [
 {
@@ -44274,7 +44274,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": [
 {
@@ -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": [
 {
@@ -44771,17 +44771,17 @@
 {
 "@id": "#202/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#202",
-"sourcemaps:value": "[(1,0)-(5,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#205/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#205",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(6,0)]"
 },
 {
 "@id": "#208/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#208",
-"sourcemaps:value": "[(1,0)-(6,0)]"
+"sourcemaps:value": "[(1,0)-(5,0)]"
 },
 {
 "@id": "#223/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)-(6,0)]"
+"sourcemaps:value": "[(1,0)-(7,0)]"
 },
 {
 "@id": "#218/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#218",
-"sourcemaps:value": "[(1,0)-(7,0)]"
+"sourcemaps:value": "[(1,0)-(3,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.2",
+  "version": "0.14.3",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {
@@ -135,7 +135,7 @@
     "oauth2-mock-server": "^8.0.0",
     "playwright": "^1.50.1",
     "prettier": "^3.5.1",
-    "sinon": "^20.0.0",
+    "sinon": "^21.0.0",
     "ts-lit-plugin": "^2.0.2",
     "ts-node-maintained": "^10.9.5",
     "typescript": "^5.5.2",
@@ -157,7 +157,6 @@
     "test:coverage": "wireit",
     "test:node": "node --import ts-node-maintained/register/esm --enable-source-maps bin/test.ts",
     "test:node:coverage": "c8 --reporter lcov --reporter text node --import ts-node-maintained/register/esm --enable-source-maps bin/test.ts",
-    "test:node:watch": "node --import ts-node-maintained/register/esm --enable-source-maps bin/test.ts --watch",
     "build:api-models": "node data/model.js",
     "copy:assets": "cp -f ./oauth-popup.html ./build/oauth-popup.html",
     "start": "echo \"Use the npm run dev instead\"",

package/src/modeling/ApiFile.ts

@@ -0,0 +1,53 @@
+import { File, type IFile } from '../models/store/File.js'
+import { ApiFileKind } from '../models/kinds.js'
+import { ApiModel, ApiModelSchema } from './ApiModel.js'
+
+export interface IApiFile extends IFile {
+  kind: typeof ApiFileKind
+}
+
+/**
+ * Used by the store. A file definition for the ApiModel.
+ */
+export class ApiFile extends File {
+  override kind = ApiFileKind
+
+  static override fromName(name: string): ApiFile {
+    return super.fromName(name, ApiFileKind) as ApiFile
+  }
+
+  /**
+   * Creates the file definition for a DomainNamespace contents.
+   *
+   * @param input The data namespace instance or schema.
+   */
+  static fromApiModel(input: ApiModel | ApiModelSchema): ApiFile {
+    let final: ApiModelSchema
+    if (typeof (input as ApiModel).toJSON === 'function') {
+      final = (input as ApiModel).toJSON()
+    } else {
+      final = input as ApiModelSchema
+    }
+    return new ApiFile({ key: final.key, info: final.info })
+  }
+
+  constructor(state: Partial<IApiFile> = {}) {
+    super({ ...state, kind: ApiFileKind })
+  }
+
+  static isApiFile(input: unknown): boolean {
+    const typed = input as IApiFile
+    if (!input || typed.kind !== ApiFileKind) {
+      return false
+    }
+    return true
+  }
+
+  override toJSON(): IApiFile {
+    const result: IApiFile = {
+      ...super.toJSON(),
+      kind: ApiFileKind,
+    }
+    return result
+  }
+}

package/src/modeling/ApiModel.ts

@@ -0,0 +1,327 @@
+import { nanoid } from '../nanoid.js'
+import { ApiModelKind } from '../models/kinds.js'
+import { type IThing, Thing } from '../models/Thing.js'
+import type {
+  AccessRule,
+  AuthenticationConfiguration,
+  AuthorizationConfiguration,
+  ExposedEntity,
+  ForeignDomainDependency,
+  RateLimitingConfiguration,
+  SessionConfiguration,
+} from './types.js'
+import { DataDomain, type DataDomainSchema } from './DataDomain.js'
+
+export interface ApiModelSchema {
+  /**
+   * The data domain kind recognizable by the ecosystem.
+   */
+  kind: typeof ApiModelKind
+  /**
+   * The unique key of the data domain schema.
+   * This is a stable identifier that does not change across versions.
+   */
+  key: string
+  /**
+   * Contains the name, display name, description, and the version of the data domain schema.
+   */
+  info: IThing
+
+  /**
+   * The designated Data Entity that represents a "User".
+   * This entity must be marked with the "User" semantic in the Data Modeler.
+   *
+   * This property is required to publish the API.
+   */
+  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.
+   */
+  authentication?: AuthenticationConfiguration
+
+  /**
+   * Configuration for what authenticated users are allowed to do.
+   * The API model is invalid if this is not set.
+   */
+  authorization?: AuthorizationConfiguration
+
+  /**
+   * Configuration for the transport and payload of the user session.
+   * The API model is invalid if this is not set.
+   */
+  session?: SessionConfiguration
+  /**
+   * The specific subset of Data Entities to be exposed by this API.
+   * These are the entities that are included in the data domain schema.
+   */
+  exposes: ExposedEntity[]
+
+  /**
+   * Optional array of access rules that define the access control policies
+   * for the API. These rules are used to enforce security and permissions
+   * on the exposed entities.
+   *
+   * These rules apply to all exposed entities and actions. An API action
+   * can declare its own access rules, which will override these.
+   */
+  accessRule?: AccessRule[]
+  /**
+   * Optional configuration for API-wide rate limiting and throttling.
+   * Defines rules to protect the API from overuse.
+   */
+  rateLimiting?: RateLimitingConfiguration
+}
+
+export class ApiModel extends EventTarget {
+  /**
+   * The data domain kind recognizable by the ecosystem.
+   */
+  kind: typeof ApiModelKind
+  /**
+   * The unique key of the data domain schema.
+   * This is a stable identifier that does not change across versions.
+   */
+  key: string
+
+  /**
+   * The description of the domain property.
+   */
+  info: Thing
+  /**
+   * The designated Data Entity that represents a "User".
+   * This entity must be marked with the "User" semantic in the Data Modeler.
+   *
+   * This property is required to publish the API.
+   */
+  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.
+   */
+  authentication?: AuthenticationConfiguration
+
+  /**
+   * Configuration for what authenticated users are allowed to do.
+   * The API model is invalid if this is not set.
+   */
+  authorization?: AuthorizationConfiguration
+
+  /**
+   * Configuration for the transport and payload of the user session.
+   * The API model is invalid if this is not set.
+   */
+  session?: SessionConfiguration
+  /**
+   * The specific subset of Data Entities to be exposed by this API.
+   * These are the entities that are included in the data domain schema.
+   */
+  exposes: ExposedEntity[]
+  /**
+   * Optional array of access rules that define the access control policies
+   * for the API. These rules are used to enforce security and permissions
+   * on the exposed entities.
+   *
+   * These rules apply to all exposed entities and actions. An API action
+   * can declare its own access rules, which will override these.
+   */
+  accessRule?: AccessRule[]
+  /**
+   * Optional configuration for API-wide rate limiting and throttling.
+   * Defines rules to protect the API from overuse.
+   */
+  rateLimiting?: RateLimitingConfiguration
+
+  /**
+   * When the initializing flag is set to true,
+   * the domain is not notified of changes.
+   */
+  #initializing = true
+
+  /**
+   * When the notifying flag is set to true,
+   * the domain is pending a notification.
+   * No other notifications will be sent until
+   * the current notification is sent.
+   */
+  #notifying = false
+
+  /**
+   * A reference to the published data domain.
+   */
+  dataDomain?: DataDomain
+
+  static createSchema(input: Partial<ApiModelSchema> = {}): ApiModelSchema {
+    const { key = nanoid(), exposes = [] } = input
+    const info = Thing.fromJSON(input.info, { name: 'Unnamed API' }).toJSON()
+    const result: ApiModelSchema = {
+      kind: ApiModelKind,
+      key,
+      info,
+      exposes,
+    }
+    if (input.userKey) {
+      result.userKey = input.userKey
+    }
+    if (input.domain) {
+      result.domain = input.domain
+    }
+    if (input.authentication) {
+      result.authentication = input.authentication
+    }
+    if (input.authorization) {
+      result.authorization = input.authorization
+    }
+    if (input.session) {
+      result.session = input.session
+    }
+    if (input.accessRule) {
+      result.accessRule = input.accessRule
+    }
+    if (input.rateLimiting) {
+      result.rateLimiting = input.rateLimiting
+    }
+    return result
+  }
+
+  constructor(state?: Partial<ApiModelSchema>, domain?: DataDomainSchema) {
+    super()
+    const init = ApiModel.createSchema(state)
+    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)
+    }
+    if (init.authorization) {
+      this.authorization = structuredClone(init.authorization)
+    }
+    if (init.session) {
+      this.session = structuredClone(init.session)
+    }
+    if (Array.isArray(init.exposes)) {
+      this.exposes = structuredClone(init.exposes)
+    } else {
+      this.exposes = []
+    }
+    if (init.accessRule) {
+      this.accessRule = structuredClone(init.accessRule)
+    }
+    if (init.rateLimiting) {
+      this.rateLimiting = structuredClone(init.rateLimiting)
+    }
+    if (domain) {
+      this.dataDomain = new DataDomain(domain)
+    }
+    this.#initializing = false
+    this.info.addEventListener('change', () => {
+      this.notifyChange()
+    })
+  }
+
+  toJSON(): ApiModelSchema {
+    const result: ApiModelSchema = {
+      kind: this.kind,
+      key: this.key,
+      info: this.info.toJSON(),
+      exposes: structuredClone(this.exposes),
+    }
+    if (this.userKey) {
+      result.userKey = this.userKey
+    }
+    if (this.domain) {
+      result.domain = structuredClone(this.domain)
+    }
+    if (this.authentication) {
+      result.authentication = structuredClone(this.authentication)
+    }
+    if (this.authorization) {
+      result.authorization = structuredClone(this.authorization)
+    }
+    if (this.session) {
+      result.session = structuredClone(this.session)
+    }
+    if (this.accessRule) {
+      result.accessRule = structuredClone(this.accessRule)
+    }
+    if (this.rateLimiting) {
+      result.rateLimiting = structuredClone(this.rateLimiting)
+    }
+    return result
+  }
+
+  /**
+   * This function is used internally by all domain elements to notify that something has changed.
+   * Since we want to notify listeners after the operation commits, we use microtask
+   * to ensure that the event is dispatched after the current operation.
+   */
+  notifyChange() {
+    if (this.#notifying || this.#initializing) {
+      return
+    }
+    this.#notifying = true
+    queueMicrotask(() => {
+      this.#notifying = false
+      const event = new Event('change')
+      this.dispatchEvent(event)
+    })
+  }
+
+  /**
+   * Exposes a new entity in the API model.
+   * If the entity already exists, it returns the existing one.
+   * @param entityKey The key of the entity to expose.
+   * @returns The exposed entity.
+   */
+  exposeEntity(entityKey: string): ExposedEntity {
+    const existing = this.exposes.find((e) => e.key === entityKey)
+    if (existing) {
+      return existing
+    }
+    const newEntity: ExposedEntity = {
+      key: entityKey,
+      actions: [],
+    }
+    this.exposes.push(newEntity)
+    this.notifyChange()
+    return newEntity
+  }
+
+  /**
+   * Removes an entity from the API model.
+   * @param entityKey The key of the entity to remove.
+   */
+  removeEntity(entityKey: string): void {
+    const index = this.exposes.findIndex((e) => e.key === entityKey)
+    if (index !== -1) {
+      this.exposes.splice(index, 1)
+      this.notifyChange()
+    }
+  }
+  /**
+   * Returns the exposed entity by its key.
+   * @param entityKey The key of the entity to find.
+   * @returns The exposed entity or undefined if not found.
+   */
+  getExposedEntity(entityKey: string): ExposedEntity | undefined {
+    return this.exposes.find((e) => e.key === entityKey)
+  }
+}

package/src/modeling/DataDomain.ts

@@ -134,7 +134,7 @@ export class DataDomain extends EventTarget {
   /**
    * The description of the domain property.
    */
-  accessor info: Thing
+  info: Thing
 
   /**
    * When the initializing flag is set to true,

package/src/modeling/DomainEntity.ts

@@ -165,7 +165,7 @@ export class DomainEntity extends DomainElement {
    */
   static createSchema(input: Partial<DomainEntitySchema> = {}): DomainEntitySchema {
     const { key = nanoid(), tags, semantics, fields, deprecated } = input
-    const info = Thing.fromJSON(input.info, { name: 'New entity' }).toJSON()
+    const info = Thing.fromJSON(input.info, { name: 'new_entity' }).toJSON()
     const result: DomainEntitySchema = {
       kind: DomainEntityKind,
       key,

package/src/modeling/DomainFile.ts

@@ -1,6 +1,4 @@
-import { nanoid } from '../nanoid.js'
 import { File, type IFile } from '../models/store/File.js'
-import { Thing } from '../models/Thing.js'
 import type { DataDomain, DataDomainSchema } from './DataDomain.js'
 import { DomainFileKind } from '../models/kinds.js'
 
@@ -30,46 +28,11 @@ export class DomainFile extends File {
     } else {
       final = input as DataDomainSchema
     }
-    const init: IDomainFile = {
-      kind: DomainFileKind,
-      key: final.key,
-      info: { ...final.info },
-      lastModified: { user: '', time: 0, byMe: false },
-      parents: [],
-      permissionIds: [],
-      permissions: [],
-    }
-    return new DomainFile(init)
+    return new DomainFile({ key: final.key, info: final.info })
   }
 
-  constructor(input?: string | IDomainFile) {
-    super()
-    let init: IDomainFile
-    if (typeof input === 'string') {
-      init = JSON.parse(input)
-    } else if (typeof input === 'object') {
-      init = input
-    } else {
-      init = {
-        kind: DomainFileKind,
-        key: nanoid(),
-        info: Thing.fromName('').toJSON(),
-        parents: [],
-        permissionIds: [],
-        permissions: [],
-        lastModified: { user: '', time: 0, byMe: false },
-      }
-    }
-    this.new(init)
-  }
-
-  override new(init: IDomainFile): this {
-    if (!DomainFile.isDomainFile(init)) {
-      throw new Error(`Not a data file.`)
-    }
-    super.new(init)
-    this.kind = DomainFileKind
-    return this
+  constructor(state: Partial<IDomainFile> = {}) {
+    super({ ...state, kind: DomainFileKind })
   }
 
   static isDomainFile(input: unknown): boolean {