@api-client/core 0.20.5 → 0.20.6

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.6",
   "license": "UNLICENSED",
   "exports": {
     "./browser.js": {

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/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,6 +109,60 @@ 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)
 
@@ -118,6 +173,7 @@ export class RuntimeApiModel extends ApiModel {
     this.#cacheEntitiesAndProperties()
     this.#precomputeAccessRules()
     this.#precomputeSessionProperties()
+    this.#precomputeSemanticProperties()
   }
 
   #precomputeSessionProperties(): void {
@@ -133,6 +189,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 +350,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/types.ts

@@ -974,3 +974,19 @@ export interface AssociationSchema {
    */
   unionType?: 'allOf' | 'anyOf' | 'oneOf' | 'not'
 }
+
+/**
+ * Options used when initializing a DataDomain.
+ */
+export interface DataDomainOptions {
+  /**
+   * The mode used during deserialization to control error tolerance.
+   * 'strict' throws errors on invalid references. 'lenient' collects them.
+   */
+  mode?: DeserializationMode
+  /**
+   * Whether the DataDomain is in read-only mode, which makes it immutable
+   * and enables internal caching optimizations.
+   */
+  readOnly?: boolean
+}

package/tests/unit/modeling/RuntimeApiModel.spec.ts

@@ -179,6 +179,97 @@ test.group('RuntimeApiModel', () => {
     assert.equal(runtimeModel.sessionProperties.get(prop2.key)?.key, prop2.key)
   }).tags(['@modeling', '@runtime'])
 
+  test('precomputes semanticPropertiesCache correctly', ({ assert }) => {
+    const domain = new DataDomain({ info: { version: '1.0.0' } })
+    const modelNode = domain.addModel({ key: 'users' })
+    const userEntity = modelNode.addEntity({ info: { name: 'User' } })
+    const prop1 = userEntity.addProperty({ info: { name: 'Prop1' }, semantics: [{ id: SemanticType.Password }] })
+    const prop2 = userEntity.addProperty({ info: { name: 'Prop2' }, semantics: [{ id: SemanticType.Username }] })
+    const prop3 = userEntity.addProperty({ info: { name: 'Prop3' } })
+
+    const schema = {
+      key: 'api-1',
+      info: { name: 'Test API' },
+      exposes: [
+        {
+          key: 'expose-1',
+          entity: { key: userEntity.key, domain: domain.key },
+          actions: [],
+        },
+      ],
+      routingMap: {},
+    }
+
+    const runtimeModel = new RuntimeApiModel(schema as any, domain.toJSON())
+
+    assert.equal(runtimeModel.semanticPropertiesCache.size, 1)
+
+    // Convert keys iterator to array to find the matched entity reference
+    const cachedEntities = Array.from(runtimeModel.semanticPropertiesCache.keys())
+    assert.equal(cachedEntities.length, 1)
+    assert.equal(cachedEntities[0].key, userEntity.key)
+
+    const cachedProps = runtimeModel.semanticPropertiesCache.get(cachedEntities[0])
+    assert.isDefined(cachedProps)
+    assert.equal(cachedProps?.length, 2)
+    assert.equal(cachedProps?.[0].key, prop1.key)
+    assert.equal(cachedProps?.[1].key, prop2.key)
+  }).tags(['@modeling', '@runtime'])
+
+  test('precomputes semanticAssociationsCache correctly', ({ assert }) => {
+    const domain = new DataDomain({ info: { version: '1.0.0' } })
+    const modelNode = domain.addModel({ key: 'users' })
+    const userEntity = modelNode.addEntity({ info: { name: 'User' } })
+
+    const assoc1 = userEntity.addAssociation({ info: { name: 'Assoc1' }, targets: [] })
+    assoc1.semantics = [{ id: SemanticType.Tags }]
+
+    const assoc2 = userEntity.addAssociation({ info: { name: 'Assoc2' }, targets: [] })
+    assoc2.semantics = [{ id: SemanticType.Categories }]
+
+    const assoc3 = userEntity.addAssociation({ info: { name: 'Assoc3' }, targets: [] })
+
+    const schema = {
+      key: 'api-1',
+      info: { name: 'Test API' },
+      exposes: [
+        {
+          key: 'expose-1',
+          entity: { key: userEntity.key, domain: domain.key },
+          actions: [],
+        },
+      ],
+      routingMap: {},
+    }
+
+    const runtimeModel = new RuntimeApiModel(schema as any, domain.toJSON())
+
+    assert.equal(runtimeModel.semanticAssociationsCache.size, 1)
+
+    // Convert keys iterator to array to find the matched entity reference
+    const cachedEntities = Array.from(runtimeModel.semanticAssociationsCache.keys())
+    assert.equal(cachedEntities.length, 1)
+    assert.equal(cachedEntities[0].key, userEntity.key)
+
+    const cachedAssocs = runtimeModel.semanticAssociationsCache.get(cachedEntities[0])
+    assert.isDefined(cachedAssocs)
+    assert.equal(cachedAssocs?.length, 2)
+    assert.equal(cachedAssocs?.[0].key, assoc1.key)
+    assert.equal(cachedAssocs?.[1].key, assoc2.key)
+
+    // Test getAssociationsBySemantic
+    const tagsAssocs = runtimeModel.getAssociationsBySemantic(cachedEntities[0], SemanticType.Tags)
+    assert.lengthOf(tagsAssocs, 1)
+    assert.equal(tagsAssocs[0].key, assoc1.key)
+
+    const categoriesAssocs = runtimeModel.getAssociationsBySemantic(cachedEntities[0], SemanticType.Categories)
+    assert.lengthOf(categoriesAssocs, 1)
+    assert.equal(categoriesAssocs[0].key, assoc2.key)
+
+    const emptyAssocs = runtimeModel.getAssociationsBySemantic(cachedEntities[0], SemanticType.ResourceOwnerIdentifier)
+    assert.lengthOf(emptyAssocs, 0)
+  }).tags(['@modeling', '@runtime', '@semantic'])
+
   test('throws exception if session property is missing from domain', ({ assert }) => {
     const domain = new DataDomain({ info: { version: '1.0.0' } })
     const modelNode = domain.addModel({ key: 'users' })

package/tests/unit/modeling/data_domain_entities.spec.ts

@@ -575,3 +575,59 @@ test.group('DataDomain.moveEntity()', () => {
     assert.isTrue(dataDomain.graph.hasNode(assoc.key))
   }).tags(['@modeling', '@entity', '@move'])
 })
+
+test.group('DomainEntity.listAllSemantics()', () => {
+  test('returns semantics from entity and its parents', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel()
+    const parentEntity = model.addEntity({ key: 'parent' })
+    const childEntity = model.addEntity({ key: 'child' })
+
+    parentEntity.addSemantic({ id: SemanticType.User })
+    childEntity.addSemantic({ id: SemanticType.Address })
+
+    childEntity.addParent(parentEntity.key)
+
+    const inherited = childEntity.listAllSemantics()
+    assert.lengthOf(inherited, 2)
+    const semanticIds = inherited.map((s) => s.id).sort()
+    assert.deepEqual(semanticIds, [SemanticType.Address, SemanticType.User].sort())
+  }).tags(['@modeling', '@entity', '@semantic'])
+
+  test('overrides parent semantics with the same id', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel()
+    const parentEntity = model.addEntity({ key: 'parent' })
+    const childEntity = model.addEntity({ key: 'child' })
+
+    parentEntity.addSemantic({ id: SemanticType.User, config: { value: 'parent-val' } })
+    childEntity.addSemantic({ id: SemanticType.User, config: { value: 'child-val' } })
+
+    childEntity.addParent(parentEntity.key)
+
+    const inherited = childEntity.listAllSemantics()
+    assert.lengthOf(inherited, 1)
+    assert.deepEqual(inherited[0].config, { value: 'child-val' })
+  }).tags(['@modeling', '@entity', '@semantic'])
+
+  test('uses cached inherited semantics when domain is readOnly', ({ assert }) => {
+    const dataDomain = new DataDomain(undefined, [], { readOnly: true })
+    const model = dataDomain.addModel()
+    const parentEntity = model.addEntity({ key: 'parent' })
+    const childEntity = model.addEntity({ key: 'child' })
+
+    parentEntity.addSemantic({ id: SemanticType.User })
+
+    childEntity.addParent(parentEntity.key)
+
+    const inherited1 = childEntity.listAllSemantics()
+    assert.lengthOf(inherited1, 1)
+
+    // Add another semantic bypassing normal immutable logic for test purposes
+    parentEntity.addSemantic({ id: SemanticType.Address })
+
+    const inherited2 = childEntity.listAllSemantics()
+    // Should still be length 1 due to the cache
+    assert.lengthOf(inherited2, 1)
+  }).tags(['@modeling', '@entity', '@semantic', '@readonly'])
+})