@api-client/core 0.14.9 → 0.15.0

package/src/modeling/types.ts

@@ -5,6 +5,14 @@ import type { DomainEntity } from './DomainEntity.js'
 import type { DomainModel } from './DomainModel.js'
 import type { DomainNamespace } from './DomainNamespace.js'
 import type { DomainProperty } from './DomainProperty.js'
+import type {
+  DomainNamespaceKind,
+  DomainEntityKind,
+  DomainModelKind,
+  DomainPropertyKind,
+  DomainAssociationKind,
+  DataDomainKind,
+} from '../models/kinds.js'
 
 export interface DataDomainRemoveOptions {
   /**
@@ -732,3 +740,81 @@ export interface RateLimitRule {
    */
   burst: number
 }
+
+export type DomainImpactKinds =
+  | typeof DomainNamespaceKind
+  | typeof DomainEntityKind
+  | typeof DomainModelKind
+  | typeof DomainPropertyKind
+  | typeof DomainAssociationKind
+  | typeof DataDomainKind
+
+/**
+ * The impact analysis report
+ */
+export interface DomainImpactReport {
+  /**
+   * The key of the impacted data object.
+   * This is the key of the object that is being changed.
+   */
+  key: string
+  /**
+   * The kind of the impacted data object.
+   * This is the kind of the object that is being changed.
+   */
+  kind: DomainImpactKinds
+  /**
+   * The list of impacted data objects.
+   */
+  impact: DomainImpactItem[]
+  /**
+   * Whether it is possible to proceed with the change.
+   * If the change is not possible, the reason will be in the impact list.
+   */
+  canProceed: boolean
+}
+
+export interface DomainImpactItem {
+  /**
+   * The key of the impacted data object.
+   */
+  key: string
+  /**
+   * The kind of the impacted data object.
+   */
+  kind: string
+  /**
+   * The type of the impact.
+   *
+   * - `delete` - The data object would be deleted.
+   */
+  type: 'delete' | 'publish'
+  /**
+   * The impact description.
+   * Explains what will happen to the impacted data object.
+   * This is a human-readable description of the impact.
+   * It should be clear and concise.
+   */
+  impact: string
+  /**
+   * The severity of the impact.
+   *
+   * - `info` - The impact is informational.
+   * - `warning` - The impact can potentially cause problems but is not a blocker.
+   * - `error` - The impact is a blocker and needs to be resolved before proceeding.
+   */
+  severity: 'info' | 'warning' | 'error'
+  /**
+   * The type of the relationship between two impacted objects.
+   */
+  relationship?: 'child'
+  /**
+   * The resolution of the conflict if the change will be forced.
+   */
+  resolution?: string
+  /**
+   * The optional parent of the impacted data object.
+   * For example, if the impacted item is a property, this will be the entity it belongs to.
+   */
+  parent?: string
+}

package/src/modeling/validation/entity_validation.ts

@@ -225,7 +225,7 @@ export class EntityValidation {
         })
       }
     }
-    for (const other of this.domain.listForeignEntities()) {
+    for (const other of this.domain.listAllForeignEntities()) {
       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.`

package/src/modeling/validation/rules.ts

@@ -1,7 +1,7 @@
 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 { DomainImpactItem } from '../types.js'
 import type { DomainEntity } from '../DomainEntity.js'
 import { DomainPropertyKind } from '../../models/kinds.js'
 
@@ -10,11 +10,9 @@ import { DomainPropertyKind } from '../../models/kinds.js'
  * - `impact` -> `message`
  * - `resolution` -> `help`
  * - `type` -> unused
- * - `blocking` -> unused (deprecated)
  * - `relationship` -> unused
  */
-export interface DomainValidation
-  extends Omit<DomainImpactItem, 'type' | 'impact' | 'blocking' | 'relationship' | 'resolution'> {
+export interface DomainValidation extends Omit<DomainImpactItem, 'type' | 'impact' | 'relationship' | 'resolution'> {
   /**
    * The field that did not pass validation.
    */

package/src/modeling/validation/semantic_validation.ts

@@ -0,0 +1,145 @@
+import { DomainEntityKind } from '../../models/kinds.js'
+import type { DataDomain } from '../DataDomain.js'
+import { SemanticType } from '../Semantics.js'
+import type { DomainValidation } from './rules.js'
+
+/**
+ * SemanticValidation is a class that performs validation on semantics in a data domain.
+ * It checks for required and recommended semantics in entities, properties, and associations.
+ */
+export class SemanticValidation {
+  constructor(protected domain: DataDomain) {}
+
+  /**
+   * Performs all the semantic validation rules on the domain.
+   * @returns The list of validation messages.
+   */
+  validate(): DomainValidation[] {
+    const results: DomainValidation[] = []
+
+    // Check for User entity semantic
+    const hasUserEntity = this.validateUserEntity()
+    results.push(...hasUserEntity)
+
+    // Check for timestamp semantics
+    const timestampSemantics = this.validateTimestampSemantics()
+    results.push(...timestampSemantics)
+
+    // Check for soft delete semantics
+    const softDeleteSemantics = this.validateSoftDeleteSemantics()
+    results.push(...softDeleteSemantics)
+
+    return results
+  }
+
+  /**
+   * Validates if there is at least one entity with the User semantic.
+   * This is a recommended semantic for authentication purposes.
+   */
+  private validateUserEntity(): DomainValidation[] {
+    const results: DomainValidation[] = []
+    let hasUserEntity = false
+
+    for (const entity of this.domain.listEntities()) {
+      if (entity.hasSemantic(SemanticType.User)) {
+        hasUserEntity = true
+        break
+      }
+    }
+
+    if (!hasUserEntity) {
+      results.push({
+        field: 'semantics',
+        rule: 'recommended',
+        message: 'No entity with User taxonomy found in the domain.',
+        help: 'It is recommended to have at least one entity with the User taxonomy for authentication purposes.',
+        severity: 'warning',
+        key: 'user_semantic',
+        kind: DomainEntityKind,
+      })
+    }
+
+    return results
+  }
+
+  /**
+   * Validates if entities have the recommended timestamp semantics.
+   * This includes CreatedTimestamp and UpdatedTimestamp.
+   */
+  private validateTimestampSemantics(): DomainValidation[] {
+    const results: DomainValidation[] = []
+
+    for (const entity of this.domain.listEntities()) {
+      let hasCreatedTimestamp = false
+      let hasUpdatedTimestamp = false
+
+      for (const property of entity.listProperties()) {
+        if (property.hasSemantic(SemanticType.CreatedTimestamp)) {
+          hasCreatedTimestamp = true
+        }
+        if (property.hasSemantic(SemanticType.UpdatedTimestamp)) {
+          hasUpdatedTimestamp = true
+        }
+      }
+
+      if (!hasCreatedTimestamp) {
+        results.push({
+          field: 'semantics',
+          rule: 'recommended',
+          message: `The "${entity.info.getLabel()}" entity does not have a CreatedTimestamp taxonomy.`,
+          help: 'It is recommended to have a CreatedTimestamp property to track when the entity was created.',
+          severity: 'info',
+          key: entity.key,
+          kind: entity.kind,
+        })
+      }
+
+      if (!hasUpdatedTimestamp) {
+        results.push({
+          field: 'semantics',
+          rule: 'recommended',
+          message: `The "${entity.info.getLabel()}" entity does not have an UpdatedTimestamp taxonomy.`,
+          help: 'It is recommended to have an UpdatedTimestamp property to track when the entity was last modified.',
+          severity: 'info',
+          key: entity.key,
+          kind: entity.kind,
+        })
+      }
+    }
+
+    return results
+  }
+
+  /**
+   * Validates if entities have the recommended soft delete semantics.
+   * This includes either DeletedTimestamp or DeletedFlag.
+   */
+  private validateSoftDeleteSemantics(): DomainValidation[] {
+    const results: DomainValidation[] = []
+
+    for (const entity of this.domain.listEntities()) {
+      let hasSoftDelete = false
+
+      for (const property of entity.listProperties()) {
+        if (property.hasSemantic(SemanticType.DeletedTimestamp) || property.hasSemantic(SemanticType.DeletedFlag)) {
+          hasSoftDelete = true
+          break
+        }
+      }
+
+      if (!hasSoftDelete) {
+        results.push({
+          field: 'semantics',
+          rule: 'recommended',
+          message: `The "${entity.info.getLabel()}" entity does not have soft delete taxonomy.`,
+          help: 'It is recommended to have either a DeletedTimestamp or DeletedFlag property for soft deletion.',
+          severity: 'info',
+          key: entity.key,
+          kind: entity.kind,
+        })
+      }
+    }
+
+    return results
+  }
+}

package/tests/unit/events/EventsTestHelpers.ts

@@ -0,0 +1,16 @@
+// The event names should be unique across all events in all modules.
+const names: string[] = []
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function ensureUnique(namespace: string, src: any): void {
+  for (const [key, value] of Object.entries(src)) {
+    const typedValue = value as string
+    if (typeof typedValue !== 'string') {
+      return
+    }
+    if (names.includes(typedValue)) {
+      throw new Error(`${namespace}.${key} has duplicated event name ${typedValue}`)
+    }
+    names.push(typedValue)
+  }
+}

package/tests/unit/events/amf.spec.ts

@@ -0,0 +1,151 @@
+import { test } from '@japa/runner'
+import sinon from 'sinon'
+import { EventTypes } from '../../../src/events/EventTypes.js'
+import { Events } from '../../../src/events/Events.js'
+import { ensureUnique } from './EventsTestHelpers.js'
+import './events_polyfills.js'
+
+test.group('EventTypes.Amf', () => {
+  test('has the namespace', ({ assert }) => {
+    assert.typeOf(EventTypes.Amf, 'object')
+  })
+
+  test('has frozen namespace', ({ assert }) => {
+    assert.throws(() => {
+      // @ts-expect-error Used in testing
+      EventTypes.Amf = { read: '' }
+    })
+  })
+
+  test('has "{prop}" property')
+    .with([
+      {
+        prop: 'processApiLink',
+        value: 'amfprocessapilink',
+      },
+      {
+        prop: 'processBuffer',
+        value: 'amfprocessbuffer',
+      },
+      {
+        prop: 'processApiFile',
+        value: 'amfprocessapifile',
+      },
+      {
+        prop: 'selectApiMainFile',
+        value: 'amfselectapimainfile',
+      },
+    ])
+    .run(({ assert }, { prop, value }) => {
+      // @ts-expect-error Used in testing
+      assert.equal(EventTypes.Amf[prop], value)
+    })
+
+  test('has unique events on the namespace', () => {
+    ensureUnique('EventTypes.Amf', EventTypes.Amf)
+  })
+})
+
+test.group('processApiLink()', () => {
+  const url = 'https://api.com'
+  const mainFile = 'api.raml'
+  const md5 = '123qwe'
+  const packaging = 'zip'
+
+  test('dispatches the event', async ({ assert }) => {
+    const spy = sinon.spy()
+    globalThis.addEventListener(EventTypes.Amf.processApiLink, spy)
+    await Events.Amf.processApiLink(url)
+    assert.isTrue(spy.calledOnce)
+  })
+
+  test('sets the arguments on the detail object', async ({ assert }) => {
+    const spy = sinon.spy()
+    globalThis.addEventListener(EventTypes.Amf.processApiLink, spy)
+    await Events.Amf.processApiLink(url, mainFile, md5, packaging)
+    globalThis.removeEventListener(EventTypes.Amf.processApiLink, spy)
+    const { detail } = spy.args[0][0]
+    assert.equal(detail.url, url, 'url is set')
+    assert.equal(detail.mainFile, mainFile, 'mainFile is set')
+    assert.equal(detail.md5, md5, 'md5 is set')
+    assert.equal(detail.packaging, packaging, 'packaging is set')
+  })
+
+  test('returns the result', async ({ assert }) => {
+    const parseResult = { model: '', type: { type: 'RAML 1.0' } }
+    function handler(e: CustomEvent): void {
+      globalThis.removeEventListener(EventTypes.Amf.processApiLink, handler as EventListener)
+      e.preventDefault()
+      e.detail.result = Promise.resolve(parseResult)
+    }
+    globalThis.addEventListener(EventTypes.Amf.processApiLink, handler as EventListener)
+    const result = await Events.Amf.processApiLink(url)
+    assert.equal(result, parseResult)
+  })
+})
+
+test.group('processApiFile()', () => {
+  const file = new File([], 'test.txt')
+
+  test('dispatches the event', async ({ assert }) => {
+    const spy = sinon.spy()
+    globalThis.addEventListener(EventTypes.Amf.processApiFile, spy)
+    await Events.Amf.processApiFile(file)
+    globalThis.removeEventListener(EventTypes.Amf.processApiFile, spy)
+    assert.isTrue(spy.calledOnce)
+  })
+
+  test('sets the arguments on the detail object', async ({ assert }) => {
+    const spy = sinon.spy()
+    globalThis.addEventListener(EventTypes.Amf.processApiFile, spy)
+    await Events.Amf.processApiFile(file)
+    globalThis.removeEventListener(EventTypes.Amf.processApiFile, spy)
+    const { detail } = spy.args[0][0]
+    assert.deepEqual(detail.file, file, 'file is set')
+  })
+
+  test('returns the result', async ({ assert }) => {
+    const parseResult = { model: '', type: { type: 'RAML 1.0' } }
+    function handler(e: CustomEvent): void {
+      globalThis.removeEventListener(EventTypes.Amf.processApiFile, handler as EventListener)
+      e.preventDefault()
+      e.detail.result = Promise.resolve(parseResult)
+    }
+    globalThis.addEventListener(EventTypes.Amf.processApiFile, handler as EventListener)
+    const result = await Events.Amf.processApiFile(file)
+    assert.equal(result, parseResult)
+  })
+})
+
+test.group('selectApiMainFile()', () => {
+  const candidates = ['test']
+
+  test('dispatches the event', async ({ assert }) => {
+    const spy = sinon.spy()
+    globalThis.addEventListener(EventTypes.Amf.selectApiMainFile, spy)
+    await Events.Amf.selectApiMainFile(candidates)
+    globalThis.removeEventListener(EventTypes.Amf.selectApiMainFile, spy)
+    assert.isTrue(spy.calledOnce)
+  })
+
+  test('sets the arguments on the detail object', async ({ assert }) => {
+    const spy = sinon.spy()
+    globalThis.addEventListener(EventTypes.Amf.selectApiMainFile, spy)
+    await Events.Amf.selectApiMainFile(candidates)
+    globalThis.removeEventListener(EventTypes.Amf.selectApiMainFile, spy)
+    const { detail } = spy.args[0][0]
+    assert.deepEqual(detail.candidates, candidates, 'candidates is set')
+  })
+
+  test('returns the result', async ({ assert }) => {
+    const selected = 'test'
+    function handler(e: CustomEvent): void {
+      globalThis.removeEventListener(EventTypes.Amf.selectApiMainFile, handler as EventListener)
+      e.preventDefault()
+      e.detail.result = Promise.resolve(selected)
+    }
+    globalThis.addEventListener(EventTypes.Amf.selectApiMainFile, handler as EventListener)
+    const result = await Events.Amf.selectApiMainFile(candidates)
+    assert.equal(result, selected)
+  })
+})

package/tests/unit/events/authorization.spec.ts

@@ -0,0 +1,150 @@
+import { test } from '@japa/runner'
+import sinon from 'sinon'
+import { EventTypes } from '../../../src/events/EventTypes.js'
+import { Events } from '../../../src/events/Events.js'
+import { ensureUnique } from './EventsTestHelpers.js'
+import './events_polyfills.js'
+
+test.group('Events > Authorization > EventTypes.Authorization', () => {
+  test('has the namespace', ({ assert }) => {
+    assert.typeOf(EventTypes.Authorization, 'object')
+  })
+
+  test('has OAuth2 namespace', ({ assert }) => {
+    assert.typeOf(EventTypes.Authorization.OAuth2, 'object')
+  })
+
+  test('has frozen OAuth2 namespace', ({ assert }) => {
+    assert.throws(() => {
+      // @ts-expect-error Used in testing
+      EventTypes.Authorization.OAuth2 = { read: '' }
+    })
+  })
+
+  test('has "{prop}" property for OAuth2')
+    .with([
+      { prop: 'authorize', value: 'oauth2authorize' },
+      { prop: 'removeToken', value: 'oauth2removetoken' },
+    ])
+    .run(({ assert }, { prop, value }) => {
+      // @ts-expect-error Used in testing
+      assert.equal(EventTypes.Authorization.OAuth2[prop], value)
+    })
+
+  test('has unique events for OAuth2 namespace', () => {
+    ensureUnique('EventTypes.Authorization.OAuth2', EventTypes.Authorization.OAuth2)
+  })
+
+  test('has frozen Oidc namespace', ({ assert }) => {
+    assert.throws(() => {
+      // @ts-expect-error Used in testing
+      EventTypes.Authorization.Oidc = { read: '' }
+    })
+  })
+
+  test('has "{prop}" property for Oidc')
+    .with([
+      { prop: 'authorize', value: 'oidcauthorize' },
+      { prop: 'removeTokens', value: 'oidcremovetokens' },
+    ])
+    .run(({ assert }, { prop, value }) => {
+      // @ts-expect-error Used in testing
+      assert.equal(EventTypes.Authorization.Oidc[prop], value)
+    })
+
+  test('has unique events for Oidc namespace', () => {
+    ensureUnique('EventTypes.Authorization.Oidc', EventTypes.Authorization.Oidc)
+  })
+})
+
+test.group('Events > Authorization > Events.Authorization > OAuth2 > authorize()', () => {
+  const config = { responseType: 'implicit' }
+
+  test('dispatches the event', async ({ assert }) => {
+    const spy = sinon.spy()
+    globalThis.addEventListener(EventTypes.Authorization.OAuth2.authorize, spy)
+    Events.Authorization.OAuth2.authorize(config)
+    globalThis.removeEventListener(EventTypes.Authorization.OAuth2.authorize, spy)
+    assert.isTrue(spy.calledOnce)
+  })
+
+  test('has the configuration on the detail', async ({ assert }) => {
+    const spy = sinon.spy()
+    globalThis.addEventListener(EventTypes.Authorization.OAuth2.authorize, spy)
+    Events.Authorization.OAuth2.authorize(config)
+    globalThis.removeEventListener(EventTypes.Authorization.OAuth2.authorize, spy)
+    const e = spy.args[0][0]
+    const cnf = e.detail
+    delete cnf.result
+    assert.deepEqual(cnf, config)
+  })
+})
+
+test.group('Events > Authorization > Events.Authorization > OAuth2 > removeToken()', () => {
+  const config = { clientId: 'id', authorizationUri: 'test' }
+
+  test('dispatches the event', async ({ assert }) => {
+    const spy = sinon.spy()
+    globalThis.addEventListener(EventTypes.Authorization.OAuth2.removeToken, spy)
+    Events.Authorization.OAuth2.removeToken(config)
+    globalThis.removeEventListener(EventTypes.Authorization.OAuth2.removeToken, spy)
+    assert.isTrue(spy.calledOnce)
+  })
+
+  test('has the configuration on the detail', async ({ assert }) => {
+    const spy = sinon.spy()
+    globalThis.addEventListener(EventTypes.Authorization.OAuth2.removeToken, spy)
+    Events.Authorization.OAuth2.removeToken(config)
+    globalThis.removeEventListener(EventTypes.Authorization.OAuth2.removeToken, spy)
+    const e = spy.args[0][0]
+    const cnf = e.detail
+    delete cnf.result
+    assert.deepEqual(cnf, config)
+  })
+})
+
+test.group('Events > Authorization > Events.Authorization > Oidc > authorize()', () => {
+  const config = { responseType: 'implicit' }
+
+  test('dispatches the event', async ({ assert }) => {
+    const spy = sinon.spy()
+    globalThis.addEventListener(EventTypes.Authorization.Oidc.authorize, spy)
+    Events.Authorization.Oidc.authorize(config)
+    globalThis.removeEventListener(EventTypes.Authorization.Oidc.authorize, spy)
+    assert.isTrue(spy.calledOnce)
+  })
+
+  test('has the configuration on the detail', async ({ assert }) => {
+    const spy = sinon.spy()
+    globalThis.addEventListener(EventTypes.Authorization.Oidc.authorize, spy)
+    Events.Authorization.Oidc.authorize(config)
+    globalThis.removeEventListener(EventTypes.Authorization.Oidc.authorize, spy)
+    const e = spy.args[0][0]
+    const cnf = e.detail
+    delete cnf.result
+    assert.deepEqual(cnf, config)
+  })
+})
+
+test.group('Events > Authorization > Events.Authorization > Oidc > removeToken()', () => {
+  const config = { clientId: 'id', authorizationUri: 'test' }
+
+  test('dispatches the event', async ({ assert }) => {
+    const spy = sinon.spy()
+    globalThis.addEventListener(EventTypes.Authorization.Oidc.removeTokens, spy)
+    Events.Authorization.Oidc.removeTokens(config)
+    globalThis.removeEventListener(EventTypes.Authorization.Oidc.removeTokens, spy)
+    assert.isTrue(spy.calledOnce)
+  })
+
+  test('has the configuration on the detail', async ({ assert }) => {
+    const spy = sinon.spy()
+    globalThis.addEventListener(EventTypes.Authorization.Oidc.removeTokens, spy)
+    Events.Authorization.Oidc.removeTokens(config) // Calling removeToken
+    globalThis.removeEventListener(EventTypes.Authorization.Oidc.removeTokens, spy)
+    const e = spy.args[0][0]
+    const cnf = e.detail
+    delete cnf.result
+    assert.deepEqual(cnf, config)
+  })
+})