@api-client/core 0.18.31 → 0.18.33

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

@@ -42068,10 +42068,10 @@
 "@id": "#194"
 },
 {
-"@id": "#200"
+"@id": "#197"
 },
 {
-"@id": "#197"
+"@id": "#200"
 },
 {
 "@id": "#203"
@@ -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": "code: '5'\ndescription: 'Limited company'\n",
+"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44766,12 +44766,12 @@
 {
 "@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)-(3,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.31",
+  "version": "0.18.33",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {

package/src/modeling/ApiModel.ts

@@ -1,12 +1,12 @@
 import { nanoid } from '../nanoid.js'
-import { ApiModelKind, DataDomainKind } from '../models/kinds.js'
+import { ApiModelKind, DataDomainKind, ExposedEntityKind } from '../models/kinds.js'
 import { type IThing, Thing } from '../models/Thing.js'
 import type {
   AccessRule,
   AssociationTarget,
   AuthenticationConfiguration,
   AuthorizationConfiguration,
-  ExposedEntity,
+  ExposedEntitySchema,
   RateLimitingConfiguration,
   RolesBasedAccessControl,
   SessionConfiguration,
@@ -18,6 +18,7 @@ import { DependentModel, type DependentModelSchema, type DomainDependency } from
 import { observed, toRaw } from '../decorators/observed.js'
 import pluralize from '@jarrodek/pluralize'
 import { createDomainKey } from './helpers/keying.js'
+import { ExposedEntity } from './ExposedEntity.js'
 
 /**
  * Contact information for the exposed API.
@@ -95,7 +96,7 @@ export interface ApiModelSchema extends DependentModelSchema {
    * 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[]
+  exposes: ExposedEntitySchema[]
 
   /**
    * Optional array of access rules that define the access control policies
@@ -169,7 +170,7 @@ export class ApiModel extends DependentModel {
    * 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[]
+  @observed({ deep: true }) accessor 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
@@ -294,7 +295,7 @@ export class ApiModel extends DependentModel {
       this.session = structuredClone(init.session)
     }
     if (Array.isArray(init.exposes)) {
-      this.exposes = structuredClone(init.exposes)
+      this.exposes = init.exposes.map((e) => new ExposedEntity(this, e))
     } else {
       this.exposes = []
     }
@@ -324,7 +325,7 @@ export class ApiModel extends DependentModel {
       kind: this.kind,
       key: this.key,
       info: this.info.toJSON(),
-      exposes: structuredClone(this.exposes),
+      exposes: this.exposes.map((e) => e.toJSON()),
     }
     if (this.user) {
       result.user = { ...this.user }
@@ -404,22 +405,21 @@ export class ApiModel extends DependentModel {
     const segment = pluralize(name.toLocaleLowerCase())
     const relativeCollectionPath = `/${segment}`
     const relativeResourcePath = `/${segment}/{id}`
-    const absoluteCollectionPath = relativeCollectionPath
-    const absoluteResourcePath = relativeResourcePath
-    const newEntity: ExposedEntity = {
+    const newEntity: ExposedEntitySchema = {
+      kind: ExposedEntityKind,
       key: nanoid(),
       entity: { ...entity },
       actions: [],
       isRoot: true,
-      relativeCollectionPath,
-      relativeResourcePath,
-      absoluteCollectionPath,
-      absoluteResourcePath,
+      collectionPath: relativeCollectionPath,
+      resourcePath: relativeResourcePath,
+      hasCollection: true,
     }
     if (options) {
       newEntity.exposeOptions = { ...options }
     }
-    this.exposes.push(newEntity)
+    const created = new ExposedEntity(this, newEntity)
+    this.exposes.push(created)
 
     // Follow associations if requested
     if (options?.followAssociations) {
@@ -428,7 +428,7 @@ export class ApiModel extends DependentModel {
       }
     }
     this.notifyChange()
-    return newEntity
+    return created
   }
 
   /**
@@ -438,7 +438,7 @@ export class ApiModel extends DependentModel {
    * @param parentExposure The root exposure to follow associations from
    * @param options The expose options containing follow configuration
    */
-  private followEntityAssociations(parentExposure: ExposedEntity, options: ExposeOptions): void {
+  private followEntityAssociations(parentExposure: ExposedEntitySchema, options: ExposeOptions): void {
     const domain = this.domain
     if (!domain) {
       return
@@ -487,24 +487,20 @@ export class ApiModel extends DependentModel {
           if (!targetDomainEntity) continue
 
           const name = association.info.name || ''
-          const parentExposure = this.exposes.find((e) => e.key === parentKey)
-          const parentAbsResource = parentExposure?.absoluteResourcePath || ''
           const segment = pluralize(name.toLocaleLowerCase())
           const isCollection = association.multiple !== false
           const relativeCollectionPath = isCollection ? `/${segment}` : undefined
           const relativeResourcePath = isCollection ? `/${segment}/{id}` : `/${segment}`
-          const absoluteCollectionPath = isCollection ? `${parentAbsResource}${relativeCollectionPath}` : undefined
-          const absoluteResourcePath = `${parentAbsResource}${relativeResourcePath}`
           // Create nested exposure
-          const nestedExposure: ExposedEntity = {
+          const nestedExposure: ExposedEntitySchema = {
+            kind: ExposedEntityKind,
             key: nanoid(),
             entity: { ...target },
             actions: [],
             isRoot: false,
-            relativeCollectionPath,
-            relativeResourcePath,
-            absoluteCollectionPath,
-            absoluteResourcePath,
+            collectionPath: relativeCollectionPath,
+            resourcePath: relativeResourcePath,
+            hasCollection: isCollection,
             parent: {
               key: parentKey,
               association: {
@@ -515,7 +511,7 @@ export class ApiModel extends DependentModel {
             },
           }
 
-          this.exposes.push(nestedExposure)
+          this.exposes.push(new ExposedEntity(this, nestedExposure))
           if (depth + 1 >= maxDepth) {
             nestedExposure.truncated = true
           } else {

package/src/modeling/ExposedEntity.ts

@@ -0,0 +1,358 @@
+import { observed } from '../decorators/observed.js'
+import { ExposedEntityKind } from '../models/kinds.js'
+import { nanoid } from '../nanoid.js'
+import type { ApiModel } from './ApiModel.js'
+import { ensureLeadingSlash, joinPaths } from './helpers/endpointHelpers.js'
+import type {
+  AccessRule,
+  ApiAction,
+  AssociationTarget,
+  ExposeOptions,
+  ExposeParentRef,
+  RateLimitingConfiguration,
+  ExposedEntitySchema,
+} from './types.js'
+
+/**
+ * A class that specializes in representing an exposed Data Entity within an API Model.
+ *
+ * @fires change - Emitted when the exposed entity has changed.
+ */
+export class ExposedEntity extends EventTarget {
+  /**
+   * The exposed entity kind recognizable by the ecosystem.
+   */
+  kind: typeof ExposedEntityKind
+
+  /**
+   * The unique key of the exposed entity.
+   * This is a stable identifier that does not change across versions.
+   */
+  key: string
+
+  /**
+   * A pointer to a Data Entity from the Data Domain.
+   */
+  @observed() accessor entity: AssociationTarget
+
+  /**
+   * Indicates whether this exposure has a collection endpoint.
+   * A collection endpoint is optional for nested exposures where the association is 1:1
+   * and the schema is embedded directly under the parent resource.
+   *
+   * Note that this property is not observed for changes as it is immutable after creation.
+   */
+  hasCollection: boolean
+
+  /**
+   * Path to the collection endpoint for this exposure.
+   * Starts with '/'. Not set for 1:1 nested exposures where collection does not exist.
+   */
+  @observed() accessor collectionPath: string | undefined
+
+  /**
+   * Path to the resource endpoint for this exposure.
+   * Starts with '/'. For 1:1 nested exposures the resource path typically does not include an id segment.
+   */
+  @observed() accessor resourcePath: string
+
+  /**
+   * Whether this exposure is a root exposure (top-level collection).
+   * If this is set then the `parent` reference must be populated.
+   *
+   * Note that this property is not observed for changes as it is immutable after creation.
+   */
+  isRoot?: boolean
+
+  /**
+   * Parent reference when this exposure was created via following an association.
+   *
+   * Note that this property is not observed for changes as it is immutable after creation.
+   */
+  parent?: ExposeParentRef
+
+  /**
+   * Expose-time config used to create this exposure (persisted for auditing/UI).
+   * This is only populated for the root exposure. All children exposures inherit this config.
+   *
+   * Note that this property is not observed for changes as it is immutable after creation.
+   */
+  exposeOptions?: ExposeOptions
+
+  /**
+   * The list of enabled API actions for this exposure (List/Read/Create/etc.)
+   */
+  @observed({ deep: true }) accessor actions: ApiAction[]
+
+  /**
+   * Optional array of access rules that define the access control policies for this exposure.
+   */
+  @observed({ deep: true }) accessor accessRule: AccessRule[] | undefined
+
+  /**
+   * Optional configuration for rate limiting for this exposure.
+   */
+  @observed({ deep: true }) accessor rateLimiting: RateLimitingConfiguration | undefined
+
+  /**
+   * When true, generation for this exposure hit configured limits
+   *
+   * Note that this property is not observed for changes as it is immutable after creation.
+   */
+  truncated?: boolean
+
+  /**
+   * 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
+  /**
+   * When the initializing flag is set to true,
+   * the domain is not notified of changes.
+   */
+  #initializing = true
+  /**
+   * A reference to the parent API Model instance.
+   */
+  api: ApiModel
+
+  static createSchema(input: Partial<ExposedEntitySchema> = {}): ExposedEntitySchema {
+    const {
+      key = nanoid(),
+      entity = { key: '' },
+      collectionPath,
+      resourcePath = '/',
+      hasCollection = true,
+      isRoot,
+      parent,
+      exposeOptions,
+      actions = [],
+      accessRule,
+      rateLimiting,
+      truncated,
+    } = input
+    const result: ExposedEntitySchema = {
+      kind: ExposedEntityKind,
+      key,
+      entity: { ...entity },
+      hasCollection,
+      resourcePath,
+      actions: actions.map((a) => ({ ...a })),
+    }
+    if (collectionPath !== undefined) {
+      result.collectionPath = collectionPath
+    }
+    if (isRoot !== undefined) {
+      result.isRoot = isRoot
+    }
+    if (parent !== undefined) {
+      result.parent = { ...parent }
+    }
+    if (exposeOptions !== undefined) {
+      result.exposeOptions = { ...exposeOptions }
+    }
+    if (accessRule !== undefined) {
+      result.accessRule = accessRule.map((ar) => ({ ...ar }))
+    }
+    if (rateLimiting !== undefined) {
+      result.rateLimiting = { ...rateLimiting }
+    }
+    if (truncated !== undefined) {
+      result.truncated = truncated
+    }
+    return result
+  }
+
+  constructor(model: ApiModel, state?: Partial<ExposedEntitySchema>) {
+    super()
+    this.api = model
+    const init = ExposedEntity.createSchema(state)
+    this.kind = init.kind
+    this.key = init.key
+    this.entity = init.entity
+    this.hasCollection = init.hasCollection
+    this.collectionPath = init.collectionPath
+    this.resourcePath = init.resourcePath
+    this.isRoot = init.isRoot
+    this.parent = init.parent
+    this.exposeOptions = init.exposeOptions
+    this.actions = init.actions
+    this.accessRule = init.accessRule
+    this.rateLimiting = init.rateLimiting
+    this.truncated = init.truncated
+    this.#initializing = false
+  }
+
+  notifyChange() {
+    if (this.#notifying || this.#initializing) {
+      return
+    }
+    this.#notifying = true
+    queueMicrotask(() => {
+      this.#notifying = false
+      const event = new Event('change')
+      this.dispatchEvent(event)
+    })
+  }
+
+  toJSON(): ExposedEntitySchema {
+    const result: ExposedEntitySchema = {
+      kind: this.kind,
+      key: this.key,
+      entity: { ...this.entity },
+      resourcePath: this.resourcePath,
+      actions: this.actions.map((a) => ({ ...a })),
+      hasCollection: this.hasCollection,
+    }
+    if (this.collectionPath !== undefined) {
+      result.collectionPath = this.collectionPath
+    }
+    if (this.isRoot !== undefined) {
+      result.isRoot = this.isRoot
+    }
+    if (this.parent !== undefined) {
+      result.parent = { ...this.parent }
+    }
+    if (this.exposeOptions !== undefined) {
+      result.exposeOptions = { ...this.exposeOptions }
+    }
+    if (this.accessRule !== undefined) {
+      result.accessRule = this.accessRule.map((ar) => ({ ...ar }))
+    }
+    if (this.rateLimiting !== undefined) {
+      result.rateLimiting = { ...this.rateLimiting }
+    }
+    if (this.truncated !== undefined) {
+      result.truncated = this.truncated
+    }
+    return result
+  }
+
+  /**
+   * Sets a new collection path for this exposed entity.
+   *
+   * It:
+   * - updates the collectionPath property
+   * - updates the absoluteCollectionPath property accordingly
+   * - updates the resourcePath accordingly.
+   * @param path The new path to set.
+   */
+  setCollectionPath(path: string) {
+    if (!this.hasCollection) {
+      throw new Error(`Cannot set collection path on an exposure that does not have a collection`)
+    }
+    const cleaned = ensureLeadingSlash(path)
+    // Ensure exactly one non-empty segment
+    const segments = cleaned.split('/').filter(Boolean)
+    if (segments.length !== 1) {
+      throw new Error(`Collection path must contain exactly one segment. Received: "${path}"`)
+    }
+    const normalizedCollection = `/${segments[0]}`
+    // Preserve current parameter name if present, otherwise default to {id}
+    let param = '{id}'
+    if (this.resourcePath) {
+      const curSegments = this.resourcePath.split('/').filter(Boolean)
+      const maybeParam = curSegments[1]
+      if (maybeParam && /^\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(maybeParam)) {
+        param = maybeParam
+      }
+    }
+    const nextResource = `${normalizedCollection}/${param}`
+    this.collectionPath = normalizedCollection
+    this.resourcePath = nextResource
+    // rely on ApiModel.exposes deep observation to notify on property sets
+  }
+
+  /**
+   * Sets a new resource path for this exposed entity.
+   *
+   * Rules:
+   * - Must start with '/'.
+   * - If this exposure has a collection, the path must be exactly the collection path plus a single
+   *   parameter segment (e.g. `/products/{productId}`) and only the parameter name may vary.
+   * - If this exposure does NOT have a collection, the path can be any two segments (e.g. `/profile/{id}` or `/a/b`).
+   */
+  setResourcePath(path: string) {
+    const cleaned = ensureLeadingSlash(path)
+    const segments = cleaned.split('/').filter(Boolean)
+
+    if (this.hasCollection) {
+      if (!this.collectionPath) {
+        throw new Error('Cannot set resource path: missing collection path for this exposure')
+      }
+      const colSegments = this.collectionPath.split('/').filter(Boolean)
+      if (colSegments.length !== 1) {
+        throw new Error(`Invalid stored collection path "${this.collectionPath}"`)
+      }
+      if (segments.length !== 2) {
+        throw new Error(`Resource path must be exactly two segments (collection + parameter). Received: "${cleaned}"`)
+      }
+      const [s1, s2] = segments
+      if (s1 !== colSegments[0]) {
+        throw new Error(`Resource path must start with the collection segment "${colSegments[0]}". Received: "${s1}"`)
+      }
+      // s2 must be a parameter segment {name}
+      if (!/^\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(s2)) {
+        throw new Error(`The second segment must be a parameter in braces, e.g. {id}. Received: "${s2}"`)
+      }
+      if (this.resourcePath !== cleaned) {
+        this.resourcePath = `/${s1}/${s2}`
+      }
+      return
+    }
+
+    // No collection: allow any two segments
+    if (segments.length !== 2) {
+      throw new Error(
+        `Resource path must contain exactly two segments when no collection is present. Received: "${cleaned}"`
+      )
+    }
+    if (this.resourcePath !== cleaned) {
+      this.resourcePath = `/${segments[0]}/${segments[1]}`
+    }
+  }
+
+  /**
+   * Computes the absolute path for this exposure's resource endpoint by
+   * walking up the exposure tree using `parent.key` until reaching a root exposure.
+   * The absolute path is composed by concatenating each ancestor's resource path
+   * with this exposure's resource path.
+   */
+  getAbsoluteResourcePath(): string {
+    let absolute = ensureLeadingSlash(this.resourcePath)
+    // Traverse parents, always joining with the parent's resource path
+    let parentKey = this.parent?.key
+    while (parentKey) {
+      const parent = this.api.exposes.find((e) => e.key === parentKey)
+      if (!parent) break
+      const parentResource = ensureLeadingSlash(parent.resourcePath)
+      absolute = joinPaths(parentResource, absolute)
+      parentKey = parent.parent?.key
+    }
+    return absolute
+  }
+
+  /**
+   * Computes the absolute path for this exposure's collection endpoint (if any)
+   * by walking up the exposure tree using `parent.key` until reaching a root exposure.
+   * The absolute path is composed by concatenating each ancestor's resource path
+   * with this exposure's collection path.
+   * Returns undefined if this exposure has no collection.
+   */
+  getAbsoluteCollectionPath(): string | undefined {
+    if (!this.hasCollection || !this.collectionPath) return undefined
+    let absolute = ensureLeadingSlash(this.collectionPath)
+    // Traverse parents, always joining with the parent's resource path
+    let parentKey = this.parent?.key
+    while (parentKey) {
+      const parent = this.api.exposes.find((e) => e.key === parentKey)
+      if (!parent) break
+      const parentResource = ensureLeadingSlash(parent.resourcePath)
+      absolute = joinPaths(parentResource, absolute)
+      parentKey = parent.parent?.key
+    }
+    return absolute
+  }
+}

package/src/modeling/helpers/endpointHelpers.ts

@@ -3,3 +3,25 @@ export function paramNameFor(entityKeyLocal: string): string {
   const key = parts[parts.length - 1]
   return `${key}Id`
 }
+
+/**
+ * Ensures the path starts with a single leading slash and has no trailing slash (except root '/')
+ * @param path The path fragment to normalize
+ */
+export function ensureLeadingSlash(path: string): string {
+  const trimmed = path.trim()
+  const withSlash = trimmed.startsWith('/') ? trimmed : `/${trimmed}`
+  if (withSlash === '/') return '/'
+  return withSlash.replace(/\/+$/, '')
+}
+
+/**
+ * Joins two absolute-like fragments ensuring single slashes between segments
+ * @param left The left path fragment
+ * @param right The right path fragment
+ */
+export function joinPaths(left: string, right: string): string {
+  const l = left.endsWith('/') ? left.slice(0, -1) : left
+  const r = right.startsWith('/') ? right : `/${right}`
+  return `${l}${r}`
+}

package/src/modeling/types.ts

@@ -12,6 +12,7 @@ import type {
   DomainPropertyKind,
   DomainAssociationKind,
   DataDomainKind,
+  ExposedEntityKind,
 } from '../models/kinds.js'
 import type { DataDomain } from './DataDomain.js'
 
@@ -426,7 +427,8 @@ export interface UsernamePasswordConfiguration extends AuthenticationConfigurati
 /**
  * Represents a Data Entity from the Data Domain that the API will expose and operate upon.
  */
-export interface ExposedEntity {
+export interface ExposedEntitySchema {
+  kind: typeof ExposedEntityKind
   /**
    * The unique identifier for this exposure instance.
    * In the exposure model, we need to uniquely identify each exposure instance, because
@@ -449,28 +451,22 @@ export interface ExposedEntity {
    */
   entity: AssociationTarget
   /**
-   * Relative path to the collection endpoint for this exposure.
-   * Starts with '/'. Not set for 1:1 nested exposures where collection does not exist.
+   * Indicates whether this exposure has a collection endpoint.
+   * A collection endpoint is optional for nested exposures where the association is 1:1
+   * and the schema is embedded directly under the parent resource.
    */
-  relativeCollectionPath?: string
-
+  hasCollection: boolean
   /**
-   * Relative path to the resource endpoint for this exposure.
-   * Starts with '/'. For 1:1 nested exposures the resource path typically does not include an id segment.
-   */
-  relativeResourcePath: string
-
-  /**
-   * Absolute path to the collection endpoint for this exposure (includes parent paths).
+   * A path to the collection endpoint for this exposure.
    * Starts with '/'. Not set for 1:1 nested exposures where collection does not exist.
    */
-  absoluteCollectionPath?: string
+  collectionPath?: string
 
   /**
-   * Absolute path to the resource endpoint for this exposure (includes parent paths).
-   * Starts with '/'.
+   * A path to the resource endpoint for this exposure.
+   * Starts with '/'. For 1:1 nested exposures the resource path typically does not include an id segment.
    */
-  absoluteResourcePath: string
+  resourcePath: string
 
   /**
    * Whether this exposure is a root exposure (top-level collection).

package/src/models/kinds.ts

@@ -21,5 +21,6 @@ export const DataCatalogVersionKind = 'Core#DataCatalogVersion'
 export const OrganizationKind = 'Core#Organization'
 export const InvitationKind = 'Core#Invitation'
 export const ApiModelKind = 'Core#ApiModel'
+export const ExposedEntityKind = 'Core#ExposedEntity'
 export const ApiFileKind = 'Core#ApiFile'
 export const GroupKind = 'Core#Group'