@api-client/core 0.16.0 → 0.17.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-client/core",
   "description": "The API Client's core client library. Works in NodeJS and in a ES enabled browser.",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {

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/semantics.spec.ts

@@ -2,10 +2,13 @@ import { test } from '@japa/runner'
 import {
   SemanticType,
   SemanticScope,
+  SemanticCategory,
   isEntitySemantic,
   isPropertySemantic,
   isAssociationSemantic,
   DataSemantics,
+  getSemanticsByCategory,
+  getSemanticsByCategoryType,
   type EntitySemantic,
   type PropertySemantic,
   type AssociationSemantic,
@@ -45,18 +48,21 @@ test.group('Semantics', () => {
       displayName: 'User Entity',
       description: 'Test',
       scope: SemanticScope.Entity,
+      category: SemanticCategory.Identity,
     }
     const propertySemantic: PropertySemantic = {
       id: SemanticType.CreatedTimestamp,
       displayName: 'Creation Timestamp',
       description: 'Test',
       scope: SemanticScope.Property,
+      category: SemanticCategory.Lifecycle,
     }
     const associationSemantic: AssociationSemantic = {
       id: SemanticType.ResourceOwnerIdentifier,
       displayName: 'Resource Owner Identifier',
       description: 'Test',
       scope: SemanticScope.Association,
+      category: SemanticCategory.Identity,
     }
 
     assert.isTrue(isEntitySemantic(entitySemantic))
@@ -70,18 +76,21 @@ test.group('Semantics', () => {
       displayName: 'User Entity',
       description: 'Test',
       scope: SemanticScope.Entity,
+      category: SemanticCategory.Identity,
     }
     const propertySemantic: PropertySemantic = {
       id: SemanticType.CreatedTimestamp,
       displayName: 'Creation Timestamp',
       description: 'Test',
       scope: SemanticScope.Property,
+      category: SemanticCategory.Lifecycle,
     }
     const associationSemantic: AssociationSemantic = {
       id: SemanticType.ResourceOwnerIdentifier,
       displayName: 'Resource Owner Identifier',
       description: 'Test',
       scope: SemanticScope.Association,
+      category: SemanticCategory.Identity,
     }
 
     assert.isFalse(isPropertySemantic(entitySemantic))
@@ -95,18 +104,21 @@ test.group('Semantics', () => {
       displayName: 'User Entity',
       description: 'Test',
       scope: SemanticScope.Entity,
+      category: SemanticCategory.Identity,
     }
     const propertySemantic: PropertySemantic = {
       id: SemanticType.CreatedTimestamp,
       displayName: 'Creation Timestamp',
       description: 'Test',
       scope: SemanticScope.Property,
+      category: SemanticCategory.Lifecycle,
     }
     const associationSemantic: AssociationSemantic = {
       id: SemanticType.ResourceOwnerIdentifier,
       displayName: 'Resource Owner Identifier',
       description: 'Test',
       scope: SemanticScope.Association,
+      category: SemanticCategory.Identity,
     }
 
     assert.isFalse(isAssociationSemantic(entitySemantic))
@@ -128,6 +140,11 @@ test.group('Semantics', () => {
       assert.isNotEmpty(semantic.description, `description for ${type} should not be empty`)
 
       assert.oneOf(semantic.scope, Object.values(SemanticScope), `scope for ${type} should be a valid SemanticScope`)
+      assert.oneOf(
+        semantic.category,
+        Object.values(SemanticCategory),
+        `category for ${type} should be a valid SemanticCategory`
+      )
 
       if (isPropertySemantic(semantic)) {
         if (semantic.applicableDataTypes) {
@@ -142,15 +159,18 @@ test.group('Semantics', () => {
     // Specific checks for some semantics
     const userSemantic = DataSemantics[SemanticType.User]
     assert.equal(userSemantic.scope, SemanticScope.Entity)
+    assert.equal(userSemantic.category, SemanticCategory.Identity)
 
     const createdTimestampSemantic = DataSemantics[SemanticType.CreatedTimestamp]
     assert.equal(createdTimestampSemantic.scope, SemanticScope.Property)
+    assert.equal(createdTimestampSemantic.category, SemanticCategory.Lifecycle)
     if (isPropertySemantic(createdTimestampSemantic)) {
       assert.deepEqual(createdTimestampSemantic.applicableDataTypes, ['datetime'])
     }
 
     const resourceOwnerSemantic = DataSemantics[SemanticType.ResourceOwnerIdentifier]
     assert.equal(resourceOwnerSemantic.scope, SemanticScope.Association)
+    assert.equal(resourceOwnerSemantic.category, SemanticCategory.Identity)
   })
 
   test('GeospatialCoordinates semantic should have correct definition', ({ assert }) => {
@@ -193,6 +213,58 @@ test.group('Semantics', () => {
     const description = geospatialSemantic.description
 
     // Check that the description mentions key features
-    assert.equal(description, 'Annotates a field that holds geospatial coordinate data (latitude/longitude).')
+    assert.equal(description, 'Location coordinates')
+  })
+
+  test('getSemanticsByCategory should group semantics correctly', ({ assert }) => {
+    const semanticsByCategory = getSemanticsByCategory()
+
+    // Check that all categories are present
+    const expectedCategories = Object.values(SemanticCategory)
+    expectedCategories.forEach((category) => {
+      assert.isDefined(semanticsByCategory[category], `Category ${category} should be present`)
+      assert.isArray(semanticsByCategory[category], `Category ${category} should be an array`)
+    })
+
+    // Check that User semantic is in Identity category
+    const identitySemantics = semanticsByCategory[SemanticCategory.Identity]
+    const userSemantic = identitySemantics.find((s) => s.id === SemanticType.User)
+    assert.isDefined(userSemantic, 'User semantic should be in Identity category')
+
+    // Check that CreatedTimestamp is in Lifecycle category
+    const lifecycleSemantics = semanticsByCategory[SemanticCategory.Lifecycle]
+    const createdTimestampSemantic = lifecycleSemantics.find((s) => s.id === SemanticType.CreatedTimestamp)
+    assert.isDefined(createdTimestampSemantic, 'CreatedTimestamp semantic should be in Lifecycle category')
+
+    // Check that Title is in Content category
+    const contentSemantics = semanticsByCategory[SemanticCategory.Content]
+    const titleSemantic = contentSemantics.find((s) => s.id === SemanticType.Title)
+    assert.isDefined(titleSemantic, 'Title semantic should be in Content category')
+
+    // Verify all semantics are categorized (total count should match)
+    const totalSemantics = Object.values(semanticsByCategory).flat().length
+    const allSemantics = Object.values(DataSemantics).length
+    assert.equal(totalSemantics, allSemantics, 'All semantics should be categorized')
+  })
+
+  test('getSemanticsByCategoryType should filter semantics by category', ({ assert }) => {
+    const identitySemantics = getSemanticsByCategoryType(SemanticCategory.Identity)
+
+    // All returned semantics should be in Identity category
+    identitySemantics.forEach((semantic) => {
+      assert.equal(semantic.category, SemanticCategory.Identity, 'All semantics should be in Identity category')
+    })
+
+    // Should include User semantic
+    const userSemantic = identitySemantics.find((s) => s.id === SemanticType.User)
+    assert.isDefined(userSemantic, 'Should include User semantic')
+
+    // Should include Password semantic
+    const passwordSemantic = identitySemantics.find((s) => s.id === SemanticType.Password)
+    assert.isDefined(passwordSemantic, 'Should include Password semantic')
+
+    // Test empty result for a category with no semantics (if any)
+    const locationSemantics = getSemanticsByCategoryType(SemanticCategory.Location)
+    assert.isArray(locationSemantics, 'Should return an array even if empty')
   })
 })