@adobe/spacecat-shared-data-access 1.60.2 → 1.61.0

package/src/v2/models/base/base.collection.js

@@ -18,15 +18,15 @@ import {
 
 import { ElectroValidationError } from 'electrodb';
 
-import { createAccessors } from '../../util/accessor.utils.js';
+import DataAccessError from '../../errors/data-access.error.js';
 import ValidationError from '../../errors/validation.error.js';
+import { createAccessors } from '../../util/accessor.utils.js';
 import { guardId } from '../../util/guards.js';
 import {
   entityNameToAllPKValue,
   isNonEmptyArray,
   removeElectroProperties,
 } from '../../util/util.js';
-import { INDEX_TYPES } from './constants.js';
 
 function isValidParent(parent, child) {
   if (!hasText(parent.entityName)) {
@@ -38,30 +38,6 @@ function isValidParent(parent, child) {
   return child.record?.[foreignKey] === parent.record?.[foreignKey];
 }
 
-/**
- * Finds the index name by the keys provided. The index is searched
- * keys to match the combination of partition and sort keys. If no
- * index is found, we fall back to the "all" index, then the "primary".
- * @param {Schema} schema - The schema to search for the index.
- * @param {Object} keys - The keys to search for.
- * @return {*|string} - The index name.
- */
-function findIndexNameByKeys(schema, keys) {
-  const keyNames = Object.keys(keys);
-
-  const index = schema.findIndexBySortKeys(keyNames);
-  if (index) {
-    return index.index;
-  }
-
-  const allIndex = schema.findIndexByType(INDEX_TYPES.ALL);
-  if (allIndex) {
-    return allIndex.index;
-  }
-
-  return INDEX_TYPES.PRIMARY;
-}
-
 /**
  * BaseCollection - A base class for managing collections of entities in the application.
  * This class uses ElectroDB to interact with entities and provides common functionality
@@ -93,6 +69,12 @@ class BaseCollection {
     this.#initializeCollectionMethods();
   }
 
+  #logAndThrowError(message, cause) {
+    const error = new DataAccessError(message, this, cause);
+    this.log.error(`Base Collection Error [${this.entityName}]`, error);
+    throw error;
+  }
+
   /**
    * Initialize collection methods for each "by..." index defined in the entity schema.
    * For each index that starts with "by", we:
@@ -146,72 +128,142 @@ class BaseCollection {
     return records.map((record) => this.#createInstance(record));
   }
 
+  /**
+   * Clears the accessor cache for the entity. This method is called when the entity is
+   * updated or removed to ensure that the cache is invalidated.
+   * @private
+   */
   #invalidateCache() {
     this._accessorCache = {};
   }
 
+  /**
+   * Internal on-create handler. This method is called after the create method has successfully
+   * created an entity. It will call the on-create handler defined in the subclass and handles
+   * any errors that occur.
+   * @param {BaseModel} item - The created entity.
+   * @return {Promise<void>}
+   * @async
+   * @private
+   */
+  async #onCreate(item) {
+    try {
+      await this._onCreate(item);
+    } catch (error) {
+      this.log.error('On-create handler failed', error);
+    }
+  }
+
+  /**
+   * Internal on-create-many handler. This method is called after the createMany method has
+   * successfully created entities. It will call the on-create-many handler defined in the
+   * subclass and handles any errors that occur.
+   * @param {Array<BaseModel>} createdItems - The created entities.
+   * @param {{ item: Object, error: ValidationError }[]} errorItems - Items that failed validation.
+   * @return {Promise<void>}
+   * @async
+   * @private
+   */
+  async #onCreateMany({ createdItems, errorItems }) {
+    try {
+      await this._onCreateMany({ createdItems, errorItems });
+    } catch (error) {
+      this.log.error('On-create-many handler failed', error);
+    }
+  }
+
+  /**
+   * Handler for the create method. This method is
+   * called after the create method has successfully created an entity.
+   * @param {BaseModel} item - The created entity.
+   * @return {Promise<void>}
+   * @async
+   * @protected
+   */
+  // eslint-disable-next-line class-methods-use-this,@typescript-eslint/no-unused-vars
+  async _onCreate(item) {
+    // no-op
+  }
+
+  /**
+   * Handler for the createMany method. This method is
+   * called after the createMany method has successfully created entities.
+   * @param {Array<BaseModel>} createdItems - The created entities.
+   * @param {{ item: Object, error: ValidationError }[]} errorItems - Items that failed validation.
+   * @return {Promise<void>}
+   * @async
+   * @protected
+   */
+  // eslint-disable-next-line class-methods-use-this,@typescript-eslint/no-unused-vars
+  async _onCreateMany({ createdItems, errorItems }) {
+    // no-op
+  }
+
   /**
    * General method to query entities by index keys. This method is used by other
    * query methods to perform the actual query operation. It will use the index keys
    * to find the appropriate index and query the entities. The query result will be
    * transformed into model instances.
+   *
    * @private
+   * @async
    * @param {Object} keys - The index keys to use for the query.
    * @param {Object} options - Additional options for the query.
    * @returns {Promise<BaseModel|Array<BaseModel>|null>} - The query result.
+   * @throws {DataAccessError} - Throws an error if the keys are not provided,
+   * if options are invalid or if the query operation fails.
    */
   async #queryByIndexKeys(keys, options = {}) {
     if (!isNonEmptyObject(keys)) {
-      const message = `Failed to query [${this.entityName}]: keys are required`;
-      this.log.error(message);
-      throw new Error(message);
+      return this.#logAndThrowError(`Failed to query [${this.entityName}]: keys are required`);
     }
 
     if (!isObject(options)) {
-      const message = `Failed to query [${this.entityName}]: options must be an object`;
-      this.log.error(message);
-      throw new Error(message);
+      return this.#logAndThrowError(`Failed to query [${this.entityName}]: options must be an object`);
     }
 
-    const indexName = options.index || findIndexNameByKeys(this.schema, keys);
+    const indexName = options.index || this.schema.findIndexNameByKeys(keys);
     const index = this.entity.query[indexName];
 
     if (!index) {
-      const message = `Failed to query [${this.entityName}]: query proxy [${indexName}] not found`;
-      this.log.error(message);
-      throw new Error(message);
+      this.#logAndThrowError(`Failed to query [${this.entityName}]: query proxy [${indexName}] not found`);
     }
 
-    const queryOptions = {
-      order: options.order || 'desc',
-      ...options.limit && { limit: options.limit },
-      ...options.attributes && { attributes: options.attributes },
-    };
-
-    let query = index(keys);
-
-    if (isObject(options.between)) {
-      query = query.between(
-        { [options.between.attribute]: options.between.start },
-        { [options.between.attribute]: options.between.end },
-      );
-    }
+    try {
+      const queryOptions = {
+        order: options.order || 'desc',
+        ...options.limit && { limit: options.limit },
+        ...options.attributes && { attributes: options.attributes },
+      };
+
+      let query = index(keys);
+
+      if (isObject(options.between)) {
+        query = query.between(
+          { [options.between.attribute]: options.between.start },
+          { [options.between.attribute]: options.between.end },
+        );
+      }
 
-    const records = await query.go(queryOptions);
+      const records = await query.go(queryOptions);
 
-    if (options.limit === 1) {
-      if (records.data?.length === 0) {
-        return null;
+      if (options.limit === 1) {
+        if (records.data?.length === 0) {
+          return null;
+        }
+        return this.#createInstance(records.data[0]);
+      } else {
+        return this.#createInstances(records.data);
       }
-      return this.#createInstance(records.data[0]);
-    } else {
-      return this.#createInstances(records.data);
+    } catch (error) {
+      return this.#logAndThrowError('Failed to query', error);
     }
   }
 
   /**
    * Finds all entities in the collection. Requires an index named "all" with a partition key
    * named "pk" with a static value of "ALL_<ENTITYNAME>".
+   * @async
    * @param {Object} [sortKeys] - The sort keys to use for the query.
    * @param {Object} [options] - Additional options for the query.
    * @return {Promise<BaseModel|Array<BaseModel>|null>}
@@ -237,18 +289,20 @@ class BaseCollection {
   }
 
   /**
-   * Finds a single entity from the "all" index. Requires an index named "all" with a partition key
-   * named "pk" with a static value of "ALL_<ENTITYNAME>".
+   * Finds a single entity from the "all" index. Requires an "all" index to be added to the
+   * entity schema via the schema builder.
+   * @async
    * @param {Object} [sortKeys] - The sort keys to use for the query.
-   * @param {{index?: string, attributes?: string[], order?: string}} [options] -
+   * @param {QueryOptions} [options] - Additional options for the query.
    * Additional options for the query.
-   * @return {Promise<BaseModel|Array<BaseModel>|null>}
+   * @return {Promise<BaseModel|null>}
+   * @throws {DataAccessError} - Throws an error if the sort keys are not provided.
    */
   async findByAll(sortKeys = {}, options = {}) {
     if (!isObject(sortKeys)) {
       const message = `Failed to find by all [${this.entityName}]: sort keys must be an object`;
       this.log.error(message);
-      throw new Error(message);
+      throw new DataAccessError(message);
     }
 
     const keys = { pk: entityNameToAllPKValue(this.entityName), ...sortKeys };
@@ -256,12 +310,13 @@ class BaseCollection {
   }
 
   /**
-   * Finds an entity by its ID.
+   * Finds an entity by its ID. This will only work if the entity's schema
+   * did not override the main table primary key via schema builder.
    * @async
    * @param {string} id - The unique identifier of the entity to be found.
    * @returns {Promise<BaseModel|null>} - A promise that resolves to an instance of
    * the model if found, otherwise null.
-   * @throws {Error} - Throws an error if the ID is not provided.
+   * @throws {ValidationError} - Throws an error if the ID is not provided.
    */
   async findById(id) {
     guardId(this.idName, id, this.entityName);
@@ -276,6 +331,7 @@ class BaseCollection {
    * @param {Object} keys - The index keys to use for the query.
    * @param {{index?: string, attributes?: string[]}} [options] - Additional options for the query.
    * @returns {Promise<BaseModel|null>} - A promise that resolves to the model instance or null.
+   * @throws {DataAccessError} - Throws an error if retrieving the entity fails.
    * @async
    */
   async findByIndexKeys(keys, options = {}) {
@@ -289,13 +345,14 @@ class BaseCollection {
    * @async
    * @param {Object} item - The data for the entity to be created.
    * @returns {Promise<BaseModel>} - A promise that resolves to the created model instance.
-   * @throws {Error} - Throws an error if the data is invalid or if the creation process fails.
+   * @throws {DataAccessError} - Throws an error if the data is invalid or if the
+   * creation process fails.
    */
   async create(item) {
     if (!isNonEmptyObject(item)) {
       const message = `Failed to create [${this.entityName}]: data is required`;
       this.log.error(message);
-      throw new Error(message);
+      throw new DataAccessError(message);
     }
 
     try {
@@ -303,11 +360,11 @@ class BaseCollection {
       const instance = this.#createInstance(record.data);
 
       this.#invalidateCache();
+      await this.#onCreate(instance);
 
       return instance;
     } catch (error) {
-      this.log.error(`Failed to create [${this.entityName}]`, error);
-      throw error;
+      return this.#logAndThrowError('Failed to create', error);
     }
   }
 
@@ -345,14 +402,14 @@ class BaseCollection {
    * @return {Promise<{ createdItems: BaseModel[],
    * errorItems: { item: Object, error: ValidationError }[] }>} - A promise that resolves to
    * an object containing the created items and any items that failed validation.
-   * @throws {ValidationError} - Throws a validation error if any of the items has validation
-   * failures.
+   * @throws {DataAccessError} - Throws an error if the items are not provided or if the
+   * creation process fails.
    */
   async createMany(newItems, parent = null) {
     if (!isNonEmptyArray(newItems)) {
       const message = `Failed to create many [${this.entityName}]: items must be a non-empty array`;
       this.log.error(message);
-      throw new Error(message);
+      throw new DataAccessError(message);
     }
 
     try {
@@ -383,10 +440,11 @@ class BaseCollection {
 
       this.log.info(`Created ${createdItems.length} items for [${this.entityName}]`);
 
+      await this.#onCreateMany({ createdItems, errorItems });
+
       return { createdItems, errorItems };
     } catch (error) {
-      this.log.error(`Failed to create many [${this.entityName}]`, error);
-      throw error;
+      return this.#logAndThrowError('Failed to create many', error);
     }
   }
 
@@ -396,28 +454,29 @@ class BaseCollection {
    * @async
    * @param {Array<BaseModel>} items - An array of model instances to be updated.
    * @return {Promise<void>} - A promise that resolves when the update operation is complete.
-   * @throws {Error} - Throws an error if the update operation fails.
+   * @throws {DataAccessError} - Throws an error if the items are not provided or if the
+   * update operation fails.
+   *
    * @protected
    */
   async _saveMany(items) {
     if (!isNonEmptyArray(items)) {
       const message = `Failed to save many [${this.entityName}]: items must be a non-empty array`;
       this.log.error(message);
-      throw new Error(message);
+      throw new DataAccessError(message);
     }
 
     try {
       const updates = items.map((item) => item.record);
       const response = await this.entity.put(updates).go();
 
-      this.#invalidateCache();
-
       if (response.unprocessed) {
         this.log.error(`Failed to process all items in batch write for [${this.entityName}]: ${JSON.stringify(response.unprocessed)}`);
       }
+
+      return this.#invalidateCache();
     } catch (error) {
-      this.log.error(`Failed to save many [${this.entityName}]`, error);
-      throw error;
+      return this.#logAndThrowError('Failed to save many', error);
     }
   }
 
@@ -426,22 +485,26 @@ class BaseCollection {
    * delete operation. This operation does not remove dependent records.
    * @param {Array<string>} ids - An array of IDs to remove.
    * @return {Promise<void>} - A promise that resolves when the removal operation is complete.
-   * @throws {Error} - Throws an error if the IDs are not provided or if the
+   * @throws {DataAccessError} - Throws an error if the IDs are not provided or if the
    * removal operation fails.
    */
   async removeByIds(ids) {
     if (!isNonEmptyArray(ids)) {
       const message = `Failed to remove [${this.entityName}]: ids must be a non-empty array`;
       this.log.error(message);
-      throw new Error(message);
+      throw new DataAccessError(message);
     }
 
-    this.log.info(`Removing ${ids.length} items for [${this.entityName}]`);
-    // todo: consider removing dependent records
+    try {
+      this.log.info(`Removing ${ids.length} items for [${this.entityName}]`);
+      // todo: consider removing dependent records
 
-    await this.entity.delete(ids.map((id) => ({ [this.idName]: id }))).go();
+      await this.entity.delete(ids.map((id) => ({ [this.idName]: id }))).go();
 
-    this.#invalidateCache();
+      return this.#invalidateCache();
+    } catch (error) {
+      return this.#logAndThrowError('Failed to remove by IDs', error);
+    }
   }
 }
 

package/src/v2/models/base/base.model.js

@@ -12,6 +12,7 @@
 
 import { isNonEmptyObject } from '@adobe/spacecat-shared-utils';
 
+import { DataAccessError } from '../../errors/index.js';
 import { createAccessors } from '../../util/accessor.utils.js';
 import Patcher from '../../util/patcher.js';
 import {
@@ -85,6 +86,18 @@ class BaseModel {
     });
   }
 
+  /**
+   * Initializes the attributes for the current entity. This method is called during the
+   * construction of the entity instance to set up the getter and setter methods for
+   * accessing and modifying the entity attributes. The getter and setter methods are
+   * automatically generated based on the entity schema. If the schema allows updates,
+   * setter methods are generated for each attribute that is not read-only.
+   *
+   * If the attribute is a reference, the setter method will tell the patcher
+   * to validate that the value is a valid UUID.
+   *
+   * @private
+   */
   #initializeAttributes() {
     const attributes = this.schema.getAttributes();
 
@@ -95,7 +108,6 @@ class BaseModel {
     for (const [name, attr] of Object.entries(attributes)) {
       const capitalized = capitalize(name);
       const getterMethodName = `get${capitalized}`;
-      const setterMethodName = `set${capitalized}`;
       const isReference = this.schema
         .getReferencesByType(Reference.TYPES.BELONGS_TO)
         .some((ref) => ref.getTarget() === idNameToEntityName(name));
@@ -104,19 +116,35 @@ class BaseModel {
         this[getterMethodName] = () => this.record[name];
       }
 
-      if (!this[setterMethodName] && !attr.readOnly) {
-        this[setterMethodName] = (value) => {
-          this.patcher.patchValue(name, value, isReference);
-          return this;
-        };
+      if (this.schema.allowsUpdates()) {
+        const setterMethodName = `set${capitalized}`;
+
+        if (!this[setterMethodName] && !attr.readOnly) {
+          this[setterMethodName] = (value) => {
+            this.patcher.patchValue(name, value, isReference);
+            return this;
+          };
+        }
       }
     }
   }
 
+  /**
+   * Clears the accessor cache for the entity. This method is called when the entity is
+   * updated or removed to ensure that the cache is invalidated.
+   * @private
+   */
   #invalidateCache() {
     this._accessorCache = {};
   }
 
+  /**
+   * Fetches the associated entities for the current entity based on the type of relationship.
+   * This is used for the remove operation to remove dependent entities associated with the
+   * current entity.
+   * @return {Promise<Array>}
+   * @private
+   */
   async #fetchDependents() {
     const promises = [];
 
@@ -184,18 +212,41 @@ class BaseModel {
    * removeDependentss flag is set to true in the reference definition.
    *
    * Dependents are removed by calling the remove method on each dependent entity, which in turn
-   * will also remove any dependent entities associated with the dependent entity. This may result
-   * in a cascade effect where multiple entities are removed. Consider the destructive
-   * and performance implications before using this method.
+   * will also remove any dependent entities associated with the dependent entity. For dependent
+   * entities the allowRemove flag is ignored.
+   *
+   * Removal of entities with many dependents can be a costly operation, as each dependent entity
+   * will be removed individually. This can result in a large number of database operations, which
+   * can impact performance. It is recommended to use this method with caution, especially when
+   * removing entities with many dependents.
+   *
    * @async
    * @returns {Promise<BaseModel>} - A promise that resolves to the current instance of the entity
    * after it and its dependents have been removed.
-   * @throws {Error} - Throws an error if the removal fails.
+   * @throws {DataAccessError} - Throws an error if the schema does not allow removal
+   * or if the removal operation fails.
    */
   async remove() {
+    if (!this.schema.allowsRemove()) {
+      throw new DataAccessError(`The entity ${this.schema.getModelName()} does not allow removal`);
+    }
+
+    return this._remove();
+  }
+
+  /**
+   * Internal remove method that removes the current entity from the database and its dependents.
+   * This method does not check if the schema allows removal in order to be able to remove
+   * dependents even if the schema does not allow removal.
+   * @return {Promise<BaseModel>}
+   * @throws {DataAccessError} - Throws an error if the removal operation fails.
+   * @protected
+   */
+  async _remove() {
     try {
       const dependents = await this.#fetchDependents();
-      const removePromises = dependents.map((dependent) => dependent.remove());
+      // eslint-disable-next-line no-underscore-dangle
+      const removePromises = dependents.map((dependent) => dependent._remove());
       removePromises.push(this.entity.remove({ [this.idName]: this.getId() }).go());
 
       this.log.info(`Removing entity ${this.entityName} with ID ${this.getId()} and ${dependents.length} dependents`);
@@ -207,7 +258,11 @@ class BaseModel {
       return this;
     } catch (error) {
       this.log.error('Failed to remove record', error);
-      throw error;
+      throw new DataAccessError(
+        `Failed to remove entity ${this.entityName} with ID ${this.getId()}`,
+        this,
+        error,
+      );
     }
   }
 
@@ -217,7 +272,7 @@ class BaseModel {
    * @async
    * @returns {Promise<BaseModel>} - A promise that resolves to the current instance of the entity
    * after it has been saved.
-   * @throws {Error} - Throws an error if the save operation fails.
+   * @throws {DataAccessError} - Throws an error if the save operation fails.
    */
   async save() {
     // todo: validate associations
@@ -230,7 +285,11 @@ class BaseModel {
       return this;
     } catch (error) {
       this.log.error('Failed to save record', error);
-      throw error;
+      throw new DataAccessError(
+        `Failed to to save entity ${this.entityName} with ID ${this.getId()}`,
+        this,
+        error,
+      );
     }
   }
 

package/src/v2/models/base/entity.registry.js

@@ -10,6 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
+import { DataAccessError } from '../../errors/index.js';
 import { collectionNameToEntityName, decapitalize } from '../../util/util.js';
 
 import ApiKeyCollection from '../api-key/api-key.collection.js';
@@ -19,6 +20,7 @@ import ExperimentCollection from '../experiment/experiment.collection.js';
 import ImportJobCollection from '../import-job/import-job.collection.js';
 import ImportUrlCollection from '../import-url/import-url.collection.js';
 import KeyEventCollection from '../key-event/key-event.collection.js';
+import LatestAuditCollection from '../latest-audit/latest-audit.collection.js';
 import OpportunityCollection from '../opportunity/opportunity.collection.js';
 import OrganizationCollection from '../organization/organization.collection.js';
 import SiteCandidateCollection from '../site-candidate/site-candidate.collection.js';
@@ -33,6 +35,7 @@ import ExperimentSchema from '../experiment/experiment.schema.js';
 import ImportJobSchema from '../import-job/import-job.schema.js';
 import ImportUrlSchema from '../import-url/import-url.schema.js';
 import KeyEventSchema from '../key-event/key-event.schema.js';
+import LatestAuditSchema from '../latest-audit/latest-audit.schema.js';
 import OpportunitySchema from '../opportunity/opportunity.schema.js';
 import OrganizationSchema from '../organization/organization.schema.js';
 import SiteSchema from '../site/site.schema.js';
@@ -90,12 +93,13 @@ class EntityRegistry {
    * Gets a collection instance by its name.
    * @param {string} collectionName - The name of the collection to retrieve.
    * @returns {Object} - The requested collection instance.
-   * @throws {Error} - Throws an error if the collection with the specified name is not found.
+   * @throws {DataAccessError} - Throws an error if the collection with the
+   * specified name is not found.
    */
   getCollection(collectionName) {
     const collection = this.collections.get(collectionName);
     if (!collection) {
-      throw new Error(`Collection ${collectionName} not found`);
+      throw new DataAccessError(`Collection ${collectionName} not found`, this);
     }
     return collection;
   }
@@ -127,6 +131,7 @@ EntityRegistry.registerEntity(ExperimentSchema, ExperimentCollection);
 EntityRegistry.registerEntity(ImportJobSchema, ImportJobCollection);
 EntityRegistry.registerEntity(ImportUrlSchema, ImportUrlCollection);
 EntityRegistry.registerEntity(KeyEventSchema, KeyEventCollection);
+EntityRegistry.registerEntity(LatestAuditSchema, LatestAuditCollection);
 EntityRegistry.registerEntity(OpportunitySchema, OpportunityCollection);
 EntityRegistry.registerEntity(OrganizationSchema, OrganizationCollection);
 EntityRegistry.registerEntity(SiteSchema, SiteCollection);