@api-client/core 0.20.5 → 0.20.7

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.20.5",
+  "version": "0.20.7",
   "license": "UNLICENSED",
   "exports": {
     "./browser.js": {
@@ -105,8 +105,8 @@
     "xpath": "^0.0.34"
   },
   "devDependencies": {
-    "@commitlint/cli": "^20.1.0",
-    "@commitlint/config-conventional": "^20.0.0",
+    "@commitlint/cli": "^21.0.0",
+    "@commitlint/config-conventional": "^21.0.0",
     "@eslint/js": "^10.0.1",
     "@japa/assert": "^4.0.1",
     "@japa/runner": "^5.3.0",

package/src/modeling/ApiModel.ts

@@ -289,9 +289,15 @@ export class ApiModel extends DependentModel {
     const init = ApiModel.createSchema(state)
     const instances: DataDomain[] = []
     if (domain instanceof DataDomain) {
-      instances.push(domain)
+      if (domain.readOnly) {
+        instances.push(domain)
+      } else {
+        // eslint-disable-next-line no-console
+        console.warn(`Domain ${domain.key} is not read only, cloning it. This may have performance implications.`)
+        instances.push(domain.clone({ readOnly: true }))
+      }
     } else if (typeof domain === 'object' && domain.kind === DataDomainKind) {
-      instances.push(new DataDomain(domain))
+      instances.push(new DataDomain(domain, undefined, { readOnly: true }))
     } else if (domain) {
       throw new Exception(`Invalid domain provided. Expected a DataDomain instance or schema.`, {
         code: 'E_DOMAIN_INVALID',

package/src/modeling/DataDomain.ts

@@ -10,13 +10,13 @@ import {
 } from '../models/kinds.js'
 import type {
   DeserializationIssue,
-  DeserializationMode,
   DomainGraphEdge,
   DomainGraphNodeType,
   SerializedGraph,
   DomainSearchCriteria,
   DomainSearchResult,
   SearchableNodeType,
+  DataDomainOptions,
 } from './types.js'
 import { type DomainNamespaceSchema, DomainNamespace, type NamespaceOrderedItem } from './DomainNamespace.js'
 import { type DomainModelSchema, DomainModel } from './DomainModel.js'
@@ -142,6 +142,11 @@ export class DataDomain extends DependentModel {
    */
   #notifying = false
 
+  /**
+   * Whether the DataDomain is in read-only mode, making it immutable and enabling caching operations.
+   */
+  readonly readOnly: boolean
+
   /**
    * This is to keep it consistent with the domain elements.
    */
@@ -193,15 +198,22 @@ export class DataDomain extends DependentModel {
    *
    * @param state The previously serialized state of the graph.
    * @param dependencies An array of foreign data domains to register with this domain.
+   * @param options Initialization options for the data domain.
    */
-  constructor(state?: Partial<DataDomainSchema>, dependencies: DomainDependency[] = [], mode?: DeserializationMode) {
+  constructor(state?: Partial<DataDomainSchema>, dependencies: DomainDependency[] = [], options?: DataDomainOptions) {
     const init = DataDomain.createSchema(state)
     const instances: DataDomain[] = []
     for (const dep of dependencies) {
       if (dep instanceof DataDomain) {
-        instances.push(dep)
+        if (dep.readOnly) {
+          instances.push(dep)
+        } else {
+          // eslint-disable-next-line no-console
+          console.warn(`Domain ${dep.key} is not read only, cloning it. This may have performance implications.`)
+          instances.push(dep.clone({ readOnly: true }))
+        }
       } else if (typeof dep === 'object' && dep.kind === DataDomainKind && dep.key) {
-        const domain = new DataDomain(dep)
+        const domain = new DataDomain(dep, undefined, { readOnly: true })
         instances.push(domain)
       } else {
         throw new Error(`Invalid foreign domain dependency: ${dep}`)
@@ -211,10 +223,13 @@ export class DataDomain extends DependentModel {
     this.kind = init.kind
     this.key = init.key
     this.info = new Thing(init.info)
+    this.readOnly = options?.readOnly || false
+
+    const mode = options?.mode || 'strict'
     const result = deserialize(this, {
       json: init.graph,
       dependencies: instances,
-      mode: mode || 'strict',
+      mode,
     })
     this.graph = result.graph
     if (result.issues.length > 0 && mode === 'lenient') {
@@ -242,12 +257,17 @@ export class DataDomain extends DependentModel {
    * It serializes the current domain and its graph, then deserializes it into a new instance.
    * It also deeply clones all foreign domain dependencies recursively.
    *
+   * @param options Optional initialization options to override the cloned ones.
    * @returns A new DataDomain instance that is a deep copy of this one.
    */
-  clone(): DataDomain {
+  clone(options?: DataDomainOptions): DataDomain {
     const state = this.toJSON()
     const dependencies = Array.from(this.dependencies.values()).map((dep) => dep.clone())
-    return new DataDomain(state, dependencies)
+    const opts: DataDomainOptions = {
+      readOnly: this.readOnly,
+      ...options,
+    }
+    return new DataDomain(state, dependencies, opts)
   }
 
   /**

package/src/modeling/DependentModel.ts

@@ -1,6 +1,10 @@
 import type { DataDomain, DataDomainSchema } from './DataDomain.js'
 import type { ForeignDomainDependency } from './types.js'
 
+/**
+ * If a dependency is a domain instance it should always be in read-only mode.
+ * Otherwise a read-only clone will be created for performance reason.
+ */
 export type DomainDependency = DataDomain | DataDomainSchema
 
 export interface DependentModelSchema {

package/src/modeling/DomainEntity.ts

@@ -127,6 +127,26 @@ export class DomainEntity extends DomainElement {
    */
   override kind: typeof DomainEntityKind
 
+  /**
+   * Cached inherited properties.
+   */
+  #inheritedPropertiesCache?: DomainProperty[]
+
+  /**
+   * Cached parent entities arrays.
+   */
+  #allParentsCache?: Record<'up' | 'down', DomainEntity[]>
+
+  /**
+   * Cached inherited associations.
+   */
+  #inheritedAssociationsCache?: DomainAssociation[]
+
+  /**
+   * Cached semantics across the inheritance chain.
+   */
+  #allSemanticsCache?: AppliedDataSemantic[]
+
   /**
    * The description of the domain entity.
    */
@@ -363,6 +383,9 @@ export class DomainEntity extends DomainElement {
    * @returns The iterator over the list of all properties.
    */
   withInheritedProperties(): MapIterator<DomainProperty> {
+    if (this.root.readOnly && this.#inheritedPropertiesCache) {
+      return this.#inheritedPropertiesCache.values()
+    }
     const cache = new Map<string, DomainProperty>()
     const parents = this.listAllParents('up')
     for (const parent of parents) {
@@ -381,6 +404,9 @@ export class DomainEntity extends DomainElement {
       }
       cache.set(prop.info.name, prop)
     }
+    if (this.root.readOnly) {
+      this.#inheritedPropertiesCache = Array.from(cache.values())
+    }
     return cache.values()
   }
 
@@ -438,6 +464,9 @@ export class DomainEntity extends DomainElement {
    * @returns An array of parent `DomainEntity` instances, ordered according to the requested traversal direction.
    */
   listAllParents(direction: 'up' | 'down' = 'up'): DomainEntity[] {
+    if (this.root.readOnly && this.#allParentsCache?.[direction]) {
+      return this.#allParentsCache[direction]
+    }
     const visited = new Set<string>()
     const parents: DomainEntity[] = []
     const queue: DomainEntity[] = [...this.listParents()]
@@ -456,6 +485,13 @@ export class DomainEntity extends DomainElement {
       parents.reverse()
     }
 
+    if (this.root.readOnly) {
+      if (!this.#allParentsCache) {
+        this.#allParentsCache = {} as Record<'up' | 'down', DomainEntity[]>
+      }
+      this.#allParentsCache[direction] = parents
+    }
+
     return parents
   }
 
@@ -982,6 +1018,70 @@ export class DomainEntity extends DomainElement {
     return this.semantics.some((s) => s.id === semanticId)
   }
 
+  /**
+   * Collects a list of all associations that affect this entity,
+   * including all inherited from parents associations as well as
+   * this entity's associations.
+   *
+   * The resulting list already accounts for an association override.
+   * An association overrides another association if it is lower in the
+   * inheritance chain. As such, an association defined on this entity
+   * always overrides previously defined entities.
+   * @returns The iterator over the list of all associations.
+   */
+  withInheritedAssociations(): MapIterator<DomainAssociation> {
+    if (this.root.readOnly && this.#inheritedAssociationsCache) {
+      return this.#inheritedAssociationsCache.values()
+    }
+    const cache = new Map<string, DomainAssociation>()
+    const parents = this.listAllParents('up')
+    for (const parent of parents) {
+      for (const assoc of parent.associations) {
+        if (!assoc.info.name) {
+          continue
+        }
+        cache.set(assoc.info.name, assoc)
+      }
+    }
+    for (const assoc of this.associations) {
+      if (!assoc.info.name) {
+        continue
+      }
+      cache.set(assoc.info.name, assoc)
+    }
+    if (this.root.readOnly) {
+      this.#inheritedAssociationsCache = Array.from(cache.values())
+    }
+    return cache.values()
+  }
+
+  /**
+   * Lists all semantics applied to this entity and its inherited parents.
+   * Semantics from this entity overwrite those inherited from parents.
+   *
+   * @returns An array of applied semantics.
+   */
+  listAllSemantics(): AppliedDataSemantic[] {
+    if (this.root.readOnly && this.#allSemanticsCache) {
+      return this.#allSemanticsCache
+    }
+    const semanticsMap = new Map<SemanticType, AppliedDataSemantic>()
+    const parents = this.listAllParents('up')
+    for (const parent of parents) {
+      for (const semantic of parent.semantics) {
+        semanticsMap.set(semantic.id, semantic)
+      }
+    }
+    for (const semantic of this.semantics) {
+      semanticsMap.set(semantic.id, semantic)
+    }
+    const result = Array.from(semanticsMap.values())
+    if (this.root.readOnly) {
+      this.#allSemanticsCache = result
+    }
+    return result
+  }
+
   /**
    * Generates a unique name by appending a number to the base name.
    * @param baseName The base name to make unique.

package/src/modeling/ExposedEntity.ts

@@ -5,7 +5,7 @@ import { nanoid } from '../nanoid.js'
 import { Action } from './actions/Action.js'
 import { ActionKind, type ApiActionSchema, createActionFromKind, restoreAction } from './actions/index.js'
 import type { ApiModel } from './ApiModel.js'
-import { ensureLeadingSlash, joinPaths } from './helpers/endpointHelpers.js'
+import { ensureLeadingSlash, joinPaths, paramNameFor } from './helpers/endpointHelpers.js'
 import { AccessRule } from './rules/AccessRule.js'
 import { type RateLimitRule, restoreAccessRule } from './rules/index.js'
 import { RateLimitingConfiguration } from './rules/RateLimitingConfiguration.js'
@@ -302,16 +302,33 @@ export class ExposedEntity extends EventTarget {
       }
     }
 
-    // Preserve current parameter name if present, otherwise default to {id}
-    let param = '{id}'
-    if (this.resourcePath) {
+    // Preserve current parameter name if present, otherwise default to semantic param name
+    let param = ''
+    if (this.resourcePath && 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
       }
     }
+
+    if (!param) {
+      const entityObj = this.api.domain?.findEntity(this.entity.key, this.entity.domain)
+      if (!entityObj || !entityObj.info.name) {
+        // Never fall back to a default like '{id}' here. Silent param generation failures must throw
+        // to prevent runtime/OAS collisions.
+        throw new Exception(
+          'Cannot generate a semantic parameter name because the associated entity or its name is missing.',
+          {
+            code: 'E_ENTITY_NOT_FOUND',
+            help: 'Ensure the exposed entity points to a valid domain entity with a defined name.',
+          }
+        )
+      }
+      param = `{${paramNameFor(entityObj.info.name)}}`
+    }
     const nextResource = `${normalizedCollection}/${param}`
+    this.#validateParameterCollisions(nextResource)
     this.collectionPath = normalizedCollection
     this.resourcePath = nextResource
     // rely on ApiModel.exposes deep observation to notify on property sets
@@ -372,6 +389,7 @@ export class ExposedEntity extends EventTarget {
         })
       }
       if (this.resourcePath !== cleaned) {
+        this.#validateParameterCollisions(`/${s1}/${s2}`)
         this.resourcePath = `/${s1}/${s2}`
       }
       return
@@ -399,10 +417,50 @@ export class ExposedEntity extends EventTarget {
     }
 
     if (this.resourcePath !== cleaned) {
+      this.#validateParameterCollisions(`/${segments[0]}`)
       this.resourcePath = `/${segments[0]}`
     }
   }
 
+  #checkDuplicatesInPaths(paths: string[]) {
+    const absolute = paths.join('/')
+    const params = [...absolute.matchAll(/\{([^}]+)\}/g)].map((m) => m[1])
+    const seen = new Set<string>()
+    for (const p of params) {
+      if (seen.has(p)) {
+        throw new Exception(`Duplicate path parameter "{${p}}" detected in branch hierarchy.`, {
+          code: 'E_PATH_PARAM_COLLISION',
+          help: 'Change the parameter name in either this resource or its ancestor to ensure unique parameter names.',
+        })
+      }
+      seen.add(p)
+    }
+  }
+
+  #validateDescendantCollisions(parentKey: string, ancestorPaths: string[]) {
+    for (const exposure of this.api.exposes.values()) {
+      if (exposure.parent?.key === parentKey) {
+        const currentPaths = [...ancestorPaths, exposure.resourcePath]
+        this.#checkDuplicatesInPaths(currentPaths)
+        this.#validateDescendantCollisions(exposure.key, currentPaths)
+      }
+    }
+  }
+
+  #validateParameterCollisions(tempResourcePath: string) {
+    const paths: string[] = [tempResourcePath]
+    let parentKey = this.parent?.key
+    while (parentKey) {
+      const parent = this.api.exposes.get(parentKey)
+      if (!parent) break
+      paths.unshift(parent.resourcePath)
+      parentKey = parent.parent?.key
+    }
+
+    this.#checkDuplicatesInPaths(paths)
+    this.#validateDescendantCollisions(this.key, paths)
+  }
+
   /**
    * Computes the absolute path for this exposure's resource endpoint by
    * walking up the exposure tree using `parent.key` until reaching a root exposure.

package/src/modeling/RuntimeApiModel.ts

@@ -4,9 +4,10 @@ import type { DataDomainSchema } from './DataDomain.js'
 import type { ActionKind } from './actions/index.js'
 import type { ExposedEntity } from './ExposedEntity.js'
 import type { Action } from './actions/Action.js'
-import { SemanticType } from './Semantics.js'
 import type { DomainEntity } from './DomainEntity.js'
 import type { DomainProperty } from './DomainProperty.js'
+import type { DomainAssociation } from './DomainAssociation.js'
+import { SemanticType } from './Semantics.js'
 import { AccessRule, AccessRuleExecutionPhase } from './rules/AccessRule.js'
 import { Exception } from '../exceptions/exception.js'
 
@@ -108,16 +109,76 @@ export class RuntimeApiModel extends ApiModel {
     return new Map(this.#sessionProperties)
   }
 
+  /**
+   * Cached properties that have at least one semantic, grouped by their entity.
+   */
+  readonly #semanticPropertiesCache = new Map<DomainEntity, DomainProperty[]>()
+
+  /**
+   * Cached properties that have at least one semantic, grouped by their entity and then by SemanticType.
+   */
+  readonly #propertiesBySemanticCache = new Map<DomainEntity, Map<SemanticType, DomainProperty[]>>()
+
+  /**
+   * Cached associations that have at least one semantic, grouped by their entity.
+   */
+  readonly #semanticAssociationsCache = new Map<DomainEntity, DomainAssociation[]>()
+
+  /**
+   * Cached associations that have at least one semantic, grouped by their entity and then by SemanticType.
+   */
+  readonly #associationsBySemanticCache = new Map<DomainEntity, Map<SemanticType, DomainAssociation[]>>()
+
+  /**
+   * Returns a readonly map of properties with semantics.
+   * Note, it creates a copy of the cached map to prevent modification of the internal state.
+   */
+  public get semanticPropertiesCache(): ReadonlyMap<DomainEntity, DomainProperty[]> {
+    return new Map(this.#semanticPropertiesCache)
+  }
+
+  /**
+   * Returns properties for a specific entity that have a specific semantic type.
+   * Provides O(1) lookup using the precomputed cache.
+   */
+  public getPropertiesBySemantic(entity: DomainEntity, semanticType: SemanticType): DomainProperty[] {
+    const semanticMap = this.#propertiesBySemanticCache.get(entity)
+    return semanticMap?.get(semanticType) || []
+  }
+
+  /**
+   * Returns a readonly map of associations with semantics.
+   * Note, it creates a copy of the cached map to prevent modification of the internal state.
+   */
+  public get semanticAssociationsCache(): ReadonlyMap<DomainEntity, DomainAssociation[]> {
+    return new Map(this.#semanticAssociationsCache)
+  }
+
+  /**
+   * Returns associations for a specific entity that have a specific semantic type.
+   * Provides O(1) lookup using the precomputed cache.
+   */
+  public getAssociationsBySemantic(entity: DomainEntity, semanticType: SemanticType): DomainAssociation[] {
+    const semanticMap = this.#associationsBySemanticCache.get(entity)
+    return semanticMap?.get(semanticType) || []
+  }
+
   constructor(schema: RuntimeApiModelSchema, domainSchema: DataDomainSchema) {
     super(schema, domainSchema)
 
-    if (schema.routingMap) {
-      this.#initializeRouter(schema.routingMap)
+    if (!schema.routingMap) {
+      throw new Exception('The runtime API model must have a routing map.', {
+        code: 'E_MISSING_ROUTING_MAP',
+        help: 'Ensure that the routingMap property is defined when creating a RuntimeApiModel.',
+      })
     }
 
+    this.#initializeRouter(schema.routingMap)
+
     this.#cacheEntitiesAndProperties()
     this.#precomputeAccessRules()
     this.#precomputeSessionProperties()
+    this.#precomputeSemanticProperties()
   }
 
   #precomputeSessionProperties(): void {
@@ -133,6 +194,72 @@ export class RuntimeApiModel extends ApiModel {
     }
   }
 
+  #precomputeSemanticProperties(): void {
+    if (!this.domain) {
+      return
+    }
+
+    const processEntity = (entity: DomainEntity) => {
+      if (this.#semanticPropertiesCache.has(entity)) {
+        return
+      }
+
+      const propertiesWithSemantics: DomainProperty[] = []
+      const semanticPropsMap = new Map<SemanticType, DomainProperty[]>()
+
+      for (const prop of entity.withInheritedProperties()) {
+        if (Array.isArray(prop.semantics) && prop.semantics.length > 0) {
+          propertiesWithSemantics.push(prop)
+
+          for (const semantic of prop.semantics) {
+            let propsForSemantic = semanticPropsMap.get(semantic.id)
+            if (!propsForSemantic) {
+              propsForSemantic = []
+              semanticPropsMap.set(semantic.id, propsForSemantic)
+            }
+            propsForSemantic.push(prop)
+          }
+        }
+      }
+
+      if (propertiesWithSemantics.length > 0) {
+        this.#semanticPropertiesCache.set(entity, propertiesWithSemantics)
+        this.#propertiesBySemanticCache.set(entity, semanticPropsMap)
+      }
+
+      const associationsWithSemantics: DomainAssociation[] = []
+      const semanticAssocMap = new Map<SemanticType, DomainAssociation[]>()
+
+      for (const assoc of entity.withInheritedAssociations()) {
+        if (Array.isArray(assoc.semantics) && assoc.semantics.length > 0) {
+          associationsWithSemantics.push(assoc)
+
+          for (const semantic of assoc.semantics) {
+            let assocForSemantic = semanticAssocMap.get(semantic.id)
+            if (!assocForSemantic) {
+              assocForSemantic = []
+              semanticAssocMap.set(semantic.id, assocForSemantic)
+            }
+            assocForSemantic.push(assoc)
+          }
+        }
+      }
+
+      if (associationsWithSemantics.length > 0) {
+        this.#semanticAssociationsCache.set(entity, associationsWithSemantics)
+        this.#associationsBySemanticCache.set(entity, semanticAssocMap)
+      }
+    }
+
+    for (const entity of this.domain.listEntities()) {
+      processEntity(entity)
+    }
+
+    for (const entity of this.domain.listAllForeignEntities()) {
+      processEntity(entity)
+    }
+  }
+
   #precomputeAccessRules(): void {
     for (const entity of this.exposes.values()) {
       for (const action of entity.actions) {
@@ -228,7 +355,7 @@ export class RuntimeApiModel extends ApiModel {
 
     this.cachedEntities.user = userEntity
 
-    for (const prop of userEntity.properties) {
+    for (const prop of userEntity.withInheritedProperties()) {
       if (prop.hasSemantic(SemanticType.Username)) {
         this.cachedProperties.username = prop
       }

package/src/modeling/generators/RuntimeModelGenerator.ts

@@ -0,0 +1,79 @@
+import { type ActionKind, type UpdateAction } from '../actions/index.js'
+import { ApiModel, type ApiModelSchema } from '../ApiModel.js'
+import { type RouteDefinition, type RuntimeApiModelSchema } from '../RuntimeApiModel.js'
+
+/**
+ * A class that takes the API model and generates a runtime-optimized API model.
+ *
+ * Note, the API model must be already validated before passing it to this generator.
+ * This class doesn't perform any validation, but it will throw an exception if the API model is invalid.
+ */
+export class RuntimeModelGenerator {
+  #apiModel: ApiModel
+  #apiSchema: ApiModelSchema
+  #routingMap: Record<string, RouteDefinition[]> = {}
+
+  constructor(input: ApiModel | ApiModelSchema) {
+    if (input instanceof ApiModel) {
+      this.#apiModel = input
+      this.#apiSchema = input.toJSON()
+    } else {
+      this.#apiModel = new ApiModel(input)
+      this.#apiSchema = input
+    }
+  }
+
+  public async generate(): Promise<RuntimeApiModelSchema> {
+    if (!this.#apiModel) {
+      throw new Error('API model is not defined')
+    }
+
+    for (const expose of this.#apiModel.exposes.values()) {
+      const colPath = expose.getAbsoluteCollectionPath()
+      const resPath = expose.getAbsoluteResourcePath()
+      for (const action of expose.actions) {
+        switch (action.kind) {
+          case 'list':
+            if (colPath) this.addRoute('GET', colPath, expose.key, action.kind)
+            break
+          case 'create':
+            if (colPath) this.addRoute('POST', colPath, expose.key, action.kind)
+            break
+          case 'search':
+            if (colPath) this.addRoute('POST', `${colPath}/search`, expose.key, action.kind)
+            break
+          case 'read':
+            if (resPath) this.addRoute('GET', resPath, expose.key, action.kind)
+            break
+          case 'update':
+            if (resPath) {
+              const updateAction = action as UpdateAction
+              for (const method of updateAction.allowedMethods) {
+                this.addRoute(method, resPath, expose.key, action.kind)
+              }
+            }
+            break
+          case 'delete':
+            if (resPath) this.addRoute('DELETE', resPath, expose.key, action.kind)
+            break
+        }
+      }
+    }
+
+    return {
+      ...this.#apiSchema,
+      routingMap: this.#routingMap,
+    }
+  }
+
+  private addRoute(method: string, path: string, exposedEntityKey: string, actionKind: ActionKind): void {
+    const upperMethod = method.toUpperCase()
+    if (!this.#routingMap[upperMethod]) {
+      this.#routingMap[upperMethod] = []
+    }
+    this.#routingMap[upperMethod].push({
+      path,
+      lookup: { exposedEntityKey, actionKind },
+    })
+  }
+}