@api-client/core 0.11.7 → 0.11.8

package/src/modeling/ImpactAnalysis.ts

@@ -0,0 +1,519 @@
+import {
+  DataNamespaceKind,
+  DataEntityKind,
+  DataModelKind,
+  DataPropertyKind,
+  DataAssociationKind,
+} from '../models/kinds.js'
+import type { DataNamespace } from './DataNamespace.js'
+
+export type ImpactKinds =
+  | typeof DataNamespaceKind
+  | typeof DataEntityKind
+  | typeof DataModelKind
+  | typeof DataPropertyKind
+  | typeof DataAssociationKind
+
+/**
+ * The impact analysis report
+ */
+interface ImpactReport {
+  /**
+   * 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: ImpactKinds
+  /**
+   * The list of impacted data objects.
+   */
+  impact: ImpactItem[]
+  /**
+   * 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
+}
+
+interface ImpactItem {
+  /**
+   * 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'
+  /**
+   * The impact description.
+   */
+  impact: string
+  /**
+   * Whether the impact is blocking the operation.
+   * If true, the operation cannot proceed.
+   */
+  blocking: boolean
+  /**
+   * The type of the relationship between two impacted objects.
+   */
+  relationship?: 'child'
+  /**
+   * The resolution of the conflict if the change will be forced.
+   */
+  resolution?: string
+}
+
+/**
+ * # ImpactAnalysis
+ *
+ * The `ImpactAnalysis` class is a powerful tool for analyzing the consequences of deleting data domain objects
+ * within a `DataNamespace`.
+ * It helps developers understand the ripple effects of removing a namespace, data model, entity, property,
+ * or association, ensuring data integrity and preventing unintended side effects.
+ *
+ * ## Core Concepts
+ *
+ * -   **Impact Report:** The central output of the `ImpactAnalysis` class is an `ImpactReport`. This report details the
+ *     potential consequences of a deletion operation, including:
+ *     -   The object being deleted (`key`, `kind`).
+ *     -   A list of `ImpactItem` objects, each describing a specific consequence.
+ *     -   Whether the deletion can proceed safely (`canProceed`).
+ *
+ * -   **ImpactItem:** Each `ImpactItem` describes a specific consequence of the deletion. Key properties include:
+ *     -   `key`: The key of the impacted object.
+ *     -   `kind`: The kind of the impacted object.
+ *     -   `type`: The type of impact (currently only `delete`).
+ *     -   `impact`: A human-readable description of the impact.
+ *     -   `blocking`: Whether this impact prevents the deletion from proceeding.
+ *     -   `relationship`: The type of relationship between the deleted object and the impacted object (e.g., `child`).
+ *     -   `resolution`: A description of how the impact will be resolved if the deletion is forced.
+ *
+ * -   **Blocking Impacts:** Some impacts are considered "blocking," meaning they prevent the deletion from proceeding
+ *     without manual intervention. For example, deleting an entity that is a parent to other entities is
+ *     a blocking impact.
+ *
+ * -   **Non-Blocking Impacts:** Some impacts are informational and do not prevent the deletion. For example, deleting a
+ *     property is not a blocking impact.
+ *
+ * ## Usage
+ *
+ * 1.  **Instantiation:** Create an instance of `ImpactAnalysis`, passing the root `DataNamespace` as an argument.
+ *
+ *     ```typescript
+ *     import { DataNamespace } from './DataNamespace'; // Assuming DataNamespace is in the same directory
+ *     import { ImpactAnalysis } from './ImpactAnalysis'; // Assuming ImpactAnalysis is in the same directory
+ *
+ *     const rootNamespace = new DataNamespace();
+ *     // ... add some data to the namespace
+ *     const analyzer = new ImpactAnalysis(rootNamespace);
+ *     ```
+ *
+ * 2.  **Performing Analysis:** Use the `deleteAnalysis()` method to generate an `ImpactReport` for a specific deletion.
+ *     Provide the `key` and `kind` of the object to be deleted.
+ *
+ *     ```typescript
+ *     import { DataEntityKind } from '../models/kinds.js';
+ *     // ...
+ *     const entityKey = 'some-entity-key';
+ *     const report = analyzer.deleteAnalysis(entityKey, DataEntityKind);
+ *     ```
+ *
+ * 3.  **Interpreting the Report:** Examine the `ImpactReport` to understand the consequences of the deletion.
+ *     -   Check `report.canProceed` to see if the deletion is safe.
+ *     -   Iterate through `report.impact` to understand each consequence.
+ *     -   Pay special attention to `impact.blocking` to identify impacts that require manual resolution.
+ *
+ *     ```typescript
+ *     if (report.canProceed) {
+ *       // Proceed with deletion
+ *     } else {
+ *       console.warn('Deletion cannot proceed due to the following impacts:');
+ *       report.impact.forEach((item) => {
+ *         console.warn(`- ${item.impact}`);
+ *         if (item.blocking) {
+ *           console.warn(`  - This impact is blocking.`);
+ *           if (item.resolution) {
+ *             console.warn(`  - Resolution: ${item.resolution}`);
+ *           }
+ *         }
+ *       });
+ *       // Handle blocking impacts (e.g., prompt the user, modify the data, etc.)
+ *     }
+ *     ```
+ *
+ * ## Supported Deletion Scenarios
+ *
+ * The `ImpactAnalysis` class supports analyzing the deletion of the following data domain object types:
+ *
+ * -   **Namespaces (`DataNamespaceKind`):** Deleting a namespace also impacts all its child namespaces,
+ *     data models, entities, properties, and associations.
+ * -   **Data Models (`DataModelKind`):** Deleting a data model impacts all its entities, properties, and associations.
+ * -   **Entities (`DataEntityKind`):** Deleting an entity impacts its properties, associations, and any other
+ *     entities that have it as a parent or target in an association.
+ * -   **Properties (`DataPropertyKind`):** Deleting a property impacts the entity it belongs to.
+ * -   **Associations (`DataAssociationKind`):** Deleting an association impacts the entity it belongs to.
+ *
+ * ## Example: Deleting an Entity
+ *
+ * Consider the following scenario:
+ *
+ * -   Namespace: `MyNamespace`
+ *     -   Data Model: `ProductModel`
+ *         -   Entity: `Product`
+ *             -   Property: `name`
+ *             -   Association: `category` (targets `Category` entity)
+ *         -   Entity: `Category`
+ *             - Property: `name`
+ *         - Entity: `SpecialProduct` (parent: `Product`)
+ *
+ * If you attempt to delete the `Product` entity, the `ImpactAnalysis` will generate a report similar to this:
+ *
+ * ```json
+ * {
+ *   "key": "Product",
+ *   "kind": "DataEntityKind",
+ *   "impact": [
+ *     {
+ *       "key": "Product",
+ *       "kind": "DataEntityKind",
+ *       "type": "delete",
+ *       "impact": "The entity with key Product will be deleted.",
+ *       "blocking": false
+ *     },
+ *     {
+ *       "key": "SpecialProduct",
+ *       "kind": "DataEntityKind",
+ *       "type": "delete",
+ *       "impact": "The SpecialProduct entity will become an orphan because it is a child of Product.",
+ *       "resolution": "The Product will be removed as the parent parent of SpecialProduct.",
+ *       "blocking": true,
+ *       "relationship": "child"
+ *     },
+ *     {
+ *       "key": "category",
+ *       "kind": "DataAssociationKind",
+ *       "type": "delete",
+ *       "impact": "The association with key category will be broken because it has a target to Product.",
+ *       "resolution": "The association with key category will be removed from Product.",
+ *       "blocking": true
+ *     },
+ *     {
+ *       "key": "name",
+ *       "kind": "DataPropertyKind",
+ *       "type": "delete",
+ *       "impact": "The property with key name will be deleted.",
+ *       "blocking": false
+ *     }
+ *   ],
+ *   "canProceed": false
+ * }
+ * ```
+ *
+ * This report indicates that:
+ *
+ * -   The `Product` entity will be deleted.
+ * -   The `SpecialProduct` entity will become an orphan (blocking).
+ * -   The `category` association will be broken (blocking).
+ * -   The `name` property will be deleted.
+ * -   The deletion cannot proceed without addressing the blocking impacts.
+ *
+ * ## Types
+ *
+ * ### `ImpactKinds`
+ *
+ * -   **Description:** A type alias for the kinds of data domain objects that can be analyzed.
+ * -   **Values:**
+ *     -   `DataNamespaceKind`
+ *     -   `DataEntityKind`
+ *     -   `DataModelKind`
+ *     -   `DataPropertyKind`
+ *     -   `DataAssociationKind`
+ *
+ * ### `ImpactReport`
+ *
+ * -   **Description:** The structure of the impact analysis report.
+ * -   **Properties:**
+ *     -   `key` (`string`): The key of the object being deleted.
+ *     -   `kind` (`ImpactKinds`): The kind of the object being deleted.
+ *     -   `impact` (`ImpactItem[]`): The list of impacts.
+ *     -   `canProceed` (`boolean`): Whether the deletion can proceed.
+ *
+ * ### `ImpactItem`
+ *
+ * -   **Description:** The structure of an individual impact item.
+ * -   **Properties:**
+ *     -   `key` (`string`): The key of the impacted object.
+ *     -   `kind` (`string`): The kind of the impacted object.
+ *     -   `type` (`'delete'`): The type of impact.
+ *     -   `impact` (`string`): The impact description.
+ *     -   `blocking` (`boolean`): Whether the impact is blocking.
+ *     -   `relationship` (`'child'`, optional): The relationship type.
+ *     -   `resolution` (`string`, optional): The resolution description.
+ *
+ * ## Error Handling
+ *
+ * The `ImpactAnalysis` class does not throw errors. Instead, it uses the `ImpactReport` to communicate
+ * the results of the analysis, including any blocking impacts.
+ *
+ * ## Best Practices
+ *
+ * - **Always Analyze Before Deleting:** Before deleting any data domain object, always use `ImpactAnalysis`
+ *   to understand the consequences.
+ * - **Handle Blocking Impacts:** Pay close attention to `blocking` impacts and implement appropriate
+ *   logic to handle them.
+ * - **Inform the User:** If a deletion cannot proceed, inform the user about the blocking impacts and provide
+ *   guidance on how to resolve them.
+ * - **Consider Forced Deletion:** In some cases, you may want to allow users to force a deletion even if there are
+ *   blocking impacts. In such cases, you should clearly communicate the risks to the user.
+ *
+ * ## Conclusion
+ *
+ * The `ImpactAnalysis` class is an essential tool for maintaining data integrity when working with complex
+ * data domain models. By providing detailed impact reports, it empowers developers to make informed decisions
+ * about data deletion and prevent unintended consequences.
+ */
+export class ImpactAnalysis {
+  private report: ImpactReport
+  private root: DataNamespace
+
+  constructor(root: DataNamespace) {
+    this.root = root
+    this.report = {
+      key: '',
+      kind: DataNamespaceKind,
+      impact: [],
+      canProceed: false,
+    }
+  }
+
+  /**
+   * Generates a report of how the data domain will be impacted by the deletion of a data domain object.
+   * @param key The key of the impacted data domain object.
+   * @param kind The kind of the impacted data object.
+   * @returns The delete impact analysis report.
+   */
+  deleteAnalysis(key: string, kind: ImpactKinds): ImpactReport {
+    this.report = {
+      key,
+      kind,
+      impact: [],
+      canProceed: true,
+    }
+    this.report.impact = this.createDeleteImpact(key, kind, key)
+    // this.report.impact.unshift({
+    //   key,
+    //   kind,
+    //   type: 'delete',
+    //   impact: `The ${this.kindToLabel(kind)} with key ${key} will be deleted.`,
+    //   blocking: false,
+    // })
+    return this.report
+  }
+
+  protected createDeleteImpact(key: string, kind: ImpactKinds, rootKey: string): ImpactItem[] {
+    switch (kind) {
+      case DataNamespaceKind:
+        return this.deleteNamespaceAnalysis(key, rootKey)
+      case DataModelKind:
+        return this.deleteDataModelAnalysis(key, rootKey)
+      case DataEntityKind:
+        return this.deleteEntityAnalysis(key, rootKey)
+      case DataPropertyKind:
+        return this.deletePropertyAnalysis(key)
+      case DataAssociationKind:
+        return this.deleteAssociationAnalysis(key)
+      default:
+        return []
+    }
+  }
+
+  protected deleteNamespaceAnalysis(key: string, rootKey: string): ImpactItem[] {
+    const result: ImpactItem[] = []
+    const ns = this.root.findNamespace(key)
+    if (!ns) {
+      return result
+    }
+    result.push({
+      key: ns.key,
+      kind: ns.kind,
+      type: 'delete',
+      impact: `The ${ns.info.renderLabel} ${this.kindToLabel(DataNamespaceKind)} will be deleted.`,
+      blocking: false,
+    })
+    const namespaces = ns.listNamespaces()
+    namespaces.forEach((child) => {
+      const items = this.deleteNamespaceAnalysis(child.key, rootKey)
+      result.push(...items)
+    })
+    const models = ns.listDataModels()
+    models.forEach((child) => {
+      const items = this.deleteDataModelAnalysis(child.key, rootKey)
+      result.push(...items)
+    })
+    return result
+  }
+
+  protected deleteDataModelAnalysis(key: string, rootKey: string): ImpactItem[] {
+    const result: ImpactItem[] = []
+    const model = this.root.findDataModel(key)
+    if (!model) {
+      return result
+    }
+    result.push({
+      key: model.key,
+      kind: model.kind,
+      type: 'delete',
+      impact: `The ${model.info.renderLabel} ${this.kindToLabel(DataModelKind)} will be deleted.`,
+      blocking: false,
+    })
+    model.entities.forEach((child) => {
+      const items = this.deleteEntityAnalysis(child.key, rootKey)
+      result.push(...items)
+    })
+    return result
+  }
+
+  protected deleteEntityAnalysis(key: string, rootKey: string): ImpactItem[] {
+    const result: ImpactItem[] = []
+    const entity = this.root.findEntity(key)
+    if (!entity) {
+      return result
+    }
+    result.push({
+      key: entity.key,
+      kind: entity.kind,
+      type: 'delete',
+      impact: `The ${entity.info.renderLabel} ${this.kindToLabel(DataEntityKind)} will be deleted.`,
+      blocking: false,
+    })
+    // We need to know whether the entity is a parent of another entity
+    const children = this.root.definitions.entities.filter((domainEntity) => {
+      if (domainEntity.key === entity.key) {
+        // ignore self
+        return false
+      }
+      if (!domainEntity.parents.includes(entity.key)) {
+        // no relationship
+        return false
+      }
+      if (domainEntity.isChildOf(rootKey)) {
+        // No need to include this parent as it itself is being deleted
+        return false
+      }
+      // the entity has a parent-child relationship to the deleted entity.
+      return true
+    })
+    if (children.length) {
+      children.forEach((child) => {
+        result.push({
+          key: child.key,
+          kind: child.kind,
+          type: 'delete',
+          impact: `The ${child.info.renderLabel} ${this.kindToLabel(DataEntityKind)} will become an orphan because it is a child of ${entity.info.renderLabel}.`,
+          resolution: `The ${entity.info.renderLabel} will be removed as the parent parent of ${child.info.renderLabel}.`,
+          blocking: true,
+          relationship: 'child',
+        })
+      })
+      this.report.canProceed = false
+    }
+    // We need to know whether there's another entity that has an association to this entity.
+    const inAssociations = this.root.definitions.associations.filter((association) => {
+      return association.targets.some((item) => {
+        if (item.key === entity.key) {
+          const related = association.getParentInstance()
+          if (!related) {
+            return false
+          }
+          if (related.isChildOf(rootKey)) {
+            // No need to include this association as the related entity itself is being deleted
+            return false
+          }
+          return true
+        }
+        return false
+      })
+    })
+    if (inAssociations.length) {
+      inAssociations.forEach((association) => {
+        result.push({
+          key: association.key,
+          kind: association.kind,
+          type: 'delete',
+          impact: `The ${association.info.renderLabel} ${this.kindToLabel(DataAssociationKind)} will be broken because it has a target to ${entity.info.renderLabel}.`,
+          resolution: `The ${association.info.renderLabel} ${this.kindToLabel(DataAssociationKind)} will be removed from ${entity.info.renderLabel}.`,
+          blocking: true,
+        })
+      })
+      this.report.canProceed = false
+    }
+    entity.properties.forEach((child) => {
+      const items = this.deletePropertyAnalysis(child.key)
+      result.push(...items)
+    })
+    entity.associations.forEach((child) => {
+      const items = this.deleteAssociationAnalysis(child.key)
+      result.push(...items)
+    })
+    return result
+  }
+
+  protected deletePropertyAnalysis(key: string): ImpactItem[] {
+    const result: ImpactItem[] = []
+    const property = this.root.findProperty(key)
+    if (!property) {
+      return result
+    }
+    result.push({
+      key: property.key,
+      kind: property.kind,
+      type: 'delete',
+      impact: `The ${property.info.renderLabel} ${this.kindToLabel(DataPropertyKind)} will be deleted.`,
+      blocking: false,
+    })
+    return result
+  }
+
+  protected deleteAssociationAnalysis(key: string): ImpactItem[] {
+    const result: ImpactItem[] = []
+    const association = this.root.findAssociation(key)
+    if (!association) {
+      return result
+    }
+    result.push({
+      key: association.key,
+      kind: association.kind,
+      type: 'delete',
+      impact: `The ${association.info.renderLabel} ${this.kindToLabel(DataAssociationKind)} will be deleted.`,
+      blocking: false,
+    })
+    return result
+  }
+
+  protected kindToLabel(kind: ImpactKinds): string {
+    switch (kind) {
+      case DataNamespaceKind:
+        return 'namespace'
+      case DataEntityKind:
+        return 'entity'
+      case DataModelKind:
+        return 'data model'
+      case DataPropertyKind:
+        return 'property'
+      case DataAssociationKind:
+        return 'association'
+      default:
+        return 'unknown'
+    }
+  }
+}

package/src/modeling/types.ts

@@ -0,0 +1,13 @@
+export interface DataDomainRemoveOptions {
+  /**
+   * When true, the object will be forcebly removed.
+   * The resolution defined in the `ImpactResolution` class will be applied.
+   *
+   * For example, when removing an entity that is a parent to another entity, it will
+   * removed itself as a parent from the child entity.
+   *
+   * Note, this option should only be used when the ImpactAnalysis has been performed
+   * and the user was informed of the impact.
+   */
+  force?: boolean
+}

package/tests/servers/ExpressServer.ts

@@ -24,6 +24,7 @@ export class ExpressServer {
     app.disable('etag')
     app.disable('x-powered-by')
     app.set('trust proxy', true)
+    app.set('query parser', 'extended')
     this.setupRoutes()
   }
 

package/tests/servers/express-routes/BaseApi.ts

@@ -19,7 +19,7 @@ export class BaseApi {
    * @param router Express app.
    */
   setCors(router: Router): void {
-    router.options('*', cors(this._processCors))
+    router.options('*splat', cors(this._processCors))
   }
 
   /**

package/tests/servers/express-routes/TestsApi.ts

@@ -43,5 +43,5 @@ class TestApiRoute extends BaseApi {
 const api = new TestApiRoute()
 api.setCors(router)
 const checkCorsFn = api._processCors
-router.post('/', cors(checkCorsFn), api.createTest.bind(api))
 router.get('/', cors(checkCorsFn), api.listTest.bind(api))
+router.post('/', cors(checkCorsFn), api.createTest.bind(api))

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

@@ -643,3 +643,76 @@ test.group('DataAssociation Multiple targets', (g) => {
     assert.deepEqual(a1.targets, [{ key: e2.key }, { key: e3.key }])
   })
 })
+
+test.group('DataAssociation.isChildOf()', (group) => {
+  let root: DataNamespace
+  let n1: DataNamespace
+  let n2: DataNamespace
+  let m1: DataModel
+  let m2: DataModel
+  let e1: DataEntity
+  let e2: DataEntity
+  let a1: DataAssociation
+  let a2: DataAssociation
+  let a3: DataAssociation
+
+  group.each.setup(() => {
+    root = new DataNamespace()
+    n1 = root.addNamespace('n1')
+    n2 = n1.addNamespace('n2')
+    m1 = root.addDataModel('m1')
+    m2 = n1.addDataModel('m2')
+    e1 = m1.addEntity('e1')
+    e2 = m2.addEntity('e2')
+    a1 = e1.addNamedAssociation('a1')
+    a2 = e2.addNamedAssociation('a2')
+    a3 = n2.addDataModel('m3').addEntity('e3').addNamedAssociation('a3')
+  })
+
+  test('returns false when called on an association not in an entity', ({ assert }) => {
+    const a4 = new DataAssociation(root)
+    const result = a4.isChildOf('some-key')
+    assert.isFalse(result)
+  })
+
+  test('returns false when called on self', ({ assert }) => {
+    const result = a2.isChildOf(a2.key)
+    assert.isFalse(result)
+  })
+
+  test('returns true when called on a direct parent', ({ assert }) => {
+    const result = a2.isChildOf(e2.key)
+    assert.isTrue(result)
+  })
+
+  test('returns true when called on a grandparent', ({ assert }) => {
+    const result = a3.isChildOf(root.key)
+    assert.isTrue(result)
+  })
+
+  test('returns false when called on a sibling', ({ assert }) => {
+    const a4 = e1.addNamedAssociation('a4')
+    const result = a1.isChildOf(a4.key)
+    assert.isFalse(result)
+  })
+
+  test('returns false when called on a child', ({ assert }) => {
+    const result = e2.isChildOf(a2.key)
+    assert.isFalse(result)
+  })
+
+  test('returns false when called on a non-existent namespace', ({ assert }) => {
+    const result = a2.isChildOf('non-existent-key')
+    assert.isFalse(result)
+  })
+
+  test('returns true when called on a grandparent', ({ assert }) => {
+    const result = a3.isChildOf(n1.key)
+    assert.isTrue(result)
+  })
+
+  test('returns true when called on a data model in the same namespace', ({ assert }) => {
+    const result = a1.isChildOf(m1.key)
+    assert.isTrue(result)
+  })
+})