@api-client/core 0.12.0 → 0.12.2

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

@@ -1,4 +1,4 @@
-import v4 from '../lib/uuid.js'
+import { nanoid } from 'nanoid'
 
 export interface IAuthorizationData {
   key: string
@@ -30,7 +30,7 @@ export class AuthorizationData {
       init = input
     } else {
       init = {
-        key: v4(),
+        key: nanoid(),
       }
     }
     this.new(init)
@@ -42,7 +42,7 @@ export class AuthorizationData {
    * Note, this throws an error when the provider is not an API Client provider object.
    */
   new(init: IAuthorizationData): void {
-    const { username, password, domain, key = v4() } = init
+    const { username, password, domain, key = nanoid() } = init
     this.username = username
     this.password = password
     this.domain = domain

package/src/models/CertificateFile.ts

@@ -1,4 +1,4 @@
-import v4 from '../lib/uuid.js'
+import { nanoid } from 'nanoid'
 import { Certificate, ICertificate } from './ClientCertificate.js'
 import { CertificateFileKind } from './kinds.js'
 import { IFile, File } from './store/File.js'
@@ -48,7 +48,7 @@ export class CertificateFile extends File {
     } else {
       init = {
         kind: CertificateFileKind,
-        key: v4(),
+        key: nanoid(),
         organization: '',
         info: Thing.fromName('').toJSON(),
         parents: [],

package/src/models/ClientCertificate.ts

@@ -1,5 +1,5 @@
 import { base64ToBuffer, bufferToBase64 } from '../lib/Buffer.js'
-import v4 from '../lib/uuid.js'
+import { nanoid } from 'nanoid'
 import {
   Certificate as LegacyCertificate,
   ARCCertificateIndex,
@@ -177,7 +177,7 @@ export class Certificate {
       certKey: {
         data: key,
       },
-      key: v4(),
+      key: nanoid(),
       name,
       type: 'pem',
       created: Date.now(),
@@ -201,7 +201,7 @@ export class Certificate {
       cert: {
         data: cert,
       },
-      key: v4(),
+      key: nanoid(),
       name,
       type: 'p12',
       created: Date.now(),
@@ -220,7 +220,7 @@ export class Certificate {
    *              to its original format.
    */
   static fromLegacy(index: ARCCertificateIndex, cert: RequestCertificate): Certificate {
-    const { name = '', type, created = Date.now(), _id = v4() } = index
+    const { name = '', type, created = Date.now(), _id = nanoid() } = index
     if (type === 'pem') {
       const data = Array.isArray(cert.cert) ? cert.cert[0] : cert.cert
       const key = Array.isArray(cert.key) ? cert.key[0] : (cert.key as LegacyCertificate)
@@ -253,7 +253,7 @@ export class Certificate {
   }
 
   constructor(certificate: HttpCertificate) {
-    const { type, cert, key = v4(), name = '', created = Date.now() } = certificate
+    const { type, cert, key = nanoid(), name = '', created = Date.now() } = certificate
     this.key = key
     this.name = name
     this.type = type

package/src/models/Environment.ts

@@ -1,7 +1,7 @@
 import { Property, IProperty } from './Property.js'
 import { Server, IServer } from './Server.js'
 import { IThing, Thing } from './Thing.js'
-import v4 from '../lib/uuid.js'
+import { nanoid } from 'nanoid'
 import { ARCVariable } from './legacy/models/Variable.js'
 import { IRequestAuthorization, RequestAuthorization } from './RequestAuthorization.js'
 
@@ -91,7 +91,7 @@ export class Environment {
    * @param name The name to set.
    */
   static fromName(name: string): Environment {
-    const key = v4()
+    const key = nanoid()
     const info = Thing.fromName(name)
     const definition = new Environment({
       key,
@@ -103,7 +103,7 @@ export class Environment {
   }
 
   static fromLegacyVariables(name: string, variables: ARCVariable[]): Environment {
-    const key = v4()
+    const key = nanoid()
     const info = Thing.fromName(name)
     const definition = new Environment({
       key,
@@ -132,7 +132,7 @@ export class Environment {
     } else {
       init = {
         kind: Kind,
-        key: v4(),
+        key: nanoid(),
         info: Thing.fromName('').toJSON(),
         variables: [],
       }
@@ -149,7 +149,7 @@ export class Environment {
     if (!Environment.isEnvironment(init)) {
       throw new Error(`Not an environment.`)
     }
-    const { key = v4(), variables, info, server, encapsulated = false, authorization } = init
+    const { key = nanoid(), variables, info, server, encapsulated = false, authorization } = init
     this.kind = Kind
     this.key = key
     this.encapsulated = encapsulated
@@ -262,7 +262,7 @@ export class Environment {
   clone(opts: IEnvironmentCloneOptions = {}): Environment {
     const copy = new Environment(this.toJSON())
     if (!opts.withoutRevalidate) {
-      copy.key = v4()
+      copy.key = nanoid()
     }
     return copy
   }

package/src/models/Folder.ts

@@ -1,5 +1,5 @@
 import { IFile, File } from './store/File.js'
-import v4 from '../lib/uuid.js'
+import { nanoid } from 'nanoid'
 import { Thing } from './Thing.js'
 import { FolderKind } from './kinds.js'
 
@@ -39,7 +39,7 @@ export class Folder extends File {
     } else {
       init = {
         kind: FolderKind,
-        key: v4(),
+        key: nanoid(),
         organization: '',
         info: Thing.fromName('').toJSON(),
         parents: [],

package/src/models/HostRule.ts

@@ -1,4 +1,4 @@
-import v4 from '../lib/uuid.js'
+import { nanoid } from 'nanoid'
 
 export const Kind = 'Core#HostRule'
 
@@ -56,7 +56,7 @@ export class HostRule {
 
   static fromValues(from: string, to: string): HostRule {
     const result = new HostRule({
-      key: v4(),
+      key: nanoid(),
       kind: Kind,
       from,
       to,
@@ -76,7 +76,7 @@ export class HostRule {
       init = input
     } else {
       init = {
-        key: v4(),
+        key: nanoid(),
         kind: Kind,
         from: '',
         to: '',
@@ -94,7 +94,7 @@ export class HostRule {
     if (!HostRule.isHostRule(init)) {
       throw new Error(`Not a HostRule.`)
     }
-    const { from = '', to = '', enabled, comment, key = v4() } = init
+    const { from = '', to = '', enabled, comment, key = nanoid() } = init
     this.kind = Kind
     this.key = key
     this.from = from