@api-client/core 0.16.1 → 0.17.1

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

@@ -42062,10 +42062,10 @@
 "@id": "#209"
 },
 {
-"@id": "#191"
+"@id": "#194"
 },
 {
-"@id": "#194"
+"@id": "#191"
 },
 {
 "@id": "#197"
@@ -42816,10 +42816,10 @@
 "@id": "#213"
 },
 {
-"@id": "#216"
+"@id": "#219"
 },
 {
-"@id": "#219"
+"@id": "#216"
 }
 ],
 "doc:root": false,
@@ -43436,7 +43436,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "countryCode: \"BE\"\ngraydonEnterpriseId: 1057155523\nregistrationId: \"0422319093\"\nvatNumber: \"BE0422319093\"\ngraydonCompanyId: \"0422319093\"\nisBranchOffice: false\n",
+"doc:raw": "addressType: 'REGISTERED-OFFICE-ADDRESS'\nstreetName: 'UITBREIDINGSTRAAT'\nhouseNumber: '84'\nhouseNumberAddition: '/1'\npostalCode: '2600'\ncity: 'BERCHEM (ANTWERPEN)'\ncountry: 'Belgium'\ncountryCode: 'BE'\nfullFormatedAddress: \"UITBREIDINGSTRAAT 84 /1, 2600 BERCHEM (ANTWERPEN), BELIUM\"\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43457,7 +43457,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "addressType: 'REGISTERED-OFFICE-ADDRESS'\nstreetName: 'UITBREIDINGSTRAAT'\nhouseNumber: '84'\nhouseNumberAddition: '/1'\npostalCode: '2600'\ncity: 'BERCHEM (ANTWERPEN)'\ncountry: 'Belgium'\ncountryCode: 'BE'\nfullFormatedAddress: \"UITBREIDINGSTRAAT 84 /1, 2600 BERCHEM (ANTWERPEN), BELIUM\"\n",
+"doc:raw": "countryCode: \"BE\"\ngraydonEnterpriseId: 1057155523\nregistrationId: \"0422319093\"\nvatNumber: \"BE0422319093\"\ngraydonCompanyId: \"0422319093\"\nisBranchOffice: false\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44274,7 +44274,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "-\n  type: 'GENERAL'\n  value: 'info@company.be'\n-\n  type: 'IT_DEPT'\n  value: 'it-service@company.be'\n",
+"doc:raw": "type: \"GENERAL\"\nvalue: \"www.company.be\"\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44295,7 +44295,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: \"GENERAL\"\nvalue: \"www.company.be\"\n",
+"doc:raw": "-\n  type: 'GENERAL'\n  value: 'info@company.be'\n-\n  type: 'IT_DEPT'\n  value: 'it-service@company.be'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44756,12 +44756,12 @@
 {
 "@id": "#193/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#193",
-"sourcemaps:value": "[(1,0)-(7,0)]"
+"sourcemaps:value": "[(1,0)-(10,0)]"
 },
 {
 "@id": "#196/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#196",
-"sourcemaps:value": "[(1,0)-(10,0)]"
+"sourcemaps:value": "[(1,0)-(7,0)]"
 },
 {
 "@id": "#199/source-map/lexical/element_0",
@@ -45126,12 +45126,12 @@
 {
 "@id": "#218/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#218",
-"sourcemaps:value": "[(1,0)-(7,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#221/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#221",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(7,0)]"
 },
 {
 "@id": "#338/source-map/synthesized-field/element_1",

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.16.1",
+  "version": "0.17.1",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {

package/src/modeling/GraphUtils.ts

@@ -1,5 +1,6 @@
 import type { Graph } from '@api-client/graph/graph/Graph.js'
 import type { DomainGraphEdge, DomainGraphNodeType } from './types.js'
+import { DomainAssociationKind } from '../models/kinds.js'
 
 /**
  * Recursively removes a node and all its children from the graph.
@@ -9,18 +10,28 @@ export function removeGraphNode(graph: Graph<unknown, DomainGraphNodeType, Domai
   if (!graph.hasNode(key)) {
     return
   }
+  const node = graph.node(key)
+  if (!node) {
+    return
+  }
+  if (node.kind === DomainAssociationKind) {
+    // If the node is an association, remove the association from the graph,
+    // but do not follow its children, as it would remove entities associated with it.
+    graph.removeNode(key)
+    return
+  }
   for (const child of graph.children(key)) {
     removeGraphNode(graph, child)
   }
+  // Remove all edges from the node.
   for (const edge of graph.outEdges(key)) {
     const label = graph.edge(edge)
     if (!label) {
       continue
     }
-    // While associations should be associated with the entity through an edge,
-    // I am still on a fence about properties being the same...
-    // We won't be reusing properties within a domain model.
-    if (['property', 'association'].includes(label.type)) {
+    if (label.type === 'association') {
+      removeGraphNode(graph, edge.w)
+    } else if (label.type === 'property') {
       removeGraphNode(graph, edge.w)
     }
   }

package/src/modeling/Semantics.ts

@@ -227,6 +227,44 @@ export enum SemanticScope {
   Association = 'Association',
 }
 
+/**
+ * Defines categories for organizing semantics in the UI.
+ */
+export enum SemanticCategory {
+  /**
+   * User management, authentication, and access control
+   */
+  Identity = 'Identity & Authentication',
+  /**
+   * Timestamps, versioning, and record lifecycle
+   */
+  Lifecycle = 'Timestamps & Versioning',
+  /**
+   * Text content, media, and rich content types
+   */
+  Content = 'Content & Media',
+  /**
+   * Business-specific data like pricing, inventory, status
+   */
+  Business = 'Business Data',
+  /**
+   * Contact information and communication
+   */
+  Contact = 'Contact Information',
+  /**
+   * Organization, categorization, and tagging
+   */
+  Organization = 'Classification & Organization',
+  /**
+   * Location and geographical data
+   */
+  Location = 'Location & Geography',
+  /**
+   * Calculated and derived values
+   */
+  Computed = 'Computed Values',
+}
+
 /**
  * A base interface for all Data Semantics, containing common properties.
  * A semantic is an annotation applied to a Data Entity, Property, or Association
@@ -250,6 +288,10 @@ interface BaseDataSemantic {
    * Specifies whether the semantic applies to an Entity, Property, or Association.
    */
   scope: SemanticScope
+  /**
+   * The category this semantic belongs to for UI organization.
+   */
+  category: SemanticCategory
 }
 
 /**
@@ -307,213 +349,296 @@ export type DataSemantic = EntitySemantic | PropertySemantic | AssociationSemant
  */
 export const DataSemantics: Record<SemanticType, DataSemantic> = {
   //
-  // Entity-Level Definitions
+  // Identity & Authentication
   //
 
   [SemanticType.User]: {
     id: SemanticType.User,
     displayName: 'User Entity',
     scope: SemanticScope.Entity,
-    description: 'Designates an entity that represents system users, crucial for authentication and authorization.',
+    description: 'System users and accounts',
+    category: SemanticCategory.Identity,
   },
-
-  //
-  // Property-Level Definitions
-  //
-
   [SemanticType.Password]: {
     id: SemanticType.Password,
     displayName: 'User Password',
     scope: SemanticScope.Property,
-    description:
-      'Annotates the field as the user password. The runtime should treat this field with special care, ensuring it is encrypted and not exposed in API responses.',
+    description: 'Secure password field',
+    category: SemanticCategory.Identity,
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.UserRole]: {
+    id: SemanticType.UserRole,
+    displayName: 'User Role Field',
+    scope: SemanticScope.Property,
+    description: 'User permissions and access level',
+    category: SemanticCategory.Identity,
     applicableDataTypes: ['string'],
   },
+  [SemanticType.ResourceOwnerIdentifier]: {
+    id: SemanticType.ResourceOwnerIdentifier,
+    displayName: 'Resource Owner Identifier',
+    scope: SemanticScope.Association,
+    description: 'Links record to owner user',
+    category: SemanticCategory.Identity,
+  },
+
+  //
+  // Timestamps & Versioning
+  //
+
   [SemanticType.CreatedTimestamp]: {
     id: SemanticType.CreatedTimestamp,
     displayName: 'Creation Timestamp',
     scope: SemanticScope.Property,
-    description: "Marks a field as the one that contains the object's creation timestamp.",
+    description: 'When record was created',
+    category: SemanticCategory.Lifecycle,
     applicableDataTypes: ['datetime'],
   },
   [SemanticType.UpdatedTimestamp]: {
     id: SemanticType.UpdatedTimestamp,
     displayName: 'Update Timestamp',
     scope: SemanticScope.Property,
-    description: "Marks a field as the field that contains object's last modification timestamp.",
+    description: 'When record was last modified',
+    category: SemanticCategory.Lifecycle,
     applicableDataTypes: ['datetime'],
   },
   [SemanticType.DeletedTimestamp]: {
     id: SemanticType.DeletedTimestamp,
     displayName: 'Soft Delete Timestamp',
     scope: SemanticScope.Property,
-    description: "Marks a field as the field that contains object's deletion timestamp.",
+    description: 'When record was marked deleted',
+    category: SemanticCategory.Lifecycle,
     applicableDataTypes: ['datetime'],
   },
-  [SemanticType.PublicUniqueName]: {
-    id: SemanticType.PublicUniqueName,
-    displayName: 'Public Unique Name (Slug)',
+  [SemanticType.DeletedFlag]: {
+    id: SemanticType.DeletedFlag,
+    displayName: 'Soft Delete Flag',
     scope: SemanticScope.Property,
-    description: 'A user-friendly, unique public identifier for a resource, often used in URLs.',
-    applicableDataTypes: ['string'],
+    description: 'Mark record as deleted',
+    category: SemanticCategory.Lifecycle,
+    applicableDataTypes: ['boolean'],
+  },
+  [SemanticType.Version]: {
+    id: SemanticType.Version,
+    displayName: 'Version Number',
+    scope: SemanticScope.Property,
+    description: 'Auto-incrementing version counter',
+    category: SemanticCategory.Lifecycle,
+    applicableDataTypes: ['number'],
   },
+
+  //
+  // Content & Media
+  //
+
   [SemanticType.Title]: {
     id: SemanticType.Title,
     displayName: 'Record Title',
     scope: SemanticScope.Property,
-    description: 'A title for the record. Used as a source for the PublicUniqueName semantic.',
+    description: 'Main title or heading',
+    category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
   },
-  [SemanticType.UserRole]: {
-    id: SemanticType.UserRole,
-    displayName: 'User Role Field',
+  [SemanticType.Description]: {
+    id: SemanticType.Description,
+    displayName: 'Description',
     scope: SemanticScope.Property,
-    description: "A text or enum field that defines the user's role for role-based authorization.",
+    description: 'Detailed description text',
+    category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
   },
-  [SemanticType.Status]: {
-    id: SemanticType.Status,
-    displayName: 'Record Status',
+  [SemanticType.Summary]: {
+    id: SemanticType.Summary,
+    displayName: 'Summary',
     scope: SemanticScope.Property,
-    description: 'A text or enum field to represent the state of a record.',
+    description: 'Brief summary text',
+    category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
   },
-  [SemanticType.Version]: {
-    id: SemanticType.Version,
-    displayName: 'Version Number',
+  [SemanticType.Markdown]: {
+    id: SemanticType.Markdown,
+    displayName: 'Markdown Content',
     scope: SemanticScope.Property,
-    description: 'An integer field that automatically increments on every update.',
-    applicableDataTypes: ['number'],
+    description: 'Formatted text content',
+    category: SemanticCategory.Content,
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.HTML]: {
+    id: SemanticType.HTML,
+    displayName: 'HTML Content',
+    scope: SemanticScope.Property,
+    description: 'Rich HTML content',
+    category: SemanticCategory.Content,
+    applicableDataTypes: ['string'],
   },
   [SemanticType.ImageURL]: {
     id: SemanticType.ImageURL,
     displayName: 'Image URL',
     scope: SemanticScope.Property,
-    description: 'Annotates a field that holds a reference to an image data via an URL.',
+    description: 'Link to image file',
+    category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
   },
   [SemanticType.FileURL]: {
     id: SemanticType.FileURL,
     displayName: 'File URL',
     scope: SemanticScope.Property,
-    description: 'Annotates a field that holds a reference to a file object via an URL (non-image binary data).',
+    description: 'Link to file attachment',
+    category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
   },
-  [SemanticType.DeletedFlag]: {
-    id: SemanticType.DeletedFlag,
-    displayName: 'Soft Delete Flag',
-    scope: SemanticScope.Property,
-    description: 'A boolean property that marks the object as deleted without physically removing it.',
-    applicableDataTypes: ['boolean'],
-  },
-  [SemanticType.Markdown]: {
-    id: SemanticType.Markdown,
-    displayName: 'Markdown Content',
+
+  //
+  // Business Data
+  //
+
+  [SemanticType.Status]: {
+    id: SemanticType.Status,
+    displayName: 'Record Status',
     scope: SemanticScope.Property,
-    description: 'A text field that contains markdown content.',
+    description: 'Current state of record',
+    category: SemanticCategory.Business,
     applicableDataTypes: ['string'],
   },
-  [SemanticType.HTML]: {
-    id: SemanticType.HTML,
-    displayName: 'HTML Content',
+  [SemanticType.Price]: {
+    id: SemanticType.Price,
+    displayName: 'Price',
     scope: SemanticScope.Property,
-    description: 'Annotates a field that contains HTML content.',
-    applicableDataTypes: ['string'],
+    description: 'Monetary value with currency',
+    category: SemanticCategory.Business,
+    applicableDataTypes: ['number', 'string'],
   },
-  [SemanticType.GeospatialCoordinates]: {
-    id: SemanticType.GeospatialCoordinates,
-    displayName: 'Geospatial Coordinates',
+  [SemanticType.SKU]: {
+    id: SemanticType.SKU,
+    displayName: 'SKU',
     scope: SemanticScope.Property,
-    description: 'Annotates a field that holds geospatial coordinate data (latitude/longitude).',
+    description: 'Product identification code',
+    category: SemanticCategory.Business,
     applicableDataTypes: ['string'],
   },
+
+  //
+  // Contact Information
+  //
+
   [SemanticType.Email]: {
     id: SemanticType.Email,
     displayName: 'Email',
     scope: SemanticScope.Property,
-    description: 'Annotates a field as an email address with validation and verification options.',
+    description: 'Email address',
+    category: SemanticCategory.Contact,
     applicableDataTypes: ['string'],
   },
   [SemanticType.Phone]: {
     id: SemanticType.Phone,
     displayName: 'Phone',
     scope: SemanticScope.Property,
-    description: 'Annotates a field as a phone number with validation and formatting options.',
+    description: 'Phone number',
+    category: SemanticCategory.Contact,
     applicableDataTypes: ['string'],
   },
-  [SemanticType.Price]: {
-    id: SemanticType.Price,
-    displayName: 'Price',
-    scope: SemanticScope.Property,
-    description: 'Annotates a field as a monetary value with currency support and precision control.',
-    applicableDataTypes: ['number', 'string'],
-  },
   [SemanticType.URL]: {
     id: SemanticType.URL,
     displayName: 'URL',
     scope: SemanticScope.Property,
-    description: 'Annotates a field as a URL with validation and allowed protocols.',
+    description: 'Web address or link',
+    category: SemanticCategory.Contact,
     applicableDataTypes: ['string'],
   },
-  [SemanticType.SKU]: {
-    id: SemanticType.SKU,
-    displayName: 'SKU',
+
+  //
+  // Classification & Organization
+  //
+
+  [SemanticType.PublicUniqueName]: {
+    id: SemanticType.PublicUniqueName,
+    displayName: 'Public Unique Name (Slug)',
     scope: SemanticScope.Property,
-    description:
-      'Annotates a field as a Stock Keeping Unit (SKU). Enforces uniqueness at the database level, critical for product catalogs. Provides automatic validation and formatting for product identification codes.',
+    description: 'URL-friendly unique identifier',
+    category: SemanticCategory.Organization,
     applicableDataTypes: ['string'],
   },
-  [SemanticType.Description]: {
-    id: SemanticType.Description,
-    displayName: 'Description',
-    scope: SemanticScope.Property,
-    description: 'Annotates a field as a long-form description.',
-    applicableDataTypes: ['string'],
+  [SemanticType.Tags]: {
+    id: SemanticType.Tags,
+    displayName: 'Tags',
+    scope: SemanticScope.Association,
+    description: 'Enable tagging functionality',
+    category: SemanticCategory.Organization,
   },
-  [SemanticType.Summary]: {
-    id: SemanticType.Summary,
-    displayName: 'Summary',
+  [SemanticType.Categories]: {
+    id: SemanticType.Categories,
+    displayName: 'Categories',
+    scope: SemanticScope.Association,
+    description: 'Enable categorization functionality',
+    category: SemanticCategory.Organization,
+  },
+
+  //
+  // Location & Geography
+  //
+
+  [SemanticType.GeospatialCoordinates]: {
+    id: SemanticType.GeospatialCoordinates,
+    displayName: 'Geospatial Coordinates',
     scope: SemanticScope.Property,
-    description: 'Annotates a field as a short summary.',
+    description: 'Location coordinates',
+    category: SemanticCategory.Location,
     applicableDataTypes: ['string'],
   },
+
+  //
+  // Computed Values
+  //
+
   [SemanticType.Calculated]: {
     id: SemanticType.Calculated,
     displayName: 'Calculated',
     scope: SemanticScope.Property,
-    description: 'Annotates a field as a calculated value based on a formula.',
+    description: 'Auto-calculated field value',
+    category: SemanticCategory.Computed,
     applicableDataTypes: ['string'],
   },
   [SemanticType.Derived]: {
     id: SemanticType.Derived,
     displayName: 'Derived',
     scope: SemanticScope.Property,
-    description: 'Annotates a field as derived from other fields.',
+    description: 'Value derived from other fields',
+    category: SemanticCategory.Computed,
     applicableDataTypes: ['string'],
   },
+}
 
-  //
-  // Association-Level Definitions
-  //
+/**
+ * Helper function to get all semantics grouped by category.
+ * Useful for organizing semantics in UI dropdowns and forms.
+ */
+export const getSemanticsByCategory = (): Record<SemanticCategory, DataSemantic[]> => {
+  const result: Record<SemanticCategory, DataSemantic[]> = {
+    [SemanticCategory.Identity]: [],
+    [SemanticCategory.Lifecycle]: [],
+    [SemanticCategory.Content]: [],
+    [SemanticCategory.Business]: [],
+    [SemanticCategory.Contact]: [],
+    [SemanticCategory.Organization]: [],
+    [SemanticCategory.Location]: [],
+    [SemanticCategory.Computed]: [],
+  }
 
-  [SemanticType.ResourceOwnerIdentifier]: {
-    id: SemanticType.ResourceOwnerIdentifier,
-    displayName: 'Resource Owner Identifier',
-    scope: SemanticScope.Association,
-    description: 'Links a resource to a "User" entity instance, indicating ownership for access control.',
-  },
-  [SemanticType.Tags]: {
-    id: SemanticType.Tags,
-    displayName: 'Tags',
-    scope: SemanticScope.Association,
-    description: 'Annotates an association as supporting tag functionality.',
-  },
-  [SemanticType.Categories]: {
-    id: SemanticType.Categories,
-    displayName: 'Categories',
-    scope: SemanticScope.Association,
-    description: 'Annotates an association as supporting category functionality.',
-  },
+  Object.values(DataSemantics).forEach((semantic) => {
+    result[semantic.category].push(semantic)
+  })
+
+  return result
+}
+
+/**
+ * Helper function to get semantics for a specific category.
+ * @param category The category to filter by
+ * @returns Array of semantics in the specified category
+ */
+export const getSemanticsByCategoryType = (category: SemanticCategory): DataSemantic[] => {
+  return Object.values(DataSemantics).filter((semantic) => semantic.category === category)
 }
 
 /**

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

@@ -8,7 +8,10 @@ import {
   type ExposedEntity,
 } from '../../../src/index.js'
 
-test.group('ApiModel.createSchema()', () => {
+test.group('ApiModel.createSchema()', (g) => {
+  g.tests.forEach((test) => {
+    test.tags(['@modeling', '@api', '@schema'])
+  })
   test('creates a schema with default values', ({ assert }) => {
     const schema = ApiModel.createSchema()
     assert.equal(schema.kind, ApiModelKind)
@@ -64,7 +67,11 @@ test.group('ApiModel.createSchema()', () => {
   })
 })
 
-test.group('ApiModel.constructor()', () => {
+test.group('ApiModel.constructor()', (g) => {
+  g.tests.forEach((test) => {
+    test.tags(['@modeling', '@api', '@creation'])
+  })
+
   test('creates an instance with default values', ({ assert }) => {
     const model = new ApiModel()
     assert.equal(model.kind, ApiModelKind)
@@ -133,7 +140,10 @@ test.group('ApiModel.constructor()', () => {
   })
 })
 
-test.group('ApiModel.toJSON()', () => {
+test.group('ApiModel.toJSON()', (g) => {
+  g.tests.forEach((test) => {
+    test.tags(['@modeling', '@api', '@serialization'])
+  })
   test('serializes default values', ({ assert }) => {
     const model = new ApiModel()
     const json = model.toJSON()
@@ -181,7 +191,10 @@ test.group('ApiModel.toJSON()', () => {
   })
 })
 
-test.group('ApiModel.exposeEntity()', () => {
+test.group('ApiModel.exposeEntity()', (g) => {
+  g.tests.forEach((test) => {
+    test.tags(['@modeling', '@api'])
+  })
   test('exposes a new entity', ({ assert }) => {
     const model = new ApiModel()
     const entityKey = 'new-entity'
@@ -228,7 +241,10 @@ test.group('ApiModel.exposeEntity()', () => {
   })
 })
 
-test.group('ApiModel.removeEntity()', () => {
+test.group('ApiModel.removeEntity()', (g) => {
+  g.tests.forEach((test) => {
+    test.tags(['@modeling', '@api'])
+  })
   test('removes an existing entity', ({ assert }) => {
     const model = new ApiModel()
     const entityKey = 'entity-to-remove'
@@ -274,7 +290,10 @@ test.group('ApiModel.removeEntity()', () => {
   })
 })
 
-test.group('ApiModel.getExposedEntity()', () => {
+test.group('ApiModel.getExposedEntity()', (g) => {
+  g.tests.forEach((test) => {
+    test.tags(['@modeling', '@api'])
+  })
   test('returns an existing exposed entity', ({ assert }) => {
     const model = new ApiModel()
     const entityKey = 'get-entity'