@api-client/core 0.12.1 → 0.12.2

package/src/modeling/validation/association_validation.ts

@@ -0,0 +1,109 @@
+import { DomainAssociationKind } from '../../models/kinds.js'
+import type { DataDomain } from '../DataDomain.js'
+import type { DomainAssociation } from '../DomainAssociation.js'
+import type { DomainEntity } from '../DomainEntity.js'
+import { type DomainValidation, validatePropertyName } from './rules.js'
+
+/**
+ * AssociationValidation is a class that performs validation on associations in a data domain.
+ * Note that an association in most cases is a property of an entity.
+ */
+export class AssociationValidation {
+  constructor(protected domain: DataDomain) {}
+  /**
+   * Performs all the validation rules on the association.
+   * If you are interested in a specific rule, use the specific method.
+   * @param target The target association to validate. Can be a string with
+   *               the association key or a DomainAssociation object.
+   */
+  validate(target: string | DomainAssociation): DomainValidation[] {
+    const results: DomainValidation[] = []
+    let association: DomainAssociation | undefined
+    if (typeof target === 'string') {
+      association = this.domain.findAssociation(target)
+    } else {
+      association = target
+    }
+    if (!association) {
+      const message = `The "${target}" association does not exist.`
+      const help = `The association must be defined in the domain.`
+      results.push({
+        field: '*',
+        rule: 'exists',
+        message,
+        help,
+        key: target as string,
+        kind: DomainAssociationKind,
+        severity: 'error',
+      })
+      return results
+    }
+    const name = this.validateName(association)
+    results.push(...name)
+    const targets = this.validateTargets(association)
+    results.push(...targets)
+    return results
+  }
+
+  /**
+   * Validates the association name.
+   *
+   * @remarks
+   * - A association must have a name defined.
+   * - The name has to follow the same rules as the names in a PostgreSQL database.
+   *   - Column names can only contain letters (a-z, A-Z), numbers (0-9), and underscores (_).
+   *   - The name must start with a letter (a-z, A-Z) or an underscore (_).
+   *   - PostgreSQL limits column names to a maximum of 59 characters.
+   *   - (our rule) Column names are case insensitive.
+   *   - (recommendation) Column names should be in lower case.
+   * @param association The association to validate
+   */
+  validateName(association: DomainAssociation): DomainValidation[] {
+    return validatePropertyName(association)
+  }
+
+  /**
+   * Validates the association targets.
+   * @param association The association to validate
+   */
+  validateTargets(association: DomainAssociation): DomainValidation[] {
+    const results: DomainValidation[] = []
+    const label = association.info.getLabel()
+    const parentEntity = association.getParentInstance() as DomainEntity
+    if (!association.targets.length) {
+      const message = `The "${label}" association has no target.`
+      const help = `An association must have at least one target.`
+      results.push({
+        field: 'targets',
+        rule: 'required',
+        message,
+        help,
+        severity: 'error',
+        key: association.key,
+        kind: association.kind,
+        parent: parentEntity.key,
+      })
+      return results
+    }
+    for (const target of association.targets) {
+      const entity = target.domain
+        ? this.domain.findForeignEntity(target.key, target.domain)
+        : this.domain.findEntity(target.key)
+      if (!entity) {
+        const message = `The "${label}" association has an invalid target "${target.key}".`
+        const help = `The target must be defined in the domain.`
+        results.push({
+          field: 'targets',
+          rule: 'exists',
+          message,
+          help,
+          severity: 'error',
+          key: association.key,
+          kind: association.kind,
+          parent: parentEntity.key,
+        })
+      }
+    }
+    return results
+  }
+}

package/src/modeling/validation/entity_validation.ts

@@ -0,0 +1,246 @@
+import { DomainEntityKind } from '../../models/kinds.js'
+import type { DataDomain } from '../DataDomain.js'
+import type { DomainEntity } from '../DomainEntity.js'
+import { ReservedKeywords } from './postgresql.js'
+import type { DomainValidation } from './rules.js'
+
+/**
+ * EntityValidation is a class that performs validation on entities in a data domain.
+ *
+ * @remarks
+ * - We do not need to check for parent uniqueness here, because in the graph there can only be one edge
+ *   between two nodes. Parent relationships are described by an edge in the graph.
+ */
+export class EntityValidation {
+  constructor(protected domain: DataDomain) {}
+
+  /**
+   * 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.
+   */
+  validate(target: string | DomainEntity): DomainValidation[] {
+    const results: DomainValidation[] = []
+    let entity: DomainEntity | undefined
+    if (typeof target === 'string') {
+      entity = this.domain.findEntity(target)
+    } else {
+      entity = target
+    }
+    if (!entity) {
+      const message = `The "${target}" entity does not exist.`
+      const help = `The entity must be defined in the domain.`
+      results.push({
+        field: '*',
+        rule: 'exists',
+        message,
+        help,
+        key: target as string,
+        kind: DomainEntityKind,
+        severity: 'error',
+      })
+      return results
+    }
+    const primary = this.validatePrimaryKey(entity)
+    results.push(...primary)
+    const minimum = this.minimumRequiredProperties(entity)
+    results.push(...minimum)
+    const name = this.validateName(entity)
+    results.push(...name)
+    const uniqueName = this.uniqueName(entity)
+    results.push(...uniqueName)
+    return results
+  }
+
+  /**
+   * Validates the entity against the primary key validation rules.
+   * @param entity The entity to validate
+   * @returns The list of validation messages.
+   */
+  validatePrimaryKey(entity: DomainEntity): DomainValidation[] {
+    const results: DomainValidation[] = []
+    const primary = entity.primaryKey()
+    if (!primary) {
+      const message = `The "${entity.info.getLabel()}" entity has no identifier.`
+      const help = `An entity that can exists by itself must have identifier defined.`
+      results.push({
+        field: 'properties',
+        rule: 'primary_key',
+        message,
+        help,
+        severity: 'error',
+        key: entity.key,
+        kind: entity.kind,
+      })
+    }
+    return results
+  }
+
+  /**
+   * 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()) {
+      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({
+        field: 'properties',
+        rule: 'required',
+        message,
+        help,
+        severity: 'warning',
+        key: entity.key,
+        kind: entity.kind,
+      })
+    }
+    return results
+  }
+
+  /**
+   * Validates the entity name.
+   *
+   * @remarks
+   * - An entity must have a name defined.
+   * - The name has to follow the same rules as the names in a PostgreSQL database.
+   *   - Table names must start with a letter (a-z) or underscore (_).
+   *   - Subsequent characters can be letters, digits (0-9), or underscores (_).
+   *   - Names are case-insensitive.
+   *   - The maximum length of a table name is 31 characters
+   *   - Should be snake case (it's a convention, not an error).
+   *   - Should not be a reserved word (for example: "IN", "SELECT", "FROM", etc.).
+   * @param entity The entity to validate
+   */
+  validateName(entity: DomainEntity): DomainValidation[] {
+    const results: DomainValidation[] = []
+    const label = entity.info.getLabel()
+    if (!entity.info.name) {
+      const message = `The "${label}" entity has no name.`
+      const help = `An entity must have a name.`
+      results.push({
+        field: 'name',
+        rule: 'required',
+        message,
+        help,
+        severity: 'error',
+        key: entity.key,
+        kind: entity.kind,
+      })
+      return results
+    }
+
+    const name = entity.info.name
+    if (name.length < 3) {
+      const message = `The "${label}" entity name is too short.`
+      const help = `The name must be at least 3 characters long.`
+      results.push({
+        field: 'name',
+        rule: 'length',
+        message,
+        help,
+        severity: 'error',
+        key: entity.key,
+        kind: entity.kind,
+      })
+    }
+    if (name.length > 31) {
+      const message = `The "${label}" entity name is too long.`
+      const help = `The name must be at most 31 characters long.`
+      results.push({
+        field: 'name',
+        rule: 'length',
+        message,
+        help,
+        severity: 'error',
+        key: entity.key,
+        kind: entity.kind,
+      })
+    }
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+      const message = `The "${label}" entity name is invalid.`
+      const help = `The name must start with a letter (a-z) or underscore (_). Subsequent characters can be letters, digits (0-9), or underscores (_).`
+      results.push({
+        field: 'name',
+        rule: 'format',
+        message,
+        help,
+        severity: 'error',
+        key: entity.key,
+        kind: entity.kind,
+      })
+    }
+    if (/^[A-Z]/.test(name)) {
+      const message = `The "${label}" entity name is not in snake case.`
+      const help = `The name should be in snake case (lowercase letters and underscores).`
+      results.push({
+        field: 'name',
+        rule: 'snake_case',
+        message,
+        help,
+        severity: 'info',
+        key: entity.key,
+        kind: entity.kind,
+      })
+    }
+    if (ReservedKeywords.has(name.toUpperCase())) {
+      const message = `The "${label}" entity name is a reserved keyword.`
+      const help = `The name should not be a reserved keyword.`
+      results.push({
+        field: 'name',
+        rule: 'reserved',
+        message,
+        help,
+        severity: 'error',
+        key: entity.key,
+        kind: entity.kind,
+      })
+    }
+    return results
+  }
+
+  /**
+   * Checks if the entity name is unique in the data domain.
+   * @param entity The entity to validate
+   */
+  uniqueName(entity: DomainEntity): DomainValidation[] {
+    const results: DomainValidation[] = []
+    const name = entity.info.name?.toLowerCase()
+    if (!name) {
+      return results
+    }
+    // We need to check the unique names in all entities, including foreign ones.
+    for (const other of this.domain.listEntities()) {
+      if (other.info.name?.toLowerCase() === name && other.key !== entity.key) {
+        const message = `The "${name}" entity name is already used in the data domain.`
+        const help = `The name must be unique. This includes references to other data domains.`
+        results.push({
+          field: 'name',
+          rule: 'unique',
+          message,
+          help,
+          severity: 'error',
+          key: other.key,
+          kind: other.kind,
+        })
+      }
+    }
+    for (const other of this.domain.listForeignEntities()) {
+      if (other.info.name?.toLowerCase() === name && other.key !== entity.key) {
+        const message = `The "${name}" entity name is already used in the foreign data domain.`
+        const help = `The name must be unique. This includes references to other data domains.`
+        results.push({
+          field: 'name',
+          rule: 'unique',
+          message,
+          help,
+          severity: 'error',
+          key: other.key,
+          kind: other.kind,
+          parent: other.domain.key,
+        })
+      }
+    }
+    return results
+  }
+}

package/src/modeling/validation/postgresql.ts

@@ -0,0 +1,57 @@
+export const ReservedKeywords = new Set([
+  'IN',
+  'EXISTS',
+  'SELECT',
+  'FROM',
+  'WHERE',
+  'AND',
+  'OR',
+  'NOT',
+  'NULL',
+  'TRUE',
+  'FALSE',
+  'BETWEEN',
+  'LIKE',
+  'INTO',
+  'JOIN',
+  'INNER JOIN',
+  'LEFT JOIN',
+  'RIGHT JOIN',
+  'FULL JOIN',
+  'CROSS JOIN',
+  'UNION',
+  'INTERSECT',
+  'EXCEPT',
+  'ORDER BY',
+  'GROUP BY',
+  'HAVING',
+  'DISTINCT',
+  'LIMIT',
+  'OFFSET',
+  'INSERT',
+  'UPDATE',
+  'DELETE',
+  'CREATE',
+  'ALTER',
+  'DROP',
+  'TRUNCATE',
+  'RENAME',
+  'GRANT',
+  'REVOKE',
+  'COMMIT',
+  'ROLLBACK',
+  'SAVEPOINT',
+  'TRANSACTION',
+  'BEGIN',
+  'END',
+  'CASE',
+  'WHEN',
+  'THEN',
+  'ELSE',
+  'END CASE',
+  'EXCEPTION',
+  'RAISE',
+  'RETURN',
+  'FUNCTION',
+  'PROCEDURE',
+])

package/src/modeling/validation/property_validation.ts

@@ -0,0 +1,58 @@
+import { DomainPropertyKind } from '../../models/kinds.js'
+import type { DataDomain } from '../DataDomain.js'
+import type { DomainProperty } from '../DomainProperty.js'
+import { type DomainValidation, validatePropertyName } from './rules.js'
+
+export class PropertyValidation {
+  constructor(protected domain: DataDomain) {}
+
+  /**
+   * Performs all the validation rules on the property.
+   * If you are interested in a specific rule, use the specific method.
+   * @param target The target property to validate. Can be a string with
+   *               the property key or a DomainProperty object.
+   */
+  validate(target: string | DomainProperty): DomainValidation[] {
+    const results: DomainValidation[] = []
+    let property: DomainProperty | undefined
+    if (typeof target === 'string') {
+      property = this.domain.findProperty(target)
+    } else {
+      property = target
+    }
+    if (!property) {
+      const message = `The "${target}" property does not exist.`
+      const help = `The property must be defined in the domain.`
+      results.push({
+        field: '*',
+        rule: 'exists',
+        message,
+        help,
+        key: target as string,
+        kind: DomainPropertyKind,
+        severity: 'error',
+      })
+      return results
+    }
+    const name = this.validateName(property)
+    results.push(...name)
+    return results
+  }
+
+  /**
+   * Validates the property name.
+   *
+   * @remarks
+   * - A property must have a name defined.
+   * - The name has to follow the same rules as the names in a PostgreSQL database.
+   *   - Column names can only contain letters (a-z, A-Z), numbers (0-9), and underscores (_).
+   *   - The name must start with a letter (a-z, A-Z) or an underscore (_).
+   *   - PostgreSQL limits column names to a maximum of 59 characters.
+   *   - (our rule) Column names are case insensitive.
+   *   - (recommendation) Column names should be in lower case.
+   * @param property The property to validate
+   */
+  validateName(property: DomainProperty): DomainValidation[] {
+    return validatePropertyName(property)
+  }
+}

package/src/modeling/validation/rules.ts

@@ -0,0 +1,152 @@
+import { ReservedKeywords } from './postgresql.js'
+import type { DomainProperty } from '../DomainProperty.js'
+import type { DomainAssociation } from '../DomainAssociation.js'
+import type { DomainImpactItem } from '../DomainImpactAnalysis.js'
+import type { DomainEntity } from '../DomainEntity.js'
+import { DomainPropertyKind } from '../../models/kinds.js'
+
+/**
+ * `DomainImpactItem` mapping:
+ * - `impact` -> `message`
+ * - `resolution` -> `help`
+ * - `type` -> unused
+ * - `blocking` -> unused (deprecated)
+ * - `relationship` -> unused
+ */
+export interface DomainValidation
+  extends Omit<DomainImpactItem, 'type' | 'impact' | 'blocking' | 'relationship' | 'resolution'> {
+  /**
+   * The field that did not pass validation.
+   */
+  field: string
+  /**
+   * The name of the rule that was violated.
+   */
+  rule: string
+  /**
+   * Optional help message that can be used to provide
+   * more information about the error.
+   */
+  help?: string
+  /**
+   * Optional URL that can be used to provide more information
+   * about the error.
+   */
+  url?: string
+  /**
+   * The validation error message.
+   * This message should be user-friendly and should not
+   * contain any technical details.
+   * It should be used to display the error to the user.
+   * It should be short and concise.
+   */
+  message: string
+}
+
+/**
+ * Validates the property name. This includes associations.
+ *
+ * @remarks
+ * - A property must have a name defined.
+ * - The name has to follow the same rules as the names in a PostgreSQL database.
+ *   - Column names can only contain letters (a-z, A-Z), numbers (0-9), and underscores (_).
+ *   - The name must start with a letter (a-z, A-Z) or an underscore (_).
+ *   - PostgreSQL limits column names to a maximum of 59 characters.
+ *   - (our rule) Column names are case insensitive.
+ *   - (recommendation) Column names should be in lower case.
+ *
+ * @param property The property to validate
+ */
+export function validatePropertyName(property: DomainProperty | DomainAssociation): DomainValidation[] {
+  const results: DomainValidation[] = []
+  const label = property.info.getLabel()
+  const parentEntity = property.getParentInstance() as DomainEntity
+  const type = property.kind === DomainPropertyKind ? 'property' : 'association'
+  if (!property.info.name) {
+    const message = `The "${label}" ${type} has no name.`
+    const help = `The ${type} must have a name.`
+    results.push({
+      field: 'name',
+      rule: 'required',
+      message,
+      help,
+      severity: 'error',
+      key: property.key,
+      kind: property.kind,
+      parent: parentEntity.key,
+    })
+    return results
+  }
+  const name = property.info.name
+  if (name.length < 3) {
+    const message = `The "${label}" ${type} name is too short.`
+    const help = `The name must be at least 3 characters long.`
+    results.push({
+      field: 'name',
+      rule: 'length',
+      message,
+      help,
+      severity: 'error',
+      key: property.key,
+      kind: property.kind,
+      parent: parentEntity.key,
+    })
+  }
+  if (name.length > 59) {
+    const message = `The "${label}" ${type} name is too long.`
+    const help = `The name must be at most 59 characters long.`
+    results.push({
+      field: 'name',
+      rule: 'length',
+      message,
+      help,
+      severity: 'error',
+      key: property.key,
+      kind: property.kind,
+      parent: parentEntity.key,
+    })
+  }
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+    const message = `The "${label}" ${type} name is invalid.`
+    const help = `The name must start with a letter (a-z) or underscore (_). Subsequent characters can be letters, digits (0-9), or underscores (_).`
+    results.push({
+      field: 'name',
+      rule: 'format',
+      message,
+      help,
+      severity: 'error',
+      key: property.key,
+      kind: property.kind,
+      parent: parentEntity.key,
+    })
+  }
+  if (/^[A-Z]/.test(name)) {
+    const message = `The "${label}" ${type} name is not in snake case.`
+    const help = `The name should be in snake case (lowercase letters and underscores).`
+    results.push({
+      field: 'name',
+      rule: 'snake_case',
+      message,
+      help,
+      severity: 'info',
+      key: property.key,
+      kind: property.kind,
+      parent: parentEntity.key,
+    })
+  }
+  if (ReservedKeywords.has(name.toUpperCase())) {
+    const message = `The "${label}" ${type} name is a reserved keyword.`
+    const help = `The name should not be a reserved keyword.`
+    results.push({
+      field: 'name',
+      rule: 'reserved',
+      message,
+      help,
+      severity: 'error',
+      key: property.key,
+      kind: property.kind,
+      parent: parentEntity.key,
+    })
+  }
+  return results
+}

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

@@ -37,7 +37,7 @@ test.group('DataDomain.addAssociation()', () => {
     assert.instanceOf(association, DomainAssociation)
     assert.isTrue(dataDomain.graph.hasNode(association.key))
     assert.typeOf(association.key, 'string')
-    assert.equal(association.info.name, 'New association')
+    assert.equal(association.info.name, 'new_association')
   })
 
   test('addAssociation notifies change', async ({ assert }) => {

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

@@ -19,7 +19,7 @@ test.group('DataDomain.addProperty()', () => {
     const property = dataDomain.addProperty(entity.key)
     assert.instanceOf(property, DomainProperty)
     assert.isTrue(dataDomain.graph.hasNode(property.key))
-    assert.equal(property.info.name, 'New property')
+    assert.equal(property.info.name, 'new_property')
     assert.equal(property.type, 'string')
   })