@api-client/core 0.18.47 → 0.18.49

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

@@ -42065,15 +42065,15 @@
 "@id": "#191"
 },
 {
-"@id": "#200"
-},
-{
 "@id": "#194"
 },
 {
 "@id": "#197"
 },
 {
+"@id": "#200"
+},
+{
 "@id": "#203"
 },
 {
@@ -43457,7 +43457,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: '5'\ndescription: 'Limited company'\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": [
 {
@@ -43478,7 +43478,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
+"doc:raw": "code: '5'\ndescription: 'Limited company'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43499,7 +43499,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": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44761,17 +44761,17 @@
 {
 "@id": "#196/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#196",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(10,0)]"
 },
 {
 "@id": "#199/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#199",
-"sourcemaps:value": "[(1,0)-(5,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#202/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#202",
-"sourcemaps:value": "[(1,0)-(10,0)]"
+"sourcemaps:value": "[(1,0)-(5,0)]"
 },
 {
 "@id": "#205/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.18.47",
+  "version": "0.18.49",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {
@@ -99,7 +99,7 @@
     "chalk": "^5.4.1",
     "console-table-printer": "^2.11.2",
     "dompurify": "^3.2.6",
-    "jsdom": "^27.0.0",
+    "jsdom": "^28.0.0",
     "nanoid": "^5.1.5",
     "tslog": "^4.9.3",
     "ws": "^8.12.0",
@@ -113,7 +113,7 @@
     "@japa/assert": "^4.0.1",
     "@japa/browser-client": "^2.1.1",
     "@japa/expect-type": "^2.0.3",
-    "@japa/runner": "^4.2.0",
+    "@japa/runner": "^5.3.0",
     "@pawel-up/semver": "^0.1.4",
     "@rollup/plugin-typescript": "^12.1.2",
     "@types/chai-as-promised": "^8.0.2",

package/src/mocking/ModelingMock.ts

@@ -7,6 +7,7 @@ import { Invitation } from './lib/Invitation.js'
 import { Trash } from './lib/Trash.js'
 import { Patch } from './lib/Patch.js'
 import { DataCatalog } from './lib/DataCatalog.js'
+import { Permission } from './lib/Permission.js'
 
 export class ModelingMock {
   faker: Faker = faker
@@ -18,4 +19,5 @@ export class ModelingMock {
   trash = new Trash()
   patch = new Patch()
   dataCatalog = new DataCatalog()
+  permission = new Permission()
 }

package/src/mocking/lib/File.ts

@@ -6,6 +6,7 @@ import { nanoid } from '../../nanoid.js'
 export class File {
   /**
    * Generates a random file object.
+   * Note that this generator doesn't create the permissions object. Use Permission class for that.
    * @param init Optional values to be present in the object.
    * @returns Random file
    */

package/src/mocking/lib/Permission.ts

@@ -0,0 +1,100 @@
+import { faker } from '@faker-js/faker'
+import { nanoid } from '../../nanoid.js'
+import {
+  IPermission,
+  Kind as PermissionKind,
+  type PermissionRole,
+  type PermissionType,
+  type PermissionSourceRule,
+} from '../../models/store/Permission.js'
+
+export class Permission {
+  /**
+   * Generates a random permission object.
+   * @param init Configuration options for the permission object.
+   * @returns Random permission
+   */
+  permission(init: Partial<IPermission> = {}): IPermission {
+    const type = init.type ?? faker.helpers.arrayElement(['user', 'group', 'organization'] as PermissionType[])
+    const role = init.role ?? faker.helpers.arrayElement(['reader', 'commenter', 'writer', 'owner'] as PermissionRole[])
+
+    const result: IPermission = {
+      kind: PermissionKind,
+      key: init.key ?? nanoid(),
+      type,
+      granteeId: init.granteeId ?? nanoid(),
+      itemId: init.itemId ?? nanoid(),
+      role,
+      addingUser: init.addingUser ?? nanoid(),
+      depth: init.depth ?? 0,
+      sourceRule:
+        init.sourceRule ??
+        faker.helpers.arrayElement([
+          'direct_user_grant',
+          'creator_default_owner',
+          'parent_owner_editor_rule',
+        ] as PermissionSourceRule[]),
+    }
+
+    if ('displayName' in init) {
+      result.displayName = init.displayName
+    } else {
+      if (type === 'user') {
+        result.displayName = faker.person.fullName()
+      } else if (type === 'group') {
+        result.displayName = faker.lorem.word()
+      } else if (type === 'organization') {
+        result.displayName = faker.company.name()
+      }
+    }
+
+    if ('expirationTime' in init) {
+      result.expirationTime = init.expirationTime
+    } else if (type === 'user' || type === 'group') {
+      result.expirationTime = faker.date.future().getTime()
+    }
+
+    return result
+  }
+
+  /**
+   * Generates a random user permission object.
+   * @param init Configuration options for the permission object.
+   * @returns Random user permission
+   */
+  userPermission(init: Partial<IPermission> = {}): IPermission {
+    return this.permission({ ...init, type: 'user' })
+  }
+
+  /**
+   * Generates a random group permission object.
+   * @param init Configuration options for the permission object.
+   * @returns Random group permission
+   */
+  groupPermission(init: Partial<IPermission> = {}): IPermission {
+    return this.permission({ ...init, type: 'group' })
+  }
+
+  /**
+   * Generates a random organization permission object.
+   * @param init Configuration options for the permission object.
+   * @returns Random organization permission
+   */
+  organizationPermission(init: Partial<IPermission> = {}): IPermission {
+    return this.permission({ ...init, type: 'organization' })
+  }
+
+  /**
+   * Generates a list of random permission objects.
+   * @param size The size of the returning array. Default is 25.
+   * @param init Configuration options for the permission object.
+   * @returns List of random permissions
+   */
+  permissions(size = 25, init: Partial<IPermission> = {}): IPermission[] {
+    const result: IPermission[] = []
+    for (let i = 0; i < size; i++) {
+      result.push(this.permission(init))
+    }
+    return result
+  }
+}

package/src/modeling/ApiModel.ts

@@ -280,6 +280,16 @@ export class ApiModel extends DependentModel {
     } else if (domain) {
       throw new Error(`Invalid domain provided. Expected a DataDomain instance or schema.`)
     }
+    // Note that since we're using the `DependentModel` class, but the API Model can have only one dependency,
+    // we keep the reference to the data domain under the `dependencyList` property.
+    // It is all handled by the parent class `DependentModel`. This way we simplify the dependency management (loading)
+    // process when the API model is loaded from the API.
+    if (domain) {
+      if (!domain.info.version) {
+        throw new Error(`Domain ${domain.key} must have a version.`)
+      }
+      init.dependencyList = [{ key: domain.key, version: domain.info.version }]
+    }
     super(init.dependencyList, instances)
     this.kind = init.kind
     this.key = init.key
@@ -380,6 +390,12 @@ export class ApiModel extends DependentModel {
   /**
    * Exposes a new entity in the API model.
    * If the entity already exists, it returns the existing one.
+   *
+   * The logic regarding exposing an entity:
+   * - If the entity is already exposed as a root entity, it returns the existing one.
+   * - If the entity has an association, we expose that entity as a nested entity (by setting the parent property).
+   * - If the associated entity is already exposed as a root entity, we do not follow the association.
+   *
    * @param entity The entity key and domain to expose.
    * @returns The exposed entity.
    */
@@ -403,8 +419,18 @@ export class ApiModel extends DependentModel {
     }
     const name = domainEntity.info.name || ''
     const segment = pluralize(name.toLocaleLowerCase())
-    const relativeCollectionPath = `/${segment}`
-    const relativeResourcePath = `/${segment}/{id}`
+    let relativeCollectionPath = `/${segment}`
+    let relativeResourcePath = `/${segment}/{id}`
+
+    // Check for root path collision and resolve by appending a number
+    let counter = 1
+    const originalCollectionPath = relativeCollectionPath
+    while (this.exposes.some((e) => e.isRoot && e.collectionPath === relativeCollectionPath)) {
+      relativeCollectionPath = `${originalCollectionPath}-${counter}`
+      relativeResourcePath = `${relativeCollectionPath}/{id}`
+      counter++
+    }
+
     const newEntity: ExposedEntitySchema = {
       kind: ExposedEntityKind,
       key: nanoid(),
@@ -444,12 +470,7 @@ export class ApiModel extends DependentModel {
       return
     }
     const maxDepth = options.maxDepth ?? 6
-    const visited = new Set<string>()
-    // Add parent entity's key to the visited set so we won't skip it when traversing
-    // associations.
-    visited.add(createDomainKey(parentExposure.entity))
-
-    const follow = (currentEntity: AssociationTarget, parentKey: string, depth: number) => {
+    const follow = (currentEntity: AssociationTarget, parentKey: string, depth: number, currentPath: string[]) => {
       // Find the domain entity
       const domainEntity = domain.findEntity(currentEntity.key, currentEntity.domain)
       if (!domainEntity) return
@@ -462,24 +483,45 @@ export class ApiModel extends DependentModel {
             continue
           }
 
-          // Create unique identifier for circular detection
-          const visitKey = createDomainKey(target)
-          if (visited.has(visitKey)) {
-            continue // Skip circular references
+          const targetKeys = createDomainKey(target)
+          // Circular dependency check: if this entity is already in our *current* traversal path
+          if (currentPath.includes(targetKeys)) {
+            continue
           }
-          visited.add(visitKey)
-
-          // Check if this nested exposure already exists
-          const existingNested = this.exposes.find(
-            (e) =>
-              !e.isRoot &&
-              e.entity.key === target.key &&
-              e.entity.domain === target.domain &&
-              e.parent?.key === parentKey
-          )
-
-          if (existingNested) {
-            continue // Already exposed under this parent
+
+          // Check if this entity is ALREADY exposed anywhere in the model
+          const existingExposure = this.getExposedEntity(target)
+
+          if (existingExposure) {
+            // If it's already exposed and NOT root (i.e., it's currently a nested child of someone else),
+            // promote it to ROOT to avoid duplicating it or deeply nesting it in multiple places.
+            if (!existingExposure.isRoot) {
+              // 1. Calculate new root paths (handling collisions)
+              const targetDomEntity = domain.findEntity(target.key, target.domain)
+              if (targetDomEntity) {
+                const name = targetDomEntity.info.name || ''
+                const segment = pluralize(name.toLocaleLowerCase())
+                let relativeCollectionPath = `/${segment}`
+                let relativeResourcePath = `/${segment}/{id}`
+
+                let counter = 1
+                const originalCollectionPath = relativeCollectionPath
+                while (this.exposes.some((e) => e.isRoot && e.collectionPath === relativeCollectionPath)) {
+                  relativeCollectionPath = `${originalCollectionPath}-${counter}`
+                  relativeResourcePath = `${relativeCollectionPath}/{id}`
+                  counter++
+                }
+
+                // 2. Update properties to make it root
+                existingExposure.isRoot = true
+                existingExposure.parent = undefined
+                existingExposure.collectionPath = relativeCollectionPath
+                existingExposure.resourcePath = relativeResourcePath
+                existingExposure.hasCollection = true
+              }
+            }
+            // Whether it was already root or we just promoted it, we stop following here.
+            continue
           }
 
           // Find the target domain entity for path generation
@@ -516,27 +558,30 @@ export class ApiModel extends DependentModel {
             nestedExposure.truncated = true
           } else {
             // Recursively follow associations
-            follow(target, nestedExposure.key, depth + 1)
+            follow(target, nestedExposure.key, depth + 1, [...currentPath, targetKeys])
           }
         }
       }
     }
 
     // Start following from the root exposure
-    follow(parentExposure.entity, parentExposure.key, 0)
+    // Initial path contains the root entity itself
+    const rootKey = createDomainKey(parentExposure.entity)
+    follow(parentExposure.entity, parentExposure.key, 0, [rootKey])
   }
 
   /**
    * Removes an exposed entity from the API model.
-   * @param entity The entity to remove.
+   * This also removes any nested exposed entities that are children of the removed entity.
+   *
+   * @param key The key of the exposed entity to remove.
    */
-  removeEntity(entity: AssociationTarget): void {
-    const current = this.exposes.find((e) => e.entity.key === entity.key && e.entity.domain === entity.domain)
-    if (!current) {
-      return
+  removeExposedEntity(key: string): void {
+    const index = this.exposes.findIndex((e) => e.key === key)
+    if (index < 0) {
+      throw new Error(`Exposed entity with key "${key}" not found.`)
     }
-    this.removeWithChildren(current.key)
-    this.notifyChange()
+    this.removeWithChildren(key)
   }
 
   private removeWithChildren(key: string): void {
@@ -573,11 +618,11 @@ export class ApiModel extends DependentModel {
   }
 
   /**
-   * Clears the API model for a new entity change.
+   * Clears the API model for a new data domain change.
    * This method resets the dependencies, exposes, user,
    * authentication, authorization, and session properties.
    */
-  cleanForEntityChange(): void {
+  cleanForDomainChange(): void {
     this.dependencies.clear()
     this.dependencyList = []
     this.exposes = []
@@ -606,7 +651,7 @@ export class ApiModel extends DependentModel {
     if (!domain.info.version) {
       throw new Error(`Cannot attach DataDomain without a version. Please set the version in the domain info.`)
     }
-    this.cleanForEntityChange()
+    this.cleanForDomainChange()
     this.dependencies.set(domain.key, domain)
     this.dependencyList = [{ key: domain.key, version: domain.info.version }]
     this.notifyChange()

package/src/modeling/ExposedEntity.ts

@@ -16,6 +16,15 @@ import type {
 /**
  * A class that specializes in representing an exposed Data Entity within an API Model.
  *
+ * ## Design Note
+ * This class enforces strict path constraints (e.g., single-segment collection paths like `/users`,
+ * two-segment resource paths like `/users/{id}`).
+ * This is an intentional design choice to support a UI paradigm for non-technical users, ensuring that
+ * path segments are configured individually at each level of the exposure hierarchy.
+ *
+ * Flexibility is achieved by chaining exposed entities (parent/child relationships), where the final
+ * absolute path is composed of all ancestral paths. See `getAbsoluteResourcePath()` and `getAbsoluteCollectionPath()`.
+ *
  * @fires change - Emitted when the exposed entity has changed.
  */
 export class ExposedEntity extends EventTarget {
@@ -250,6 +259,17 @@ export class ExposedEntity extends EventTarget {
       throw new Error(`Collection path must contain exactly one segment. Received: "${path}"`)
     }
     const normalizedCollection = `/${segments[0]}`
+
+    // Check for collision if this is a root entity
+    if (this.isRoot) {
+      const collision = this.api.exposes.find(
+        (e) => e.isRoot && e.key !== this.key && e.collectionPath === normalizedCollection
+      )
+      if (collision) {
+        throw new Error(`Collection path "${normalizedCollection}" is already in use by another root entity.`)
+      }
+    }
+
     // Preserve current parameter name if present, otherwise default to {id}
     let param = '{id}'
     if (this.resourcePath) {
@@ -309,6 +329,14 @@ export class ExposedEntity extends EventTarget {
         `Resource path must contain exactly two segments when no collection is present. Received: "${cleaned}"`
       )
     }
+    // Check for collision if this is a root entity (singleton case)
+    if (this.isRoot) {
+      const collision = this.api.exposes.find((e) => e.isRoot && e.key !== this.key && e.resourcePath === cleaned)
+      if (collision) {
+        throw new Error(`Resource path "${cleaned}" is already in use by another root entity.`)
+      }
+    }
+
     if (this.resourcePath !== cleaned) {
       this.resourcePath = `/${segments[0]}/${segments[1]}`
     }