@api-client/core 0.11.6 → 0.11.8

package/build/src/modeling/ImpactAnalysis.d.ts

@@ -0,0 +1,290 @@
+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 declare class ImpactAnalysis {
+    private report;
+    private root;
+    constructor(root: DataNamespace);
+    /**
+     * 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;
+    protected createDeleteImpact(key: string, kind: ImpactKinds, rootKey: string): ImpactItem[];
+    protected deleteNamespaceAnalysis(key: string, rootKey: string): ImpactItem[];
+    protected deleteDataModelAnalysis(key: string, rootKey: string): ImpactItem[];
+    protected deleteEntityAnalysis(key: string, rootKey: string): ImpactItem[];
+    protected deletePropertyAnalysis(key: string): ImpactItem[];
+    protected deleteAssociationAnalysis(key: string): ImpactItem[];
+    protected kindToLabel(kind: ImpactKinds): string;
+}
+export {};
+//# sourceMappingURL=ImpactAnalysis.d.ts.map

package/build/src/modeling/ImpactAnalysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImpactAnalysis.d.ts","sourceRoot":"","sources":["../../../src/modeling/ImpactAnalysis.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAEvD,MAAM,MAAM,WAAW,GACnB,OAAO,iBAAiB,GACxB,OAAO,cAAc,GACrB,OAAO,aAAa,GACpB,OAAO,gBAAgB,GACvB,OAAO,mBAAmB,CAAA;AAE9B;;GAEG;AACH,UAAU,YAAY;IACpB;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,IAAI,EAAE,WAAW,CAAA;IACjB;;OAEG;IACH,MAAM,EAAE,UAAU,EAAE,CAAA;IACpB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAA;CACpB;AAED,UAAU,UAAU;IAClB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,IAAI,EAAE,QAAQ,CAAA;IACd;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAA;IACjB;;OAEG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgNG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,IAAI,CAAe;gBAEf,IAAI,EAAE,aAAa;IAU/B;;;;;OAKG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,YAAY;IAkB5D,SAAS,CAAC,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE;IAiB3F,SAAS,CAAC,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE;IA0B7E,SAAS,CAAC,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE;IAoB7E,SAAS,CAAC,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE;IAqF1E,SAAS,CAAC,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE;IAgB3D,SAAS,CAAC,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE;IAgB9D,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM;CAgBjD"}