@api-client/core 0.19.29 → 0.19.31

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.19.29",
+  "version": "0.19.31",
   "license": "UNLICENSED",
   "exports": {
     "./browser.js": {

package/skills-lock.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "skills": {
+    "gemini-api": {
+      "source": "google/skills",
+      "sourceType": "github",
+      "computedHash": "445259b8086e10073300f8451dea10a2c62d8616723edf5d376eaf337f248a68"
+    }
+  }
+}

package/src/modeling/DomainAssociation.ts

@@ -8,7 +8,7 @@ import type { DomainEntity } from './DomainEntity.js'
 import type { Shapes } from '@api-client/amf-core'
 import type { AssociationBinding, AssociationBindings, AssociationWebBindings } from './Bindings.js'
 import { DomainAttributeAttribute, DomainAttributeAttributes } from './DataFormat.js'
-import type { AssociationTarget, DomainGraphEdge } from './types.js'
+import type { AssociationSchema, AssociationTarget, DomainGraphEdge } from './types.js'
 import { ShapeGenerator } from './amf/ShapeGenerator.js'
 import { DataSemantics, isAssociationSemantic, type SemanticType, type AppliedDataSemantic } from './Semantics.js'
 
@@ -53,7 +53,7 @@ export interface DomainAssociationSchema extends DomainElementSchema {
    * referenced entities schemas. Note, changes in the referenced entities may not be propagated
    * to schemas altered by the user.
    */
-  schema?: Shapes.IApiAssociationShape
+  schema?: AssociationSchema
   /**
    * The list of bindings for this property.
    *
@@ -153,7 +153,7 @@ export class DomainAssociation extends DomainElement {
    * The schema allowing to translate the model into a
    * specific format (like JSON, RAML, XML, etc.)
    */
-  @observed({ deep: true }) accessor schema: Shapes.IApiAssociationShape | undefined
+  @observed({ deep: true }) accessor schema: AssociationSchema | undefined
 
   /**
    * The list of bindings for this property.
@@ -351,7 +351,7 @@ export class DomainAssociation extends DomainElement {
    * const schema = association.ensureSchema();
    * ```
    */
-  ensureSchema(): Shapes.IApiAssociationShape {
+  ensureSchema(): AssociationSchema {
     if (!this.schema) {
       this.schema = {}
     }

package/src/modeling/ai/domain_response_schema.ts

@@ -94,7 +94,7 @@ const PropertySchema = {
 const AssociationSchemaShape = {
   type: Type.OBJECT,
   properties: {
-    linked: { type: Type.BOOLEAN },
+    embedded: { type: Type.BOOLEAN, description: 'Whether the association should be embedded in the target entity' },
     unionType: { type: Type.STRING, description: 'Enum: allOf, anyOf, oneOf, not' },
   },
 }

package/src/modeling/ai/types.ts

@@ -1,10 +1,9 @@
-import type { Shapes } from '@api-client/amf-core'
 import type { Exception } from '../../exceptions/exception.js'
 import type { AiSessionSchema } from '../../models/AiSession.js'
 import type { DomainPropertyType } from '../DataFormat.js'
 import type { OnDeleteRule } from '../index.js'
 import { SemanticType } from '../Semantics.js'
-import type { AssociationTarget, PropertySchema } from '../types.js'
+import type { AssociationSchema, AssociationTarget, PropertySchema } from '../types.js'
 import type { AiModelMessageSchema, AiModelMessage, AiUserMessageSchema } from '../../models/AiMessage.js'
 
 /**
@@ -150,7 +149,7 @@ export interface AiDomainAssociation {
   multiple?: boolean
   onDelete?: OnDeleteRule
   semantics?: AiDomainSemantic[]
-  schema?: Shapes.IApiAssociationShape
+  schema?: AssociationSchema
 }
 
 /**

package/src/modeling/amf/ShapeGenerator.ts

@@ -199,7 +199,7 @@ export class ShapeGenerator {
    */
   associationShape(input: DomainAssociation, visited: Set<string> = new Set<string>()): Shapes.IShapeUnion | undefined {
     const schema = input.schema
-    if (schema && schema.linked) {
+    if (!schema?.embedded) {
       return this.createLinkedShape(input)
     }
     const items = this.associationUnion(input, visited)

package/src/modeling/generators/oas_312/OasGenerator.ts

@@ -439,7 +439,7 @@ export class OasGenerator {
       }
       const links: Record<string, LinkObject> = {}
       for (const assoc of domainEntity.associations) {
-        if (assoc.schema?.linked === false) {
+        if (assoc.schema?.embedded === true) {
           continue
         }
         const targets = Array.from(assoc.listTargets())

package/src/modeling/generators/oas_312/OasSchemaGenerator.ts

@@ -105,12 +105,12 @@ export class OasSchemaGenerator {
       const targets = Array.from(assoc.listTargets())
       if (targets.length === 0) continue
 
-      const linked = assoc.schema?.linked === true
+      const linked = !assoc.schema?.embedded
       const targetRefs: (SchemaObject | ReferenceObject)[] = []
 
       for (const targetEntity of targets) {
         if (linked) {
-          // When an entity is linked then we treat it as a regular property, which value is a key to
+          // When an entity is not embedded then we treat it as a regular property, which value is a key to
           // the target entity. The consuming application has to construct the endpoint manually.
           const targetName = targetEntity.info.displayName || targetEntity.info.name || targetEntity.key
           targetRefs.push({
@@ -118,7 +118,7 @@ export class OasSchemaGenerator {
             description: `The ID of the linked ${targetName}.`,
           })
         } else {
-          // If not linked, embed the resource as a reference to the schema.
+          // If "embedded", add the resource as a reference to the schema.
           if (targetEntity !== entity) {
             this.generateEntity(targetEntity)
           }

package/src/modeling/generators/oas_320/OasSchemaGenerator.ts

@@ -78,12 +78,12 @@ export class OasSchemaGenerator {
       const targets = Array.from(assoc.listTargets())
       if (targets.length === 0) continue
 
-      const linked = assoc.schema?.linked === true
+      const linked = !assoc.schema?.embedded
       const targetRefs: (SchemaObject | ReferenceObject)[] = []
 
       for (const targetEntity of targets) {
         if (linked) {
-          // When an entity is linked then we treat it as a regular property, which value is a key to
+          // When an entity is not embedded then we treat it as a regular property, which value is a key to
           // the target entity. The consuming application has to construct the endpoint manually.
           const targetName = targetEntity.info.displayName || targetEntity.info.name || targetEntity.key
           targetRefs.push({
@@ -91,7 +91,7 @@ export class OasSchemaGenerator {
             description: `The ID of the linked ${targetName}.`,
           })
         } else {
-          // If not linked, embed the resource as a reference to the schema.
+          // If "embedded", add the resource as a reference to the schema.
           if (targetEntity !== entity) {
             this.generateEntity(targetEntity)
           }

package/src/modeling/types.ts

@@ -897,3 +897,59 @@ export interface ApiModelValidationResult {
    */
   issues: ApiModelValidationItem[]
 }
+
+/**
+ * Schema definition for an association.
+ *
+ * This is used to define how an association is represented in the schema.
+ */
+export interface AssociationSchema {
+  /**
+   * Whether the target entity should be embedded under the property name.
+   * When false, this association is just an information that one entity depend on another.
+   * When true, it changes the definition of the schema having this association to
+   * add the target schema properties inline with this property.
+   *
+   * **When true**
+   *
+   * ```javascript
+   * // generated schema for `address` association
+   * {
+   *  "name": "example value",
+   *  "address": {
+   *    "city": "example value",
+   *    ...
+   *  }
+   * }
+   * ```
+   *
+   * **When false**
+   *
+   * ```javascript
+   * // generated schema for `address` association
+   * {
+   *  "name": "example value",
+   *  "address": "the key of the referenced schema"
+   * }
+   * ```
+   */
+  embedded?: boolean
+  /**
+   * When the association has multiple targets the union type should be
+   * set to describe which union this is.
+   *
+   * Possible values are:
+   *
+   * - allOf - To validate against `allOf`, the given data must be valid against
+   *   all of the given sub-schemas. When generating, it's a sum of all properties.
+   * - anyOf - To validate against `anyOf`, the given data must be valid against
+   *   any (one or more) of the given sub-schemas. When generation a schema, it takes first union schema.
+   * - oneOf - To validate against `oneOf`, the given data must be valid against
+   *   exactly one of the given sub-schemas. It behaves the same as `anyOf` when generating a schema
+   * - not - The `not` keyword declares that an instance validates if it doesn’t
+   *   validate against the given sub-schema. It has no use when generating a schema.
+   *
+   * @default anyOf
+   */
+  unionType?: 'allOf' | 'anyOf' | 'oneOf' | 'not'
+}

package/tests/unit/modeling/amf/shape_generator.spec.ts

@@ -762,6 +762,9 @@ test.group('associationProperty()', (group) => {
   })
 
   test('returns basic shape definition', ({ assert }) => {
+    a1.schema = {
+      embedded: true,
+    }
     const result = a1.toApiShape()
     assert.typeOf(result, 'object')
 
@@ -812,8 +815,8 @@ test.group('associationProperty()', (group) => {
     assert.equal(result.path, AmfNamespace.aml.vocabularies.data.key + 'a1', 'has the path')
   })
 
-  test('returns a link definition when created on the schema', ({ assert }) => {
-    a1.schema = { linked: true }
+  test('returns a reference definition when not embedded', ({ assert }) => {
+    a1.schema = { embedded: false }
     const result = a1.toApiShape()
     const range = result.range as Shapes.IApiScalarShape
     assert.equal(range.id, `link-${a1.key}`)
@@ -824,6 +827,9 @@ test.group('associationProperty()', (group) => {
   test('returns a default union type', ({ assert }) => {
     const e3 = m1.addEntity({ key: 'e3', info: { name: 'e3' } })
     a1.addTarget(e3)
+    a1.schema = {
+      embedded: true,
+    }
     const result = a1.toApiShape()
     const range = result.range as Shapes.IApiUnionShape
 
@@ -841,12 +847,18 @@ test.group('associationProperty()', (group) => {
 
   test('has no range when no associations', ({ assert }) => {
     a1.removeTarget(e2)
+    a1.schema = {
+      embedded: true,
+    }
     const result = a1.toApiShape()
     assert.isUndefined(result.range)
   })
 
   test('returns an array shape when multiple', ({ assert }) => {
     a1.multiple = true
+    a1.schema = {
+      embedded: true,
+    }
     const result = a1.toApiShape()
     const range = result.range as Shapes.IApiArrayShape
     assert.deepEqual(range.types, AmfTypes.IAmfArrayTypes)
@@ -859,7 +871,7 @@ test.group('associationProperty()', (group) => {
   })
 
   test('creates the "anyOf" union', ({ assert }) => {
-    a1.schema = { unionType: 'anyOf' }
+    a1.schema = { unionType: 'anyOf', embedded: true }
 
     const e3 = m1.addEntity({ key: 'e3', info: { name: 'e3' } })
     a1.addTarget(e3)
@@ -879,7 +891,7 @@ test.group('associationProperty()', (group) => {
   })
 
   test('creates the "allOf" union', ({ assert }) => {
-    a1.schema = { unionType: 'allOf' }
+    a1.schema = { unionType: 'allOf', embedded: true }
 
     const e3 = m1.addEntity({ key: 'e3', info: { name: 'e3' } })
     a1.addTarget(e3)
@@ -899,7 +911,7 @@ test.group('associationProperty()', (group) => {
   })
 
   test('creates the "oneOf" union', ({ assert }) => {
-    a1.schema = { unionType: 'oneOf' }
+    a1.schema = { unionType: 'oneOf', embedded: true }
 
     const e3 = m1.addEntity({ key: 'e3', info: { name: 'e3' } })
     a1.addTarget(e3)
@@ -919,7 +931,7 @@ test.group('associationProperty()', (group) => {
   })
 
   test('creates the "not" union', ({ assert }) => {
-    a1.schema = { unionType: 'not' }
+    a1.schema = { unionType: 'not', embedded: true }
 
     const e3 = m1.addEntity({ key: 'e3', info: { name: 'e3' } })
     a1.addTarget(e3)
@@ -938,7 +950,7 @@ test.group('associationProperty()', (group) => {
   })
 
   test('creates the "not" shape', ({ assert }) => {
-    a1.schema = { unionType: 'not' }
+    a1.schema = { unionType: 'not', embedded: true }
 
     const result = a1.toApiShape()
     const range = result.range as Shapes.IApiUnionShape
@@ -956,7 +968,7 @@ test.group('associationProperty()', (group) => {
 
   test('wraps the union in the array shape', ({ assert }) => {
     a1.multiple = true
-    a1.schema = { unionType: 'anyOf' }
+    a1.schema = { unionType: 'anyOf', embedded: true }
 
     const e3 = m1.addEntity({ key: 'e3', info: { name: 'e3' } })
     a1.addTarget(e3)
@@ -978,8 +990,8 @@ test.group('associationProperty()', (group) => {
     assert.lengthOf(p2.properties, 0, 'p2 has the properties')
   })
 
-  test('handles linked schema', ({ assert }) => {
-    a1.schema = { linked: true }
+  test('handles not embedded schema', ({ assert }) => {
+    a1.schema = { embedded: false }
     const result = a1.toApiShape()
     const range = result.range as Shapes.IApiScalarShape
     assert.equal(range.dataType, AmfNamespace.w3.xmlSchema.string)
@@ -988,13 +1000,16 @@ test.group('associationProperty()', (group) => {
   test('handles multiple associations', ({ assert }) => {
     const e3 = m1.addEntity({ key: 'e3', info: { name: 'e3' } })
     a1.addTarget(e3)
+    a1.schema = {
+      embedded: true,
+    }
     const result = a1.toApiShape()
     const range = result.range as Shapes.IApiUnionShape
     assert.lengthOf(range.anyOf, 2)
   })
 
   test('handles unionType', ({ assert }) => {
-    a1.schema = { unionType: 'allOf' }
+    a1.schema = { unionType: 'allOf', embedded: true }
     const e3 = m1.addEntity({ key: 'e3', info: { name: 'e3' } })
     a1.addTarget(e3)
     const result = a1.toApiShape()
@@ -1004,7 +1019,7 @@ test.group('associationProperty()', (group) => {
 
   test('handles multiple and unionType', ({ assert }) => {
     a1.multiple = true
-    a1.schema = { unionType: 'allOf' }
+    a1.schema = { unionType: 'allOf', embedded: true }
     const e3 = m1.addEntity({ key: 'e3', info: { name: 'e3' } })
     a1.addTarget(e3)
     const result = a1.toApiShape()
@@ -1119,9 +1134,9 @@ test.group('AI Generated tests', (group) => {
     assert.equal(items.format, AmfNamespace.w3.xmlSchema.integer)
   })
 
-  test('handles multiple associations with schema', ({ assert }) => {
+  test('handles multiple associations not embedded', ({ assert }) => {
     a1.multiple = true
-    a1.schema = { linked: false }
+    a1.schema = { embedded: true }
     const result = a1.toApiShape()
     const range = result.range as Shapes.IApiArrayShape
     assert.include(range.types, AmfNamespace.aml.vocabularies.shapes.ArrayShape)
@@ -1139,6 +1154,9 @@ test.group('AI Generated tests', (group) => {
         },
       },
     ]
+    a1.schema = {
+      embedded: true,
+    }
     const result = a1.toApiShape()
     const range = result.range as Shapes.IApiArrayShape
     assert.include(range.types, AmfNamespace.aml.vocabularies.shapes.ArrayShape)

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

@@ -664,7 +664,7 @@ test.group('DomainAssociation change observers', (g) => {
     const e1 = m1.addEntity()
     const a1 = e1.addAssociation()
     await sleep(1)
-    a1.schema = { linked: true }
+    a1.schema = { embedded: false }
     await assert.dispatchCount(domain, 'change', 1, { timeout: 1 })
   })
 

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

@@ -8,8 +8,8 @@ import {
   DataFormat,
   SemanticType,
   type OnDeleteRule,
+  type AssociationSchema,
 } from '../../../src/index.js'
-import { Shapes } from '@api-client/amf-core'
 
 test.group('DomainAssociation.createSchema()', () => {
   test('creates a valid schema with default values', ({ assert }) => {
@@ -58,7 +58,7 @@ test.group('DomainAssociation.createSchema()', () => {
   })
 
   test('creates a schema with provided schema', ({ assert }) => {
-    const schemaDefinition: Shapes.IApiAssociationShape = { linked: false }
+    const schemaDefinition: AssociationSchema = { embedded: false }
     const schema = DomainAssociation.createSchema({ schema: schemaDefinition })
     assert.deepEqual(schema.schema, schemaDefinition)
   })
@@ -88,7 +88,7 @@ test.group('DomainAssociation.createSchema()', () => {
   test('creates a schema with all properties', ({ assert }) => {
     const key = 'test-key'
     const info = { name: 'Test Association', description: 'Test description' }
-    const schemaDefinition: Shapes.IApiAssociationShape = { linked: false }
+    const schemaDefinition: AssociationSchema = { embedded: false }
     const multiple = true
     const required = true
     const bindings: AssociationBinding[] = [{ type: 'web', schema: { hidden: false } }]
@@ -144,7 +144,7 @@ test.group('DomainAssociation.createSchema()', () => {
   })
 
   test('creates a schema with cloned schema', ({ assert }) => {
-    const schemaDefinition: Shapes.IApiAssociationShape = { linked: false }
+    const schemaDefinition: AssociationSchema = { embedded: false }
     const schema = DomainAssociation.createSchema({ schema: schemaDefinition })
     assert.deepEqual(schema.schema, schemaDefinition)
     assert.notStrictEqual(schema.schema, schemaDefinition)
@@ -212,7 +212,7 @@ test.group('DomainAssociation.constructor()', () => {
   test('creates an instance with provided schema', ({ assert }) => {
     const dataDomain = new DataDomain()
     const parentKey = 'test-parent'
-    const schemaDefinition: Shapes.IApiAssociationShape = { linked: false }
+    const schemaDefinition: AssociationSchema = { embedded: false }
     const association = new DomainAssociation(dataDomain, parentKey, { schema: schemaDefinition })
     assert.deepEqual(association.schema, schemaDefinition)
   })
@@ -252,7 +252,7 @@ test.group('DomainAssociation.constructor()', () => {
     const parentKey = 'test-parent'
     const key = 'test-key'
     const info = { name: 'Test Association', description: 'Test description' }
-    const schemaDefinition: Shapes.IApiAssociationShape = { linked: false }
+    const schemaDefinition: AssociationSchema = { embedded: false }
     const multiple = true
     const required = true
     const bindings: AssociationBinding[] = [{ type: 'web', schema: { hidden: false } }]
@@ -316,7 +316,7 @@ test.group('DomainAssociation.constructor()', () => {
   test('creates an instance with cloned schema', ({ assert }) => {
     const dataDomain = new DataDomain()
     const parentKey = 'test-parent'
-    const schemaDefinition: Shapes.IApiAssociationShape = { linked: false }
+    const schemaDefinition: AssociationSchema = { embedded: false }
     const association = new DomainAssociation(dataDomain, parentKey, { schema: schemaDefinition })
     assert.deepEqual(association.schema, schemaDefinition)
     assert.notStrictEqual(association.schema, schemaDefinition)
@@ -390,7 +390,7 @@ test.group('DomainAssociation.toJSON()', () => {
   test('returns a JSON representation with provided schema', ({ assert }) => {
     const dataDomain = new DataDomain()
     const parentKey = 'test-parent'
-    const schemaDefinition: Shapes.IApiAssociationShape = { linked: false }
+    const schemaDefinition: AssociationSchema = { embedded: false }
     const association = new DomainAssociation(dataDomain, parentKey, { schema: schemaDefinition })
     const json = association.toJSON()
     assert.deepEqual(json.schema, schemaDefinition)
@@ -438,7 +438,7 @@ test.group('DomainAssociation.toJSON()', () => {
     const parentKey = 'test-parent'
     const key = 'test-key'
     const info = { name: 'Test Association', description: 'Test description' }
-    const schemaDefinition: Shapes.IApiAssociationShape = { linked: false }
+    const schemaDefinition: AssociationSchema = { embedded: false }
     const multiple = true
     const required = true
     const bindings: AssociationBinding[] = [{ type: 'web', schema: { hidden: false } }]
@@ -527,7 +527,7 @@ test.group('DomainAssociation.toJSON()', () => {
   test('returns a JSON representation with cloned schema', ({ assert }) => {
     const dataDomain = new DataDomain()
     const parentKey = 'test-parent'
-    const schemaDefinition: Shapes.IApiAssociationShape = { linked: false }
+    const schemaDefinition: AssociationSchema = { embedded: false }
     const association = new DomainAssociation(dataDomain, parentKey, { schema: schemaDefinition })
     const json = association.toJSON()
     assert.deepEqual(json.schema, schemaDefinition)
@@ -538,7 +538,7 @@ test.group('DomainAssociation.toJSON()', () => {
     const dataDomain = new DataDomain()
     const parentKey = 'test-parent'
     const association = new DomainAssociation(dataDomain, parentKey)
-    const schemaDefinition: Shapes.IApiAssociationShape = { linked: false }
+    const schemaDefinition: AssociationSchema = { embedded: false }
     association.schema = schemaDefinition
     const json = association.toJSON()
     assert.deepEqual(json.schema, schemaDefinition)
@@ -672,7 +672,7 @@ test.group('DomainAssociation.ensureSchema()', () => {
 
   test('returns the existing schema object if it exists', ({ assert }) => {
     const dataDomain = new DataDomain()
-    const schemaDefinition: Shapes.IApiAssociationShape = { linked: false }
+    const schemaDefinition: AssociationSchema = { embedded: false }
     const association = new DomainAssociation(dataDomain, 'test-parent', { schema: schemaDefinition })
     const originalSchema = association.schema
     const schema = association.ensureSchema()
@@ -682,7 +682,7 @@ test.group('DomainAssociation.ensureSchema()', () => {
 
   test('does not modify the existing schema object', ({ assert }) => {
     const dataDomain = new DataDomain()
-    const schemaDefinition: Shapes.IApiAssociationShape = { linked: false }
+    const schemaDefinition: AssociationSchema = { embedded: false }
     const association = new DomainAssociation(dataDomain, 'test-parent', { schema: schemaDefinition })
     const originalSchema = association.schema
     association.ensureSchema()
@@ -1083,7 +1083,7 @@ test.group('DomainAssociation.duplicate()', () => {
     association.readOnly = true
     association.onDelete = 'cascade'
     association.semantics = [{ id: SemanticType.ResourceOwnerIdentifier }]
-    association.schema = { linked: true, unionType: 'allOf' }
+    association.schema = { embedded: true, unionType: 'allOf' }
     association.bindings = [{ type: 'web', schema: { hidden: true } }]
 
     const duplicate = association.duplicate()
@@ -1095,7 +1095,7 @@ test.group('DomainAssociation.duplicate()', () => {
     assert.equal(duplicate.readOnly, true)
     assert.equal(duplicate.onDelete, 'cascade')
     assert.deepEqual(duplicate.semantics, [{ id: SemanticType.ResourceOwnerIdentifier }])
-    assert.deepEqual(duplicate.schema, { linked: true, unionType: 'allOf' })
+    assert.deepEqual(duplicate.schema, { embedded: true, unionType: 'allOf' })
     assert.deepEqual(duplicate.bindings, [{ type: 'web', schema: { hidden: true } }])
   })
 
@@ -1107,17 +1107,17 @@ test.group('DomainAssociation.duplicate()', () => {
 
     const association = entity.addAssociation({ targets: [{ key: targetEntity.key }] })
     association.info.name = 'original'
-    association.schema = { linked: false, unionType: 'anyOf' }
+    association.schema = { embedded: false, unionType: 'anyOf' }
     association.bindings = [{ type: 'web', schema: { hidden: false } }]
 
     const duplicate = association.duplicate()
 
     // Modify original schema and bindings
-    association.schema!.linked = true
+    association.schema!.embedded = true
     association.bindings[0].schema = { hidden: true }
 
     // Duplicate should be unaffected
-    assert.equal(duplicate.schema!.linked, false)
+    assert.equal(duplicate.schema!.embedded, false)
     assert.deepEqual(duplicate.bindings[0].schema, { hidden: false })
   })