@khester/create-dynamics-app 1.0.8 → 1.1.0

package/templates/dynamics-365-starter/src/models/BaseEntity.ts

@@ -0,0 +1,204 @@
+import { IApiService } from '@khester/dynamics-ui-api-client';
+
+/**
+ * Abstract base class for all entity models in the system.
+ * Provides common CRUD operations and validation patterns.
+ */
+export abstract class BaseEntity {
+  /**
+   * Validates the entity instance.
+   * @returns True if valid, throws error if invalid
+   */
+  abstract validate(): boolean;
+
+  /**
+   * Creates a new entity record in Dynamics 365.
+   * @param apiService The API service instance
+   * @param entity The entity instance to create
+   * @param entityName The entity collection name
+   * @param loggerContext Optional logger context for debugging
+   * @returns Promise resolving to the created entity
+   */
+  protected static async createEntity<T extends BaseEntity>(
+    apiService: IApiService,
+    entity: T,
+    entityName: string,
+    loggerContext?: string
+  ): Promise<T> {
+    try {
+      entity.validate();
+
+      const result = await apiService.createRecord(entityName, entity);
+
+      if (loggerContext) {
+        console.log(`${loggerContext}: Entity created successfully`, result);
+      }
+
+      return result as T;
+    } catch (error) {
+      const errorMessage = `Error creating ${entityName}: ${error}`;
+      if (loggerContext) {
+        console.error(`${loggerContext}: ${errorMessage}`);
+      }
+      throw new Error(errorMessage);
+    }
+  }
+
+  /**
+   * Updates an existing entity record in Dynamics 365.
+   * @param apiService The API service instance
+   * @param entityId The ID of the entity to update
+   * @param entity The entity instance with updated values
+   * @param entityName The entity collection name
+   * @param primaryKey The primary key field name
+   * @param loggerContext Optional logger context for debugging
+   * @returns Promise resolving to the updated entity
+   */
+  protected static async updateEntity<T extends BaseEntity>(
+    apiService: IApiService,
+    entityId: string,
+    entity: T,
+    entityName: string,
+    primaryKey: string,
+    loggerContext?: string
+  ): Promise<T> {
+    try {
+      entity.validate();
+
+      // Remove the primary key from the update payload
+      const updatePayload = { ...entity };
+      delete (updatePayload as any)[primaryKey];
+
+      await apiService.updateRecord(entityName, entityId, updatePayload);
+
+      if (loggerContext) {
+        console.log(`${loggerContext}: Entity updated successfully`);
+      }
+
+      // Return the entity with the ID set
+      (entity as any)[primaryKey] = entityId;
+      return entity;
+    } catch (error) {
+      const errorMessage = `Error updating ${entityName}: ${error}`;
+      if (loggerContext) {
+        console.error(`${loggerContext}: ${errorMessage}`);
+      }
+      throw new Error(errorMessage);
+    }
+  }
+
+  /**
+   * Deletes an entity record from Dynamics 365.
+   * @param apiService The API service instance
+   * @param entityId The ID of the entity to delete
+   * @param entityName The entity collection name
+   * @param loggerContext Optional logger context for debugging
+   * @returns Promise resolving when deletion is complete
+   */
+  protected static async deleteEntity(
+    apiService: IApiService,
+    entityId: string,
+    entityName: string,
+    loggerContext?: string
+  ): Promise<void> {
+    try {
+      await apiService.deleteRecord(entityName, entityId);
+
+      if (loggerContext) {
+        console.log(`${loggerContext}: Entity deleted successfully`);
+      }
+    } catch (error) {
+      const errorMessage = `Error deleting ${entityName}: ${error}`;
+      if (loggerContext) {
+        console.error(`${loggerContext}: ${errorMessage}`);
+      }
+      throw new Error(errorMessage);
+    }
+  }
+
+  /**
+   * Retrieves entities based on a FetchXML filter.
+   * @param apiService The API service instance
+   * @param entityName The entity collection name
+   * @param fetchXml The FetchXML query
+   * @param EntityClass The entity class constructor
+   * @param loggerContext Optional logger context for debugging
+   * @returns Promise resolving to an array of entities
+   */
+  protected static async retrieveEntitiesByFilter<T extends BaseEntity>(
+    apiService: IApiService,
+    entityName: string,
+    fetchXml: string,
+    EntityClass: new (data: any) => T,
+    loggerContext?: string
+  ): Promise<T[]> {
+    try {
+      const result = await apiService.retrieveMultipleRecords(
+        entityName,
+        fetchXml
+      );
+
+      const entities = result.entities.map(
+        (record: any) => new EntityClass(record)
+      );
+
+      if (loggerContext) {
+        console.log(`${loggerContext}: Retrieved ${entities.length} entities`);
+      }
+
+      return entities;
+    } catch (error) {
+      const errorMessage = `Error retrieving ${entityName} records: ${error}`;
+      if (loggerContext) {
+        console.error(`${loggerContext}: ${errorMessage}`);
+      }
+      throw new Error(errorMessage);
+    }
+  }
+
+  /**
+   * Builds a FetchXML query with proper escaping.
+   * @param entityName The entity name
+   * @param attributes Array of attribute names to retrieve
+   * @param filter Optional filter XML string
+   * @param orderBy Optional order by configuration
+   * @returns FetchXML string
+   */
+  protected static buildFetchXml(
+    entityName: string,
+    attributes: string[],
+    filter?: string,
+    orderBy?: { attribute: string; descending?: boolean }
+  ): string {
+    const attributesXml = attributes
+      .map((attr) => `<attribute name="${attr}" />`)
+      .join('\n    ');
+    const orderXml = orderBy
+      ? `<order attribute="${orderBy.attribute}" descending="${orderBy.descending || false}" />`
+      : '';
+
+    return `<fetch mapping="logical">
+  <entity name="${entityName}">
+    ${attributesXml}
+    ${orderXml}
+    ${filter || ''}
+  </entity>
+</fetch>`;
+  }
+
+  /**
+   * Escapes XML special characters in a string.
+   * @param value The string to escape
+   * @returns Escaped string safe for XML
+   */
+  protected static escapeXml(value: string): string {
+    if (!value) return value;
+
+    return value
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&apos;');
+  }
+}