@api-client/core 0.18.13 → 0.18.15

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

@@ -42065,10 +42065,10 @@
 "@id": "#191"
 },
 {
-"@id": "#197"
+"@id": "#194"
 },
 {
-"@id": "#194"
+"@id": "#197"
 },
 {
 "@id": "#200"
@@ -42813,13 +42813,13 @@
 "@id": "#210"
 },
 {
-"@id": "#213"
+"@id": "#219"
 },
 {
-"@id": "#216"
+"@id": "#213"
 },
 {
-"@id": "#219"
+"@id": "#216"
 }
 ],
 "doc:root": false,
@@ -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": [
 {
@@ -44253,7 +44253,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '21'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)21 302099'\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": [
 {
@@ -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": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '21'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)21 302099'\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",
@@ -45121,17 +45121,17 @@
 {
 "@id": "#215/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#215",
-"sourcemaps:value": "[(1,0)-(6,0)]"
+"sourcemaps:value": "[(1,0)-(7,0)]"
 },
 {
 "@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)-(6,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.18.13",
+  "version": "0.18.15",
   "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/importers/FilteringJsonSchemaImporter.ts

@@ -0,0 +1,324 @@
+import type { JSONSchema7 } from 'json-schema'
+import type { JsonImportReport, InMemorySchema } from './JsonSchemaImporter.js'
+import { JsonSchemaImporter } from './JsonSchemaImporter.js'
+import {
+  SchemaFilteringStrategy,
+  type SchemaFilteringOptions,
+  FILTERING_STRATEGIES,
+} from './SchemaFilteringStrategy.js'
+import type { DataDomain } from '../DataDomain.js'
+import type { DomainEntity } from '../DomainEntity.js'
+import type { ImportMessage } from './JsonSchemaImporter.js'
+
+/**
+ * Extended JsonSchemaImporter that supports filtering out non-structural schemas.
+ * This version can eliminate schemas that don't contribute meaningful structure
+ * to the data model, such as empty objects or conceptual marker types.
+ */
+export class FilteringJsonSchemaImporter extends JsonSchemaImporter {
+  private filteringStrategy: SchemaFilteringStrategy
+
+  constructor(domain: DataDomain, filteringOptions: SchemaFilteringOptions = {}) {
+    super(domain)
+    this.filteringStrategy = new SchemaFilteringStrategy(filteringOptions)
+  }
+
+  /**
+   * Creates an importer with a predefined filtering strategy.
+   */
+  static withStrategy(
+    domain: DataDomain,
+    strategyName: keyof typeof FILTERING_STRATEGIES
+  ): FilteringJsonSchemaImporter {
+    const strategy = FILTERING_STRATEGIES[strategyName]
+    // Access private options through a public method (would need to be added to SchemaFilteringStrategy)
+    const options = strategy['options'] as SchemaFilteringOptions
+    return new FilteringJsonSchemaImporter(domain, options)
+  }
+
+  /**
+   * Creates an importer optimized for API development.
+   * Excludes schemas that don't contribute to API structure.
+   */
+  static forApiModeling(domain: DataDomain): FilteringJsonSchemaImporter {
+    return new FilteringJsonSchemaImporter(domain, {
+      excludeEmptyObjects: true,
+      excludeConceptualMarkers: true,
+      excludePatterns: [
+        /.*Enumeration$/, // Exclude *Enumeration schemas
+        /.*Type$/, // Exclude conceptual *Type schemas that are just markers
+      ],
+    })
+  }
+
+  /**
+   * Creates an importer optimized for database schema generation.
+   * Very strict filtering - only includes schemas with concrete properties.
+   */
+  static forDatabaseModeling(domain: DataDomain): FilteringJsonSchemaImporter {
+    return new FilteringJsonSchemaImporter(domain, {
+      excludeEmptyObjects: true,
+      excludeConceptualMarkers: true,
+      customExclusionFilter: (schema: JSONSchema7) => {
+        // For database modeling, exclude anything that doesn't have properties or clear structure
+        return (
+          schema.type === 'object' &&
+          !schema.properties &&
+          !schema.additionalProperties &&
+          !schema.allOf?.some(
+            (subSchema) => typeof subSchema === 'object' && 'properties' in subSchema && subSchema.properties
+          )
+        )
+      },
+    })
+  }
+
+  /**
+   * Override the base import method to apply filtering.
+   */
+  override async import(schemas: InMemorySchema[], modelName: string): Promise<JsonImportReport> {
+    // Apply pre-filtering to the schemas before import
+    const filteredSchemas = this.preFilterSchemas(schemas)
+
+    // Get the raw import result with filtered schemas
+    const rawResult = await super.import(filteredSchemas.schemas, modelName)
+
+    // Apply post-filtering to clean up any remaining issues
+    const finalReport = this.postFilterReport(rawResult, filteredSchemas.messages)
+
+    return finalReport
+  }
+
+  /**
+   * Pre-filters schemas before they are processed by the base importer.
+   */
+  private preFilterSchemas(schemas: InMemorySchema[]): {
+    schemas: InMemorySchema[]
+    messages: ImportMessage[]
+  } {
+    const filteredSchemas: InMemorySchema[] = []
+    const messages: ImportMessage[] = []
+
+    for (const schema of schemas) {
+      const schemaId = schema.contents.$id || schema.path
+
+      if (this.filteringStrategy.shouldExcludeSchema(schema.contents, schemaId)) {
+        const reason = this.filteringStrategy.getExclusionReason(schema.contents, schemaId)
+        messages.push({
+          level: 'info',
+          message: `Pre-filtered schema '${schemaId}': ${reason}`,
+          location: schema.path,
+        })
+      } else {
+        filteredSchemas.push(schema)
+      }
+    }
+
+    if (messages.length > 0) {
+      messages.push({
+        level: 'info',
+        message: `Pre-filtering removed ${messages.length} non-structural schema(s)`,
+      })
+    }
+
+    return { schemas: filteredSchemas, messages }
+  }
+
+  /**
+   * Post-processes the import report to clean up any remaining filtered entities.
+   */
+  private postFilterReport(report: JsonImportReport, preFilterMessages: ImportMessage[]): JsonImportReport {
+    const { model, messages } = report
+    const allMessages = [...preFilterMessages, ...messages]
+    let removedCount = 0
+
+    // Get entities as array for easier processing
+    const entities = Array.from(model.listEntities())
+    const entitiesToRemove: string[] = []
+
+    // Check each entity to see if it should be filtered out
+    for (const entity of entities) {
+      const shouldFilter = this.shouldFilterEntity(entity)
+
+      if (shouldFilter) {
+        entitiesToRemove.push(entity.key)
+        const reason = this.getEntityFilterReason(entity)
+        allMessages.push({
+          level: 'info',
+          message: `Post-filtered entity '${entity.info.name}': ${reason}`,
+          location: entity.key,
+        })
+        removedCount++
+      }
+    }
+
+    // Remove the filtered entities
+    for (const entityKey of entitiesToRemove) {
+      try {
+        model.removeEntity(entityKey)
+      } catch (error) {
+        allMessages.push({
+          level: 'warning',
+          message: `Failed to remove entity '${entityKey}': ${error}`,
+          location: entityKey,
+        })
+      }
+    }
+
+    // Clean up orphaned associations
+    this.cleanupOrphanedAssociations(entities, entitiesToRemove, allMessages)
+
+    if (removedCount > 0) {
+      allMessages.push({
+        level: 'info',
+        message: `Post-filtering removed ${removedCount} additional non-structural entity/entities`,
+      })
+    }
+
+    return {
+      model,
+      messages: allMessages,
+    }
+  }
+
+  /**
+   * Determines if an entity should be filtered out based on its characteristics.
+   */
+  private shouldFilterEntity(entity: DomainEntity): boolean {
+    // Check if entity has no properties and no meaningful associations
+    const hasProperties = Array.from(entity.listProperties()).length > 0
+    const hasAssociations = Array.from(entity.listAssociations()).length > 0
+
+    // If it has neither properties nor associations, it's likely a conceptual marker
+    if (!hasProperties && !hasAssociations) {
+      return this.filteringStrategy.shouldExcludeSchema(
+        {
+          type: 'object',
+          title: entity.info.name,
+          description: entity.info.description,
+        } as JSONSchema7,
+        entity.info.name
+      )
+    }
+
+    return false
+  }
+
+  /**
+   * Gets a human-readable reason for filtering an entity.
+   */
+  private getEntityFilterReason(entity: DomainEntity): string {
+    const hasProperties = Array.from(entity.listProperties()).length > 0
+    const hasAssociations = Array.from(entity.listAssociations()).length > 0
+
+    if (!hasProperties && !hasAssociations) {
+      return 'Entity has no properties or associations (likely a conceptual marker)'
+    }
+
+    return 'Entity matches exclusion pattern'
+  }
+
+  /**
+   * Removes associations that reference entities that were filtered out.
+   */
+  private cleanupOrphanedAssociations(
+    entities: DomainEntity[],
+    removedEntityKeys: string[],
+    messages: ImportMessage[]
+  ): void {
+    for (const entity of entities) {
+      const associationsToRemove: string[] = []
+
+      for (const association of entity.listAssociations()) {
+        const hasOrphanedTargets = association.targets?.some((target) => removedEntityKeys.includes(target.key))
+
+        if (hasOrphanedTargets) {
+          associationsToRemove.push(association.key)
+          messages.push({
+            level: 'info',
+            message: `Removed association '${association.info.name}' from '${entity.info.name}' due to filtered target entity`,
+            location: `${entity.key}.${association.key}`,
+          })
+        }
+      }
+
+      for (const associationKey of associationsToRemove) {
+        try {
+          entity.removeAssociation(associationKey)
+        } catch (error) {
+          messages.push({
+            level: 'warning',
+            message: `Failed to remove association '${associationKey}' from '${entity.info.name}': ${error}`,
+            location: `${entity.key}.${associationKey}`,
+          })
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Utility functions for working with filtered imports.
+ */
+export const SchemaFilteringUtils = {
+  /**
+   * Analyzes a JSON schema to determine if it would be filtered by the given strategy.
+   */
+  wouldBeFiltered(schema: JSONSchema7, strategy: SchemaFilteringStrategy): boolean {
+    return strategy.shouldExcludeSchema(schema)
+  },
+
+  /**
+   * Gets statistics about what would be filtered from a set of schemas.
+   */
+  getFilteringStats(
+    schemas: { id: string; schema: JSONSchema7 }[],
+    strategy: SchemaFilteringStrategy
+  ): {
+    total: number
+    filtered: number
+    remaining: number
+    filteredSchemas: { id: string; reason: string }[]
+  } {
+    const filteredSchemas: { id: string; reason: string }[] = []
+
+    for (const { id, schema } of schemas) {
+      if (strategy.shouldExcludeSchema(schema, id)) {
+        filteredSchemas.push({
+          id,
+          reason: strategy.getExclusionReason(schema, id),
+        })
+      }
+    }
+
+    return {
+      total: schemas.length,
+      filtered: filteredSchemas.length,
+      remaining: schemas.length - filteredSchemas.length,
+      filteredSchemas,
+    }
+  },
+
+  /**
+   * Creates a report showing what would be filtered from a schema collection.
+   */
+  createFilteringReport(schemas: { id: string; schema: JSONSchema7 }[], strategy: SchemaFilteringStrategy): string {
+    const stats = this.getFilteringStats(schemas, strategy)
+
+    let report = `Schema Filtering Report\n`
+    report += `======================\n\n`
+    report += `Total schemas: ${stats.total}\n`
+    report += `Would be filtered: ${stats.filtered}\n`
+    report += `Would remain: ${stats.remaining}\n\n`
+
+    if (stats.filteredSchemas.length > 0) {
+      report += `Schemas that would be filtered:\n`
+      report += `-------------------------------\n`
+      for (const { id, reason } of stats.filteredSchemas) {
+        report += `• ${id}: ${reason}\n`
+      }
+    }
+
+    return report
+  },
+}