@api-client/core 0.18.12 → 0.18.14

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.12",
+  "version": "0.18.14",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {
@@ -97,6 +97,7 @@
     "dompurify": "^3.2.6",
     "jsdom": "^26.1.0",
     "nanoid": "^5.1.5",
+    "tslog": "^4.9.3",
     "ws": "^8.12.0",
     "xpath": "^0.0.34"
   },
@@ -136,7 +137,6 @@
     "globals": "^16.0.0",
     "husky": "^9.0.11",
     "lint-staged": "^16.0.0",
-    "nock": "^14.0.1",
     "oauth2-mock-server": "^8.0.0",
     "prettier": "^3.5.1",
     "schema-org-json-schemas": "^2.1.4",

package/src/lib/logging/DefaultLogger.ts

@@ -1,20 +1,52 @@
 /* eslint-disable no-console */
 import { Logger } from './Logger.js'
 
+export enum LogLevel {
+  Silly,
+  Debug,
+  Verbose,
+  Info,
+  Warn,
+  Error,
+  Silent,
+}
+
+export interface LoggerConfig {
+  level?: LogLevel
+}
+
 export class DefaultLogger extends Logger {
+  level: LogLevel = LogLevel.Info
+
+  constructor(config: LoggerConfig = {}) {
+    super()
+    if (typeof config.level !== 'undefined') {
+      this.level = config.level
+    }
+  }
+
   warn(...args: unknown[]): void {
+    if (this.level > LogLevel.Warn) return
     console.warn(...args)
   }
+
   info(...args: unknown[]): void {
+    if (this.level > LogLevel.Info) return
     console.info(...args)
   }
+
   error(...args: unknown[]): void {
+    if (this.level > LogLevel.Error) return
     console.error(...args)
   }
+
   log(...args: unknown[]): void {
+    if (this.level > LogLevel.Debug) return
     console.log(...args)
   }
+
   debug(...args: unknown[]): void {
+    if (this.level > LogLevel.Debug) return
     console.debug(...args)
   }
 }

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/src/models/ClientCertificate.ts

@@ -37,7 +37,7 @@ export interface ICertificateData {
 export interface ICertificate {
   kind: typeof Kind
   /**
-   * The data store key to refer.
+   * The data store key to refer under which this certificate is stored.
    */
   key: string
   /**

package/src/models/RequestConfig.ts

@@ -56,7 +56,7 @@ export interface IRequestBaseConfig {
    */
   proxyPassword?: string
   /**
-   * THe type of proxy authentication to use.
+   * The type of proxy authentication to use.
    */
   proxyAuthorization?: 'Basic'
   /**

package/src/models/SerializableError.ts

@@ -23,7 +23,7 @@ export class SerializableError {
     return this.stackValue
   }
 
-  readonly name = 'SerializableError'
+  readonly name: string = 'SerializableError'
 
   constructor(message?: string | Error, options: IErrorOptions | number | string = {}) {
     if (typeof message === 'string') {

package/src/proxy/RequestProxy.ts

@@ -3,12 +3,12 @@ import { IRequestAuthorization } from '../models/RequestAuthorization.js'
 import { IRequestConfig } from '../models/RequestConfig.js'
 import Proxy, { IProxyResult } from './Proxy.js'
 import { HttpCertificate } from '../models/ClientCertificate.js'
-import { DummyLogger } from '../lib/logging/DummyLogger.js'
 import { HttpRequestRunner } from '../runtime/http-runner/HttpRequestRunner.js'
 import { IRequestLog } from '../models/RequestLog.js'
 import { IHttpFlow } from '../models/http-flows/HttpFlows.js'
 import { IHttpAssertion } from '../models/http-flows/HttpAssertion.js'
 import { Exception } from '../exceptions/exception.js'
+import { createLogger } from '../lib/logging/index.js'
 
 export interface IRequestProxyInit {
   kind: typeof HttpRequestKind
@@ -78,7 +78,7 @@ export default class RequestProxy extends Proxy {
     const { request, authorization, certificate, config = {}, variables = {}, flows, assertions } = data
     const factory = new HttpRequestRunner()
     factory.variables = variables
-    factory.logger = new DummyLogger()
+    factory.logger = createLogger()
     factory.config = { ...config, enabled: true } as IRequestConfig
     if (Array.isArray(authorization) && authorization.length) {
       factory.authorization = authorization