@api-client/core 0.18.13 → 0.18.14

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

@@ -42065,10 +42065,10 @@
 "@id": "#191"
 },
 {
-"@id": "#197"
+"@id": "#194"
 },
 {
-"@id": "#194"
+"@id": "#197"
 },
 {
 "@id": "#200"
@@ -43457,7 +43457,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: '5'\ndescription: 'Limited company'\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": [
 {
@@ -43478,7 +43478,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": "code: '5'\ndescription: 'Limited company'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44761,12 +44761,12 @@
 {
 "@id": "#196/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#196",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(10,0)]"
 },
 {
 "@id": "#199/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#199",
-"sourcemaps:value": "[(1,0)-(10,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#202/source-map/lexical/element_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.18.13",
+  "version": "0.18.14",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {

package/src/modeling/DomainValidation.ts

@@ -6,6 +6,75 @@ import { EntityValidation } from './validation/entity_validation.js'
 import { PropertyValidation } from './validation/property_validation.js'
 import { SemanticValidation } from './validation/semantic_validation.js'
 
+/**
+ * DomainValidation performs comprehensive validation on a data domain and its components.
+ *
+ * This class orchestrates validation across all domain elements including entities, properties,
+ * associations, and semantics. It ensures that the data domain is well-formed and follows
+ * established conventions before it can be published or used in API generation.
+ *
+ * ## Validation Scope
+ *
+ * The validation process covers:
+ * - **Entities**: Structure, naming, primary keys, and inheritance
+ * - **Properties**: Naming conventions, data types, and constraints
+ * - **Associations**: Relationships, targets, and naming
+ * - **Semantics**: Recommended patterns and best practices
+ *
+ * ## Validation Severity Levels
+ *
+ * - **Error**: Blocking issues that prevent domain publication
+ * - **Warning**: Issues that may cause problems but don't block publication
+ * - **Info**: Recommendations for best practices
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const domain = new DataDomain()
+ * // ... add entities, properties, associations
+ *
+ * const validator = new DomainValidation(domain)
+ * const report = validator.validate()
+ *
+ * if (report.canProceed) {
+ *   // Domain is valid and can be published
+ * } else {
+ *   // Handle validation errors
+ *   console.log(report.impact)
+ * }
+ * ```
+ *
+ * ## Validation Rules
+ *
+ * ### Entity Validation Rules
+ * - **Primary Key**: Each entity must have a primary key (can be inherited)
+ * - **Minimum Properties**: Entities should have properties or associations (can be inherited)
+ * - **Naming**: Entity names must follow PostgreSQL naming conventions
+ * - **Uniqueness**: Entity names must be unique within the domain
+ *
+ * ### Property Validation Rules
+ * - **Naming**: Properties must follow PostgreSQL column naming conventions
+ * - **Length**: Names must be 2-59 characters long
+ * - **Format**: Names must start with letter/underscore, contain only alphanumeric/underscore
+ * - **Reserved Words**: Names cannot be PostgreSQL reserved keywords
+ * - **Case**: Snake case is recommended (lowercase with underscores)
+ *
+ * ### Association Validation Rules
+ * - **Targets**: Associations must have at least one target entity
+ * - **Target Existence**: Target entities must exist in the domain
+ * - **Naming**: Same rules as properties
+ *
+ * ### Semantic Validation Rules
+ * - **User Entity**: Recommended to have at least one entity with User semantic
+ * - **Timestamps**: Recommended to have CreatedTimestamp and UpdatedTimestamp properties
+ * - **Soft Delete**: Recommended to have soft delete capability for entities
+ * - **Data Types**: Semantic-specific data type validation
+ *
+ * @see {@link EntityValidation} for detailed entity validation rules
+ * @see {@link PropertyValidation} for detailed property validation rules
+ * @see {@link AssociationValidation} for detailed association validation rules
+ * @see {@link SemanticValidation} for detailed semantic validation rules
+ */
 export class DomainValidation {
   private root: DataDomain
 
@@ -13,6 +82,15 @@ export class DomainValidation {
     this.root = root
   }
 
+  /**
+   * Performs comprehensive validation on the entire data domain.
+   *
+   * This method validates all entities, properties, associations, and semantics
+   * in the domain. It returns a detailed report of all validation issues found,
+   * categorized by severity level.
+   *
+   * @returns A comprehensive validation report with all issues found
+   */
   validate(): DomainImpactReport {
     const result: DomainImpactReport = {
       key: '',

package/src/modeling/validation/entity_validation.ts

@@ -17,7 +17,8 @@ export class EntityValidation {
   /**
    * Performs all the validation rules on the entity.
    * If you are interested in a specific rule, use the specific method.
-   * @param target The target entity to validate. Can be a string with the entity key or a DomainEntity object.
+   * @param target The target entity to validate. Can be a string with
+   *               the entity key or a DomainEntity object.
    */
   validate(target: string | DomainEntity): DomainValidation[] {
     const results: DomainValidation[] = []
@@ -41,21 +42,20 @@ export class EntityValidation {
       })
       return results
     }
-    const primary = this.validatePrimaryKey(entity)
-    results.push(...primary)
-    const minimum = this.minimumRequiredProperties(entity)
-    results.push(...minimum)
+    const primaryKey = this.validatePrimaryKey(entity)
+    results.push(...primaryKey)
+    const minimumProperties = this.minimumRequiredProperties(entity)
+    results.push(...minimumProperties)
     const name = this.validateName(entity)
     results.push(...name)
-    const uniqueName = this.uniqueName(entity)
-    results.push(...uniqueName)
+    const unique = this.uniqueName(entity)
+    results.push(...unique)
     return results
   }
 
   /**
-   * Validates the entity against the primary key validation rules.
+   * Validates the entity primary key.
    * @param entity The entity to validate
-   * @returns The list of validation messages.
    */
   validatePrimaryKey(entity: DomainEntity): DomainValidation[] {
     const results: DomainValidation[] = []
@@ -76,13 +76,62 @@ export class EntityValidation {
     return results
   }
 
+  /**
+   * Checks if an entity has properties through its entire inheritance chain.
+   * This includes direct properties and properties inherited from any level of parent entities.
+   * @param entity The entity to check
+   * @returns True if the entity has properties either directly or through inheritance
+   */
+  private hasPropertiesInherited(entity: DomainEntity): boolean {
+    // Check direct properties first
+    if (entity.hasProperties()) {
+      return true
+    }
+
+    // Check all parents recursively
+    for (const parent of entity.listParents()) {
+      if (this.hasPropertiesInherited(parent)) {
+        return true
+      }
+    }
+
+    return false
+  }
+
+  /**
+   * Checks if an entity has associations through its entire inheritance chain.
+   * This includes direct associations and associations inherited from any level of parent entities.
+   * @param entity The entity to check
+   * @returns True if the entity has associations either directly or through inheritance
+   */
+  private hasAssociationsInherited(entity: DomainEntity): boolean {
+    // Check direct associations first
+    if (entity.hasAssociations()) {
+      return true
+    }
+
+    // Check all parents recursively
+    for (const parent of entity.listParents()) {
+      if (this.hasAssociationsInherited(parent)) {
+        return true
+      }
+    }
+
+    return false
+  }
+
   /**
    * Checks if the entity has the minimum required properties.
    * @param entity The entity to validate
    */
   minimumRequiredProperties(entity: DomainEntity): DomainValidation[] {
     const results: DomainValidation[] = []
-    if (!entity.hasProperties() && !entity.hasAssociations()) {
+
+    // Check if entity has properties or associations through entire inheritance chain
+    const hasProperties = this.hasPropertiesInherited(entity)
+    const hasAssociations = this.hasAssociationsInherited(entity)
+
+    if (!hasProperties && !hasAssociations) {
       const message = `The "${entity.info.getLabel()}" entity has no properties. It will be ignored.`
       const help = `Entities that have no properties are ignored in the data domain. No schema will be generated for it.`
       results.push({

package/tests/unit/modeling/validation/entity_validation.spec.ts

@@ -1,3 +1,4 @@
+/* eslint-disable max-len */
 import { test } from '@japa/runner'
 import { DataDomain, EntityValidation } from '../../../../src/index.js'
 
@@ -78,6 +79,100 @@ test.group('EntityValidation', (group) => {
     assert.lengthOf(results, 0)
   })
 
+  test('minimumRequiredProperties() should return no errors when the entity inherits properties from parent', ({
+    assert,
+  }) => {
+    const model = domain.addModel({ key: 'model' })
+    const parent = model.addEntity({ key: 'parent', info: { name: 'Parent' } })
+    parent.addProperty({ key: 'name', type: 'string' })
+    const entity = model.addEntity({ key: 'entity', info: { name: 'Entity' } })
+    entity.addParent(parent.key)
+    const results = validation.minimumRequiredProperties(entity)
+    assert.lengthOf(results, 0)
+  })
+
+  test('minimumRequiredProperties() should return no errors when the entity inherits associations from parent', ({
+    assert,
+  }) => {
+    const model = domain.addModel({ key: 'model' })
+    const target = model.addEntity({ key: 'target', info: { name: 'Target' } })
+    const parent = model.addEntity({ key: 'parent', info: { name: 'Parent' } })
+    parent.addAssociation({ key: target.key })
+    const entity = model.addEntity({ key: 'entity', info: { name: 'Entity' } })
+    entity.addParent(parent.key)
+    const results = validation.minimumRequiredProperties(entity)
+    assert.lengthOf(results, 0)
+  })
+
+  test('minimumRequiredProperties() should return no errors when the entity inherits properties from grandparent', ({
+    assert,
+  }) => {
+    const model = domain.addModel({ key: 'model' })
+    const grandparent = model.addEntity({
+      key: 'grandparent',
+      info: { name: 'Grandparent' },
+    })
+    grandparent.addProperty({ key: 'name', type: 'string' })
+    const parent = model.addEntity({ key: 'parent', info: { name: 'Parent' } })
+    parent.addParent(grandparent.key)
+    const entity = model.addEntity({ key: 'entity', info: { name: 'Entity' } })
+    entity.addParent(parent.key)
+    const results = validation.minimumRequiredProperties(entity)
+    assert.lengthOf(results, 0)
+  })
+
+  test('minimumRequiredProperties() should return no errors when the entity inherits associations from grandparent', ({
+    assert,
+  }) => {
+    const model = domain.addModel({ key: 'model' })
+    const target = model.addEntity({ key: 'target', info: { name: 'Target' } })
+    const grandparent = model.addEntity({
+      key: 'grandparent',
+      info: { name: 'Grandparent' },
+    })
+    grandparent.addAssociation({ key: target.key })
+    const parent = model.addEntity({ key: 'parent', info: { name: 'Parent' } })
+    parent.addParent(grandparent.key)
+    const entity = model.addEntity({ key: 'entity', info: { name: 'Entity' } })
+    entity.addParent(parent.key)
+    const results = validation.minimumRequiredProperties(entity)
+    assert.lengthOf(results, 0)
+  })
+
+  test('minimumRequiredProperties() should return no errors when the entity inherits properties from great-grandparent', ({
+    assert,
+  }) => {
+    const model = domain.addModel({ key: 'model' })
+    const greatGrandparent = model.addEntity({
+      key: 'great_grandparent',
+      info: { name: 'GreatGrandparent' },
+    })
+    greatGrandparent.addProperty({ key: 'name', type: 'string' })
+    const grandparent = model.addEntity({ key: 'grandparent', info: { name: 'Grandparent' } })
+    grandparent.addParent(greatGrandparent.key)
+    const parent = model.addEntity({ key: 'parent', info: { name: 'Parent' } })
+    parent.addParent(grandparent.key)
+    const entity = model.addEntity({ key: 'entity', info: { name: 'Entity' } })
+    entity.addParent(parent.key)
+    const results = validation.minimumRequiredProperties(entity)
+    assert.lengthOf(results, 0)
+  })
+
+  test('minimumRequiredProperties() should return warning when the entity has no properties in entire inheritance chain', ({
+    assert,
+  }) => {
+    const model = domain.addModel({ key: 'model' })
+    const grandparent = model.addEntity({ key: 'grandparent', info: { name: 'Grandparent' } })
+    const parent = model.addEntity({ key: 'parent', info: { name: 'Parent' } })
+    parent.addParent(grandparent.key)
+    const entity = model.addEntity({ key: 'entity', info: { name: 'Entity' } })
+    entity.addParent(parent.key)
+    const results = validation.minimumRequiredProperties(entity)
+    assert.lengthOf(results, 1)
+    assert.equal(results[0].severity, 'warning')
+    assert.equal(results[0].rule, 'required')
+  })
+
   test('validateName() should return an error when the entity has no name', ({ assert }) => {
     const model = domain.addModel({ key: 'model' })
     const entity = model.addEntity({ key: 'entity', info: {} })