@api-client/core 0.11.11 → 0.12.0

package/src/modeling/legacy/DataImpactAnalysis.ts

@@ -0,0 +1,530 @@
+import {
+  DataNamespaceKind,
+  DataEntityKind,
+  DataModelKind,
+  DataPropertyKind,
+  DataAssociationKind,
+} from '../../models/kinds.js'
+import type { DataNamespace } from './DataNamespace.js'
+
+/**
+ * @deprecated
+ */
+export type DataImpactKinds =
+  | typeof DataNamespaceKind
+  | typeof DataEntityKind
+  | typeof DataModelKind
+  | typeof DataPropertyKind
+  | typeof DataAssociationKind
+
+/**
+ * The impact analysis report
+ * @deprecated
+ */
+export interface DataImpactReport {
+  /**
+   * 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: DataImpactKinds
+  /**
+   * The list of impacted data objects.
+   */
+  impact: DataImpactItem[]
+  /**
+   * 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
+}
+
+/**
+ * @deprecated
+ */
+export interface DataImpactItem {
+  /**
+   * 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
+}
+
+/**
+ * # DomainImpactAnalysis
+ *
+ * The `DomainImpactAnalysis` 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 `DomainImpactAnalysis` class is an `DataImpactReport`.
+ *     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 `DomainImpactAnalysis`, passing the root `DataNamespace` as an argument.
+ *
+ *     ```typescript
+ *     import { DataNamespace } from './DataNamespace';
+ *     import { DomainImpactAnalysis } from './DomainImpactAnalysis';
+ *
+ *     const rootNamespace = new DataNamespace();
+ *     // ... add some data to the namespace
+ *     const analyzer = new DomainImpactAnalysis(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 `DomainImpactAnalysis` 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 `DomainImpactAnalysis` 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" entity will be removed as the parent of the "SpecialProduct" entity.",
+ *       "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 `DomainImpactAnalysis` 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 `DomainImpactAnalysis`
+ *   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 `DomainImpactAnalysis` 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.
+ * @deprecated
+ */
+export class DataImpactAnalysis {
+  private report: DataImpactReport
+  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.
+   * @deprecated
+   */
+  deleteAnalysis(key: string, kind: DataImpactKinds): DataImpactReport {
+    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: DataImpactKinds, rootKey: string): DataImpactItem[] {
+    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): DataImpactItem[] {
+    const result: DataImpactItem[] = []
+    const ns = this.root.findNamespace(key)
+    if (!ns) {
+      return result
+    }
+    result.push({
+      key: ns.key,
+      kind: ns.kind,
+      type: 'delete',
+      impact: `The ${ns.info.getLabel()} ${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): DataImpactItem[] {
+    const result: DataImpactItem[] = []
+    const model = this.root.findDataModel(key)
+    if (!model) {
+      return result
+    }
+    result.push({
+      key: model.key,
+      kind: model.kind,
+      type: 'delete',
+      impact: `The ${model.info.getLabel()} ${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): DataImpactItem[] {
+    const result: DataImpactItem[] = []
+    const entity = this.root.findEntity(key)
+    if (!entity) {
+      return result
+    }
+    result.push({
+      key: entity.key,
+      kind: entity.kind,
+      type: 'delete',
+      impact: `The ${entity.info.getLabel()} ${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) => {
+        const pLabel = entity.info.getLabel()
+        const cLabel = child.info.getLabel()
+        result.push({
+          key: child.key,
+          kind: child.kind,
+          type: 'delete',
+          impact: `The "${cLabel}" ${this.kindToLabel(DataEntityKind)} will become an orphan because it is a child of the "${pLabel}" entity.`,
+          resolution: `The "${pLabel}" entity will be removed as the parent of the "${cLabel}" entity.`,
+          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.getLabel()} ${this.kindToLabel(DataAssociationKind)} will be broken because it has a target to ${entity.info.getLabel()}.`,
+          resolution: `The ${association.info.getLabel()} ${this.kindToLabel(DataAssociationKind)} will be removed from ${entity.info.getLabel()}.`,
+          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): DataImpactItem[] {
+    const result: DataImpactItem[] = []
+    const property = this.root.findProperty(key)
+    if (!property) {
+      return result
+    }
+    result.push({
+      key: property.key,
+      kind: property.kind,
+      type: 'delete',
+      impact: `The ${property.info.getLabel()} ${this.kindToLabel(DataPropertyKind)} will be deleted.`,
+      blocking: false,
+    })
+    return result
+  }
+
+  protected deleteAssociationAnalysis(key: string): DataImpactItem[] {
+    const result: DataImpactItem[] = []
+    const association = this.root.findAssociation(key)
+    if (!association) {
+      return result
+    }
+    result.push({
+      key: association.key,
+      kind: association.kind,
+      type: 'delete',
+      impact: `The ${association.info.getLabel()} ${this.kindToLabel(DataAssociationKind)} will be deleted.`,
+      blocking: false,
+    })
+    return result
+  }
+
+  protected kindToLabel(kind: DataImpactKinds): 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/{DataModel.ts → legacy/DataModel.ts}

@@ -1,16 +1,17 @@
-import { IThing, Thing } from '../models/Thing.js'
-import v4 from '../lib/uuid.js'
+import { IThing, Thing } from '../../models/Thing.js'
+import v4 from '../../lib/uuid.js'
 import { DataEntity, IDataEntity } from './DataEntity.js'
 import type { DataItemAdaptingOptions, DataNamespace } from './DataNamespace.js'
-import { FileBreadcrumb } from '../models/store/File.js'
-import { DataModelKind } from '../models/kinds.js'
-import type { DataDomainRemoveOptions } from './types.js'
+import { FileBreadcrumb } from '../../models/store/File.js'
+import { DataModelKind } from '../../models/kinds.js'
+import type { DataDomainRemoveOptions } from '../types.js'
 
 /**
  * Data model creates a logical structure around data entities.
  * It groups entities that represents a whole schema, like a Product data model
  * can have entities that describe: the product entity, price history entity,
  * product location, etc.
+ * @deprecated
  */
 export interface IDataModel {
   kind: typeof DataModelKind
@@ -33,6 +34,7 @@ export interface IDataModel {
  * It groups entities that represents a whole schema, like a Product data model
  * can have entities that describe: the product entity, price history entity,
  * product location, etc.
+ * @deprecated
  */
 export class DataModel {
   kind = DataModelKind
@@ -231,7 +233,7 @@ export class DataModel {
     const result: FileBreadcrumb[] = []
     result.push({
       key: this.key,
-      name: this.info.name || 'Unnamed data model',
+      name: this.info.getLabel('Unnamed data model'),
       kind: DataModelKind,
     })
     let parent = this.getParentInstance()
@@ -239,13 +241,13 @@ export class DataModel {
       result.push({
         key: parent.key,
         kind: parent.kind,
-        name: parent.info.name || 'Unnamed namespace',
+        name: parent.info.getLabel('Unnamed namespace'),
       })
       parent = parent.getParentInstance()
     }
     result.push({
       key: this.root.key,
-      name: this.root.info.name || 'Unnamed namespace',
+      name: this.root.info.getLabel('Unnamed data domain'),
       kind: this.root.kind,
     })
     return result.reverse()

package/src/modeling/{DataNamespace.ts → legacy/DataNamespace.ts}

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-this-alias */
-import { IThing, Thing } from '../models/Thing.js'
+import { IThing, Thing } from '../../models/Thing.js'
 import { IDataAssociation, DataAssociation, AssociationTarget } from './DataAssociation.js'
 import { IDataEntity, DataEntity } from './DataEntity.js'
 import { IDataModel, DataModel } from './DataModel.js'
@@ -10,19 +10,27 @@ import {
   DataEntityKind,
   DataPropertyKind,
   DataAssociationKind,
-} from '../models/kinds.js'
-import v4 from '../lib/uuid.js'
-import type { DataDomainRemoveOptions } from './types.js'
+} from '../../models/kinds.js'
+import v4 from '../../lib/uuid.js'
+import type { DataDomainRemoveOptions } from '../types.js'
 
+/**
+ * @deprecated
+ */
 type ItemKind = typeof DataNamespaceKind | typeof DataModelKind
 
+/**
+ * @deprecated
+ */
 export interface DataItemAdaptingOptions {
   /**
    * The index at which to adapt the item.
    */
   index?: number
 }
-
+/**
+ * @deprecated
+ */
 interface IDataDefinitions {
   models?: IDataModel[]
   entities?: IDataEntity[]
@@ -36,6 +44,9 @@ interface IDataDefinitions {
   foreign?: ForeignNamespace[]
 }
 
+/**
+ * @deprecated
+ */
 interface DataDefinitions {
   models: DataModel[]
   // @todo: This should be a map of entities with a key of the entity key.
@@ -61,6 +72,7 @@ interface DataDefinitions {
  * Each foreign namespace is resolved to a specific version.
  * This makes sure that the local data are always referencing an existing
  * entity as breaking changes should be resolved when upgrading a version.
+ * @deprecated
  */
 interface ForeignNamespace {
   key: string
@@ -69,6 +81,7 @@ interface ForeignNamespace {
 
 /**
  * Data namespace is a logical description of the hierarchy in the data.
+ * @deprecated
  */
 export interface IDataNamespace {
   kind: typeof DataNamespaceKind
@@ -93,6 +106,7 @@ export interface IDataNamespace {
 /**
  * Data item is a reference to an object in the top namespace definitions
  * to the namespace items.
+ * @deprecated
  */
 export interface IDataItem {
   /**
@@ -105,6 +119,9 @@ export interface IDataItem {
   key: string
 }
 
+/**
+ * @deprecated
+ */
 export class DataItem implements IDataItem {
   kind: ItemKind = DataModelKind
 
@@ -187,6 +204,7 @@ export class DataItem implements IDataItem {
 
 /**
  * Data namespace is a logical description of the hierarchy in the data.
+ * @deprecated
  */
 export class DataNamespace {
   kind = DataNamespaceKind