@adobe/spacecat-shared-data-access 1.57.1 → 1.58.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-data-access-v1.58.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v1.57.2...@adobe/spacecat-shared-data-access-v1.58.0) (2024-11-26)
+
+
+### Features
+
+* auto references & attribute set/get ([#461](https://github.com/adobe/spacecat-shared/issues/461)) ([2c29683](https://github.com/adobe/spacecat-shared/commit/2c296835bb7e71f2984e5537eab1dfc25bcc6141))
+
+# [@adobe/spacecat-shared-data-access-v1.57.2](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v1.57.1...@adobe/spacecat-shared-data-access-v1.57.2) (2024-11-23)
+
+
+### Bug Fixes
+
+* **deps:** update external fixes ([#454](https://github.com/adobe/spacecat-shared/issues/454)) ([325cf8d](https://github.com/adobe/spacecat-shared/commit/325cf8dded5fcabadaf7d8fdd510d33aeafd08a7))
+
 # [@adobe/spacecat-shared-data-access-v1.57.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v1.57.0...@adobe/spacecat-shared-data-access-v1.57.1) (2024-11-22)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "1.57.1",
+  "version": "1.58.0",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {
@@ -34,14 +34,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@adobe/spacecat-shared-dynamo": "1.3.49",
-    "@adobe/spacecat-shared-utils": "1.23.0",
-    "@aws-sdk/client-dynamodb": "3.696.0",
-    "@aws-sdk/lib-dynamodb": "3.696.0",
+    "@adobe/spacecat-shared-dynamo": "1.3.50",
+    "@adobe/spacecat-shared-utils": "1.23.1",
+    "@aws-sdk/client-dynamodb": "3.699.0",
+    "@aws-sdk/lib-dynamodb": "3.699.0",
     "@types/joi": "17.2.3",
     "aws-xray-sdk": "3.10.2",
     "electrodb": "3.0.1",
     "joi": "17.13.3",
+    "pluralize": "8.0.0",
     "uuid": "11.0.3"
   },
   "devDependencies": {

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

@@ -16,6 +16,7 @@ import { ElectroValidationError } from 'electrodb';
 
 import ValidationError from '../errors/validation.error.js';
 import { guardId } from '../util/guards.js';
+import { keyNamesToIndexName } from '../util/reference.js';
 
 /**
  * BaseCollection - A base class for managing collections of entities in the application.
@@ -30,7 +31,7 @@ class BaseCollection {
    * @constructor
    * @param {Object} electroService - The ElectroDB service used for managing entities.
    * @param {Object} modelFactory - A factory for creating model instances.
-   * @param {Class} clazz - The model class that represents the entity.
+   * @param {BaseModel} clazz - The model class that represents the entity.
    * @param {Object} log - A logger for capturing logging information.
    */
   constructor(electroService, modelFactory, clazz, log) {
@@ -45,12 +46,12 @@ class BaseCollection {
 
   /**
    * Creates an instance of a model from a record.
-   * @protected
+   * @private
    * @param {Object} record - The record containing data to create the model instance.
    * @returns {BaseModel|null} - Returns an instance of the model class if the data is valid,
    * otherwise null.
    */
-  _createInstance(record) {
+  #createInstance(record) {
     if (!isNonEmptyObject(record?.data)) {
       this.log.warn(`Failed to create instance of [${this.entityName}]: record is empty`);
       return null;
@@ -66,18 +67,25 @@ class BaseCollection {
 
   /**
    * Creates instances of models from a set of records.
-   * @protected
+   * @private
    * @param {Object} records - The records containing data to create the model instances.
    * @returns {Array<BaseModel>} - An array of instances of the model class.
    */
-  _createInstances(records) {
+  #createInstances(records) {
     if (!Array.isArray(records?.data)) {
       this.log.warn(`Failed to create instances of [${this.entityName}]: records are empty`);
       return [];
     }
-    return records.data.map((record) => this._createInstance({ data: record }));
+    return records.data.map((record) => this.#createInstance({ data: record }));
   }
 
+  /**
+   * Retrieves the enum values for a field in the entity schema. Useful for validating
+   * enum values prior to creating or updating an entity.
+   * @param {string} fieldName - The name of the field to retrieve enum values for.
+   * @return {string[]} - An array of enum values for the field.
+   * @protected
+   */
   _getEnumValues(fieldName) {
     return this.entity.model.schema.attributes[fieldName]?.enumArray;
   }
@@ -95,7 +103,38 @@ class BaseCollection {
 
     const record = await this.entity.get({ [this.idName]: id }).go();
 
-    return this._createInstance(record);
+    return this.#createInstance(record);
+  }
+
+  /**
+   * Finds entities by a set of index keys. Index keys are used to query entities by
+   * a specific index defined in the entity schema. The index keys must match the
+   * fields defined in the index.
+   * @param {Object} keys - The index keys to use for the query.
+   * @return {Promise<Array<BaseModel>>} - A promise that resolves to an array of model instances.
+   * @throws {Error} - Throws an error if the index keys are not provided or if the index
+   * is not found.
+   * @async
+   */
+  async findByIndexKeys(keys) {
+    if (!isNonEmptyObject(keys)) {
+      const message = `Failed to find by index keys [${this.entityName}]: keys are required`;
+      this.log.error(message);
+      throw new Error(message);
+    }
+
+    const indexName = keyNamesToIndexName(Object.keys(keys));
+    const index = this.entity.query[indexName];
+
+    if (!index) {
+      const message = `Failed to find by index keys [${this.entityName}]: index [${indexName}] not found`;
+      this.log.error(message);
+      throw new Error(message);
+    }
+
+    const records = await index(keys).go();
+
+    return this.#createInstances(records);
   }
 
   /**
@@ -118,7 +157,7 @@ class BaseCollection {
       // todo: catch ElectroDB validation errors and re-throws as ValidationError
       // todo: validate associations
       const record = await this.entity.create(item).go();
-      return this._createInstance(record);
+      return this.#createInstance(record);
     } catch (error) {
       this.log.error(`Failed to create [${this.entityName}]`, error);
       throw error;
@@ -131,13 +170,14 @@ class BaseCollection {
    *
    * @async
    * @param {Array<Object>} newItems - An array of data for the entities to be created.
+   * @param {BaseModel} [parent] - Optional parent entity that these items are associated with.
    * @return {Promise<{ createdItems: BaseModel[],
    * errorItems: { item: Object, error: ElectroValidationError }[] }>} - 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.
    */
-  async createMany(newItems) {
+  async createMany(newItems, parent = null) {
     if (!Array.isArray(newItems) || newItems.length === 0) {
       const message = `Failed to create many [${this.entityName}]: items must be a non-empty array`;
       this.log.error(message);
@@ -181,13 +221,20 @@ class BaseCollection {
         const response = await this.entity.put(validatedItems).go(
           { listeners: [requestItemsListener] },
         );
-        records = this._createInstances({ data: createdItems });
+        records = this.#createInstances({ data: createdItems });
 
         if (Array.isArray(response.unprocessed) && response.unprocessed.length > 0) {
           this.log.error(`Failed to process all items in batch write for [${this.entityName}]: ${JSON.stringify(response.unprocessed)}`);
         }
       }
 
+      if (parent) {
+        records.forEach((record) => {
+          // eslint-disable-next-line no-underscore-dangle
+          record._cacheReference(parent.entity.model.name, parent);
+        });
+      }
+
       return { createdItems: records, errorItems };
     } catch (error) {
       this.log.error(`Failed to create many [${this.entityName}]`, error);

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

@@ -10,12 +10,28 @@
  * governing permissions and limitations under the License.
  */
 
+import { isNonEmptyObject } from '@adobe/spacecat-shared-utils';
+
 import Patcher from '../util/patcher.js';
+import {
+  capitalize,
+  entityNameToCollectionName,
+  entityNameToIdName,
+  entityNameToReferenceMethodName, idNameToEntityName,
+} from '../util/reference.js';
 
 /**
  * Base - A base class for representing individual entities in the application.
  * Provides common functionality for entity management, including fetching, updating,
- * and deleting records.
+ * and deleting records. This class is intended to be extended by specific entity classes
+ * that represent individual entities in the application. The BaseModel class provides
+ * methods for fetching associated entities based on the type of relationship
+ * (belongs_to, has_one, has_many).
+ * The fetched references are cached to avoid redundant database queries. If the reference
+ * is already cached, it will be returned directly.
+ * Attribute values can be accessed and modified using getter and setter methods that are
+ * automatically generated based on the entity schema. The BaseModel class also provides
+ * methods for removing and saving entities to the database.
  *
  * @class BaseModel
  */
@@ -35,31 +51,121 @@ class BaseModel {
     this.entity = electroService.entities[this.entityName];
     this.idName = `${this.entityName}Id`;
     this.log = log;
+    this.referencesCache = {};
 
     this.patcher = new Patcher(this.entity, this.record);
-    this.associationsCache = {};
+
+    this.#initializeReferences();
+    this.#initializeAttributes();
+  }
+
+  /**
+   * Initializes the references for the current entity.
+   * This method is called during the construction of the entity instance
+   * to set up the reference methods for fetching associated entities.
+   * @private
+   */
+  #initializeReferences() {
+    const { references } = this.entity.model.original;
+    if (!isNonEmptyObject(references)) {
+      return;
+    }
+
+    for (const [type, refs] of Object.entries(references)) {
+      refs.forEach((ref) => {
+        const { target } = ref;
+        const methodName = entityNameToReferenceMethodName(target, type);
+
+        this[methodName] = async () => this._fetchReference(type, target);
+      });
+    }
+  }
+
+  #initializeAttributes() {
+    const { attributes } = this.entity.model.schema;
+
+    if (!isNonEmptyObject(attributes)) {
+      return;
+    }
+
+    for (const [name, attr] of Object.entries(attributes)) {
+      const capitalized = capitalize(name);
+      const getterMethodName = `get${capitalized}`;
+      const setterMethodName = `set${capitalized}`;
+      const isReference = this.entity.model.original
+        .references?.belongs_to?.some((ref) => ref.target === idNameToEntityName(name));
+
+      if (!this[getterMethodName] || name === this.idName) {
+        this[getterMethodName] = () => this.record[name];
+      }
+
+      if (!this[setterMethodName] && !attr.readOnly) {
+        this[setterMethodName] = (value) => {
+          this.patcher.patchValue(name, value, isReference);
+          return this;
+        };
+      }
+    }
+  }
+
+  /**
+   * Gets a cached reference for the specified entity.
+   * @param {string} targetName - The name of the entity to fetch.
+   * @return {*}
+   */
+  #getCachedReference(targetName) {
+    return this.referencesCache[targetName];
   }
 
   /**
-   * Gets the association of the model by querying another related model. Retrieved
-   * associations are cached to avoid redundant queries.
-   * @protected
+   * Caches a reference for the specified entity. This method is used to store
+   * fetched references to avoid redundant database queries.
+   * @param {string} targetName - The name of the entity to cache.
+   * @param {*} reference - The reference to cache.
+   * @private
+   */
+  _cacheReference(targetName, reference) {
+    this.referencesCache[targetName] = reference;
+  }
+
+  /**
+   * Fetches a reference for the specified entity. This method is used to fetch
+   * associated entities based on the type of relationship (belongs_to, has_one, has_many).
+   * The fetched references are cached to avoid redundant database queries. If the reference
+   * is already cached, it will be returned directly.
+   * References are defined in the entity model and are used to fetch associated entities.
    * @async
-   * @param {string} modelName - The name of the related model.
-   * @param {string} method - The method to use for querying the related model.
-   * @param {...*} args - Additional arguments to be passed to the method.
-   * @returns {Promise<Object>} - A promise that resolves to the associated model instance.
+   * @param {string} type - The type of relationship (belongs_to, has_one, has_many).
+   * @param {string} targetName - The name of the entity to fetch.
+   * @return {Promise<*|null>} - A promise that resolves to the fetched reference or null if
+   * not found.
+   * @private
    */
-  async _getAssociation(modelName, method, ...args) {
-    const cache = this.associationsCache;
+  async _fetchReference(type, targetName) { /* eslint-disable no-underscore-dangle */
+    let result = this.#getCachedReference(targetName);
+    if (result) {
+      return result;
+    }
 
-    cache[modelName] = cache[modelName] || {};
+    const collectionName = entityNameToCollectionName(targetName);
+    const targetCollection = this.modelFactory.getCollection(collectionName);
+
+    if (type === 'belongs_to' || type === 'has_one') {
+      const foreignKey = entityNameToIdName(targetName);
+      const id = this.record[foreignKey];
+      if (!id) return null;
+
+      result = await targetCollection.findById(id);
+    } else if (type === 'has_many') {
+      const foreignKey = entityNameToIdName(this.entityName);
+      result = await targetCollection.findByIndexKeys({ [foreignKey]: this.getId() });
+    }
 
-    if (!(method in cache[modelName])) {
-      cache[modelName][method] = await this.modelFactory.getCollection(modelName)[method](...args);
+    if (result) {
+      await this._cacheReference(targetName, result);
     }
 
-    return cache[modelName][method];
+    return result;
   }
 
   /**
@@ -116,6 +222,7 @@ class BaseModel {
     // todo: validate associations
     try {
       await this.patcher.save();
+      // todo: in case references are updated, clear or refresh references cache
       return this;
     } catch (error) {
       this.log.error('Failed to save record', error);

package/src/v2/models/index.d.ts

@@ -81,6 +81,7 @@ export interface Suggestion extends BaseModel {
  */
 export interface BaseCollection<T extends BaseModel> {
   findById(id: string): Promise<T>;
+  findByIndexKeys(indexKeys: object): Promise<T[]>;
   create(item: object): Promise<T>;
   createMany(items: object[]): Promise<MultiStatusCreateResult<T>>;
 }

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

@@ -46,10 +46,7 @@ class OpportunityCollection extends BaseCollection {
     if (!hasText(siteId)) {
       throw new Error('SiteId is required');
     }
-
-    const records = await this.entity.query.bySiteId({ siteId }).go();
-
-    return this._createInstances(records);
+    return this.findByIndexKeys({ siteId });
   }
 
   /**
@@ -70,8 +67,7 @@ class OpportunityCollection extends BaseCollection {
       throw new Error('Status is required');
     }
 
-    const records = await this.entity.query.bySiteIdAndStatus({ siteId, status }).go();
-    return this._createInstances(records);
+    return this.findByIndexKeys({ siteId, status });
   }
 }
 

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

@@ -38,219 +38,9 @@ class Opportunity extends BaseModel {
       ...suggestion,
       [this.idName]: this.getId(),
     }));
-    return this._getAssociation('SuggestionCollection', 'createMany', childSuggestions);
-  }
-
-  /**
-   * Retrieves all Suggestion entities associated to this Opportunity.
-   * @async
-   * @returns {Promise<Array<Suggestion>>} - A promise that resolves to an array of Suggestion
-   * instances associated with this Opportunity.
-   */
-  async getSuggestions() {
-    return this._getAssociation(
-      'SuggestionCollection',
-      'allByOpportunityId',
-      this.getId(),
-    );
-  }
-
-  /**
-   * Gets the ID of the site associated with this Opportunity.
-   * @returns {string} - The unique identifier of the site.
-   */
-  getSiteId() {
-    return this.record.siteId;
-  }
-
-  /**
-   * Sets the site ID for this Opportunity (associates it with a site).
-   * @param {string} siteId - The unique identifier of the site.
-   * @returns {Opportunity} - The current instance of Opportunity for chaining.
-   * @throws {Error} - Throws an error if the siteId is not a valid UUID.
-   */
-  setSiteId(siteId) {
-    this.patcher.patchValue('siteId', siteId, true);
-    return this;
-  }
-
-  /**
-   * Gets the ID of the audit associated with this Opportunity.
-   * @returns {string} - The unique identifier of the audit.
-   */
-  getAuditId() {
-    return this.record.auditId;
-  }
-
-  /**
-   * Sets the audit ID for this Opportunity (associates it with an audit).
-   * @param {string} auditId - The unique identifier of the audit.
-   * @returns {Opportunity} - The current instance of Opportunity for chaining.
-   * @throws {Error} - Throws an error if the auditId is not a valid UUID.
-   */
-  setAuditId(auditId) {
-    this.patcher.patchValue('auditId', auditId, true);
-    return this;
-  }
-
-  /**
-   * Gets the runbook URL or reference for this Opportunity.
-   * @returns {string} - The runbook reference for this Opportunity.
-   */
-  getRunbook() {
-    return this.record.runbook;
-  }
-
-  /**
-   * Sets the runbook URL or reference for this Opportunity.
-   * @param {string} runbook - The runbook reference or URL.
-   * @returns {Opportunity} - The current instance of Opportunity for chaining.
-   * @throws {Error} - Throws an error if the runbook is not a string or empty.
-   */
-  setRunbook(runbook) {
-    this.patcher.patchValue('runbook', runbook);
-    return this;
-  }
-
-  /**
-   * Gets the guidance information for this Opportunity.
-   * @returns {Object} - The guidance object for this Opportunity.
-   */
-  getGuidance() {
-    return this.record.guidance;
-  }
-
-  /**
-   * Sets the guidance information for this Opportunity.
-   * @param {Object} guidance - The guidance object.
-   * @returns {Opportunity} - The current instance of Opportunity for chaining.
-   * @throws {Error} - Throws an error if the guidance is not an object or empty.
-   */
-  setGuidance(guidance) {
-    this.patcher.patchValue('guidance', guidance);
-    return this;
-  }
-
-  /**
-   * Gets the title of this Opportunity.
-   * @returns {string} - The title of the Opportunity.
-   */
-  getTitle() {
-    return this.record.title;
-  }
-
-  /**
-   * Sets the title of this Opportunity.
-   * @param {string} title - The title of the Opportunity.
-   * @returns {Opportunity} - The current instance of Opportunity for chaining.
-   * @throws {Error} - Throws an error if the title is not a string or empty.
-   */
-  setTitle(title) {
-    this.patcher.patchValue('title', title);
-    return this;
-  }
-
-  /**
-   * Gets the description of this Opportunity.
-   * @returns {string} - The description of the Opportunity.
-   */
-  getDescription() {
-    return this.record.description;
-  }
-
-  /**
-   * Sets the description of this Opportunity.
-   * @param {string} description - The description of the Opportunity.
-   * @returns {Opportunity} - The current instance of Opportunity for chaining.
-   * @throws {Error} - Throws an error if the description is not a string or empty.
-   */
-  setDescription(description) {
-    this.patcher.patchValue('description', description);
-    return this;
-  }
-
-  /**
-   * Gets the type of this Opportunity.
-   * @returns {string} - The type of the Opportunity.
-   */
-  getType() {
-    return this.record.type;
-  }
-
-  /**
-   * Gets the status of this Opportunity.
-   * @returns {string} - The status of the Opportunity.
-   */
-  getStatus() {
-    return this.record.status;
-  }
-
-  /**
-   * Sets the status of this Opportunity. Check the schema for valid status values.
-   * @param {string} status - The status of the Opportunity.
-   * @returns {Opportunity} - The current instance of Opportunity for chaining.
-   * @throws {Error} - Throws an error if the status is not a valid value.
-   */
-  setStatus(status) {
-    this.patcher.patchValue('status', status);
-    return this;
-  }
-
-  /**
-   * Gets the origin of this Opportunity.
-   * @returns {string} - The origin of the Opportunity (e.g., ESS_OPS, AI, AUTOMATION).
-   */
-  getOrigin() {
-    return this.record.origin;
-  }
-
-  /**
-   * Sets the origin of this Opportunity. Check the schema for valid origin values.
-   * @param {string} origin - The origin of the Opportunity.
-   * @returns {Opportunity} - The current instance of Opportunity for chaining.
-   * @throws {Error} - Throws an error if the origin is not a valid value.
-   */
-  setOrigin(origin) {
-    this.patcher.patchValue('origin', origin);
-    return this;
-  }
-
-  /**
-   * Gets the tags associated with this Opportunity.
-   * @returns {Array<string>} - An array of tags associated with the Opportunity.
-   */
-  getTags() {
-    return this.record.tags;
-  }
-
-  /**
-   * Sets the tags for this Opportunity. Duplicate tags are made unique.
-   * @param {Array<string>} tags - An array of tags to associate with the Opportunity.
-   * @returns {Opportunity} - The current instance of Opportunity for chaining.
-   * @throws {Error} - Throws an error if the tags are not an array.
-   */
-  setTags(tags) {
-    this.patcher.patchValue('tags', tags);
-    return this;
-  }
-
-  /**
-   * Gets additional data associated with this Opportunity.
-   * @returns {Object} - The additional data for the Opportunity.
-   */
-  getData() {
-    return this.record.data;
-  }
-
-  /**
-   * Sets additional data for this Opportunity.
-   * @param {Object} data - The data to set for the Opportunity.
-   * @returns {Opportunity} - The current instance of Opportunity for chaining.
-   * @throws {Error} - Throws an error if the data is not a valid object.
-   */
-  setData(data) {
-    this.patcher.patchValue('data', data);
-    return this;
+    return this.modelFactory
+      .getCollection('SuggestionCollection')
+      .createMany(childSuggestions, this);
   }
 }
 

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

@@ -46,17 +46,14 @@ class SuggestionCollection extends BaseCollection {
     if (!hasText(opportunityId)) {
       throw new Error('OpportunityId is required');
     }
-
-    const records = await this.entity.query.byOpportunityId({ opportunityId }).go();
-
-    return this._createInstances(records);
+    return this.findByIndexKeys({ opportunityId });
   }
 
   /**
    * Retrieves all Suggestion entities by their associated Opportunity ID and status.
    * @param {string} opportunityId - The unique identifier of the associated Opportunity.
    * @param {string} status - The status of the Suggestion entities
-   * @return {Promise<Array<BaseModel>>} - A promise that resolves to an array of
+   * @return {Promise<BaseModel[]>} - A promise that resolves to an array of
    * Suggestion instances.
    * @throws {Error} - Throws an error if the opportunityId or status is not provided.
    */
@@ -69,11 +66,7 @@ class SuggestionCollection extends BaseCollection {
       throw new Error('Status is required');
     }
 
-    const records = await this.entity.query.byOpportunityIdAndStatus(
-      { opportunityId, status },
-    ).go();
-
-    return this._createInstances(records);
+    return this.findByIndexKeys({ opportunityId, status });
   }
 
   /**

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

@@ -21,118 +21,7 @@ import BaseModel from './base.model.js';
  * @extends BaseModel
  */
 class Suggestion extends BaseModel {
-  /**
-   * Retrieves the Opportunity entity associated to this Suggestion.
-   * @async
-   * @returns {Promise<Opportunity>} - A promise that resolves to the Opportunity
-   * instance associated with this Suggestion.
-   */
-  async getOpportunity() {
-    return this._getAssociation('OpportunityCollection', 'findById', this.getOpportunityId());
-  }
-
-  /**
-   * Gets the Opportunity ID for this Suggestion.
-   * @returns {string} - The unique identifier of the related Opportunity.
-   */
-  getOpportunityId() {
-    return this.record.opportunityId;
-  }
-
-  /**
-   * Sets the Opportunity ID for this Suggestion.
-   * @param {string} opportunityId - The unique identifier of the related Opportunity.
-   * @returns {Suggestion} - The current instance of Suggestion for chaining.
-   * @throws {Error} - Throws an error if the opportunityId is not a valid UUID.
-   */
-  setOpportunityId(opportunityId) {
-    this.patcher.patchValue('opportunityId', opportunityId, true);
-    return this;
-  }
-
-  /**
-   * Gets the type of this Suggestion.
-   * @returns {string} - The type of the Suggestion (e.g., CODE_CHANGE, CONTENT_UPDATE).
-   */
-  getType() {
-    return this.record.type;
-  }
-
-  /**
-   * Gets the status of this Suggestion.
-   * @returns {string} - The status of the Suggestion (e.g., NEW, APPROVED, SKIPPED, FIXED, ERROR).
-   */
-  getStatus() {
-    return this.record.status;
-  }
-
-  /**
-   * Sets the status of this Suggestion. Check the schema for possible values.
-   * @param {string} status - The new status of the Suggestion.
-   * @returns {Suggestion} - The current instance of Suggestion for chaining.
-   * @throws {Error} - Throws an error if the status is not a valid value.
-   */
-  setStatus(status) {
-    this.patcher.patchValue('status', status);
-    return this;
-  }
-
-  /**
-   * Gets the rank of this Suggestion.
-   * @returns {number} - The rank of the Suggestion used for sorting or prioritization.
-   */
-  getRank() {
-    return this.record.rank;
-  }
-
-  /**
-   * Sets the rank of this Suggestion.
-   * @param {number} rank - The rank value to set for this Suggestion.
-   * @returns {Suggestion} - The current instance of Suggestion for chaining.
-   * @throws {Error} - Throws an error if the rank is not a valid number.
-   */
-  setRank(rank) {
-    this.patcher.patchValue('rank', rank);
-    return this;
-  }
-
-  /**
-   * Gets additional data associated with this Suggestion.
-   * @returns {Object} - The additional data for the Suggestion.
-   */
-  getData() {
-    return this.record.data;
-  }
-
-  /**
-   * Sets additional data for this Suggestion.
-   * @param {Object} data - The data to set for the Suggestion.
-   * @returns {Suggestion} - The current instance of Suggestion for chaining.
-   * @throws {Error} - Throws an error if the data is not a valid object.
-   */
-  setData(data) {
-    this.patcher.patchValue('data', data);
-    return this;
-  }
-
-  /**
-   * Gets the KPI deltas for this Suggestion.
-   * @returns {Object} - The key performance indicator deltas that are affected by this Suggestion.
-   */
-  getKpiDeltas() {
-    return this.record.kpiDeltas;
-  }
-
-  /**
-   * Sets the KPI deltas for this Suggestion.
-   * @param {Object} kpiDeltas - The KPI deltas to set for the Suggestion.
-   * @returns {Suggestion} - The current instance of Suggestion for chaining.
-   * @throws {Error} - Throws an error if the kpiDeltas is not a valid object.
-   */
-  setKpiDeltas(kpiDeltas) {
-    this.patcher.patchValue('kpiDeltas', kpiDeltas);
-    return this;
-  }
+  // add your customized methods here
 }
 
 export default Suggestion;

package/src/v2/readme.md

@@ -2,14 +2,28 @@
 
 This repository contains a model framework built using the ElectroDB ORM, designed to manage website improvements in a scalable manner. The system consists of several entities, including Opportunities and Suggestions, which represent potential areas of improvement and the actions to resolve them.
 
+## Table of Contents
+
+1. [Architecture Overview](#architecture-overview)
+2. [Entities and Relationships](#entities-and-relationships)
+3. [Getting Started](#getting-started)
+4. [Adding a New ElectroDB-Based Entity](#adding-a-new-electrodb-based-entity)
+   - [Step 1: Define the Entity Schema](#step-1-define-the-entity-schema)
+   - [Step 2: Add a Model Class](#step-2-add-a-model-class)
+   - [Step 3: Add a Collection Class](#step-3-add-a-collection-class)
+   - [Step 4: Integrate the Entity into Model Factory](#step-4-integrate-the-entity-into-model-factory)
+   - [Step 5: Write Unit and Integration Tests](#step-5-write-unit-and-integration-tests)
+   - [Step 6: Create JSDoc and Update Documentation](#step-6-create-jsdoc-and-update-documentation)
+   - [Step 7: Run Tests and Verify](#step-7-run-tests-and-verify)
+
 ## Architecture Overview
 
-The architecture is centered around a collection-management pattern with ElectroDB, enabling efficient management of DynamoDB entities. It uses a layered architecture as follows:
+The architecture follows a collection-management pattern with ElectroDB, enabling efficient handling of DynamoDB entities. The architecture is organized into the following layers:
 
-1. **Data Layer**: Utilizes DynamoDB as the data store, with ElectroDB for managing schema definitions and data interactions.
-2. **Model Layer**: The `BaseModel` provides common methods like `save`, `remove`, and associations for all entities. Each entity (e.g., `Opportunity`, `Suggestion`) extends `BaseModel` for specific features.
-3. **Collection Layer**: The `BaseCollection` handles entity-specific CRUD operations. `OpportunityCollection` and `SuggestionCollection` extend `BaseCollection` to provide tailored methods for managing Opportunities and Suggestions.
-4. **Factory Layer**: The `ModelFactory` centralizes the instantiation of models and collections, providing a unified interface for interacting with different entity types.
+1. **Data Layer**: Uses DynamoDB with ElectroDB to manage schema definitions and data interactions.
+2. **Model Layer**: The `BaseModel` provides methods like `save`, `remove`, and manages associations. Entity classes such as `Opportunity` and `Suggestion` extend `BaseModel` for specific features.
+3. **Collection Layer**: The `BaseCollection` handles CRUD operations for entities. Specialized collections, like `OpportunityCollection` and `SuggestionCollection`, extend `BaseCollection` with tailored methods for specific entities.
+4. **Factory Layer**: The `ModelFactory` centralizes instantiation of models and collections, providing a unified interface for different entity types.
 
 ### Architectural Diagram
 
@@ -44,9 +58,10 @@ The architecture is centered around a collection-management pattern with Electro
 ```
 
 ## Entities and Relationships
+
 - **Opportunity**: Represents a specific issue identified on a website. It includes attributes like `title`, `description`, `siteId`, and `status`.
 - **Suggestion**: Represents a proposed fix for an Opportunity. Attributes include `opportunityId`, `type`, `status`, and `rank`.
-- **Relationship**: Opportunities have many Suggestions. This is implemented through the `OpportunityCollection` and `SuggestionCollection`, which interact via ElectroDB-managed DynamoDB relationships.
+- **Relationships**: Opportunities have many Suggestions. This relationship is implemented through `OpportunityCollection` and `SuggestionCollection`, which interact via ElectroDB-managed DynamoDB relationships.
 
 ## Getting Started
 
@@ -56,8 +71,8 @@ The architecture is centered around a collection-management pattern with Electro
    ```
 
 2. **Setup DynamoDB**
-   - This framework relies on AWS DynamoDB for data storage. Ensure you have AWS credentials configured and a DynamoDB table set up.
-   - Configure the DynamoDB table name and related settings in the `index.js` configuration.
+   - Ensure AWS credentials are configured and a DynamoDB table is set up.
+   - Configure the DynamoDB table name and related settings in `index.js`.
 
 3. **Usage Example**
    ```javascript
@@ -79,17 +94,12 @@ The architecture is centered around a collection-management pattern with Electro
 
 ## Adding a New ElectroDB-Based Entity
 
-This guide provides a step-by-step overview for adding a new ElectroDB-based entity to the existing application. By following this guide, you will be able to create, integrate, and test a new entity seamlessly.
-
-## Prerequisites
+This guide provides a step-by-step overview for adding a new ElectroDB-based entity to the application.
 
-- Familiarity with ElectroDB and how it models data.
-- Understanding of the current data model and relationships.
-- Node.js and npm installed on your system.
+### Step 1: Define the Entity Schema
 
-## Step 1: Define the Entity Schema
+1. **Create Entity Schema File**: Define the entity schema in a new file (e.g., `myNewEntity.schema.js`) within the `/schemas/` directory.
 
-1. **Create Entity Schema File**: Start by defining the entity schema in a new file (e.g., `myNewEntity.schema.js`) within the `/entities/` directory. This file should export a simple JavaScript object that defines the schema for the entity (refer to the existing `opportunity.schema.js` for an example).
    ```javascript
    export const MyNewEntitySchema = {
      model: {
@@ -129,45 +139,74 @@ This guide provides a step-by-step overview for adding a new ElectroDB-based ent
          },
        },
      },
+     references: {
+       belongs_to: [
+         { type: 'belongs_to', target: 'Opportunity' },
+       ],
+     },
    };
    ```
 
-## Step 2: Add a Model Class
+2. **Declare References**: Use the `references` field to define relationships between entities. This sets up associations for easy fetching and managing of related entities, allowing for automatic generation of reference getter methods.
+
+### Step 2: Add a Model Class
+
+1. **Create the Model Class**: In the `/models/` directory, add `myNewEntity.model.js`.
 
-1. **Create the Model Class**: In the `/models/` directory, add a file named `myNewEntity.model.js`.
    ```javascript
    import BaseModel from './base.model.js';
-
+   
    class MyNewEntity extends BaseModel {
      constructor(electroService, modelFactory, record, log) {
        super(electroService, modelFactory, record, log);
      }
+   }
+   
+   export default MyNewEntity;
+   ```
 
-     getName() {
-       return this.record.name;
-     }
+   Note: By using `BaseModel`, entity classes can remain empty unless there is a need to:
+   - Override automatically generated getters or setters for specific attributes.
+   - Add custom methods specific to the entity.
 
-     setName(name) {
-       this.record.name = name;
-       return this;
-     }
+### Automatic Getter and Setter Methods
 
-     getStatus() {
-       return this.record.status;
-     }
+The `BaseModel` automatically generates getter and setter methods for each attribute defined in the entity schema:
 
-     setStatus(status) {
-       this.record.status = status;
-       return this;
-     }
-   }
+- **Utility Methods**: `BaseModel` provides `getId()`, `getCreatedAt()`, and `getUpdatedAt()` methods out of the box for accessing common entity information like the unique identifier, creation timestamp, and last update timestamp.
 
-   export default MyNewEntity;
-   ```
+- **Getters**: Follow the convention `get<AttributeName>()` to access attribute values.
+- **Setters**: Follow the convention `set<AttributeName>(value)` to modify entity values, while handling patching.
+
+Example:
+
+- If an attribute is named `name`, `BaseModel` will automatically generate:
+   - `getName()`: Retrieve the value of `name`.
+   - `setName(value)`: Update the value of `name`.
+
+This reduces boilerplate and ensures consistency.
+
+### Automatic Reference Getter Methods
 
-## Step 3: Add a Collection Class
+If references are defined in the schema (e.g., `belongs_to`, `has_many`), `BaseModel` generates reference getter methods:
+
+- **References Getter Naming**:
+   - Methods are named `get<RelatedEntity>()`, where `<RelatedEntity>` corresponds to the target specified in the `references` field.
+
+  Example:
+  ```javascript
+  references: {
+     belongs_to: [
+        { type: 'belongs_to', target: 'Opportunity' },
+     ],
+  },
+  ```
+  This results in a `getOpportunity()` method for accessing the related `Opportunity` entity.
+
+### Step 3: Add a Collection Class
+
+1. **Create the Collection Class**: Add `myNewEntity.collection.js` in the `/collections/` directory.
 
-1. **Create the Collection Class**: Add a new file named `myNewEntity.collection.js` in the `/collections/` directory.
    ```javascript
    import BaseCollection from './base.collection.js';
    import MyNewEntity from '../models/myNewEntity.model.js';
@@ -178,83 +217,56 @@ This guide provides a step-by-step overview for adding a new ElectroDB-based ent
      }
 
      async allByStatus(status) {
-       return await this.service.entities.myNewEntity.query.myNewEntityIndex({ status }).go();
+       return this.findByIndexKeys({ status });
      }
    }
 
    export default MyNewEntityCollection;
    ```
 
-## Step 4: Integrate the Entity into Model Factory
+### Step 4: Integrate the Entity into Model Factory
+
+1. **Update the Model Factory**: Open `model.factory.js` and add the new entity and collection to the `initialize` method.
 
-1. **Update the Model Factory**: Open `model.factory.js` and add the newly created entity and collection to the initialize method.
    ```javascript
    import MyNewEntityCollection from './collections/myNewEntity.collection.js';
 
    class ModelFactory {
      initialize() {
-
        const myNewEntityCollection = new MyNewEntityCollection(
          this.service,
          this,
          this.logger,
        );
 
-       this.models.set(MyNewEntityCollection.name, myNewEntityColection);
-     }
-   }
-   ```
-
-## Step 5: Write Unit Tests
-
-1. **Create Unit Test for the Model Class**: Add a new file in the `/tests/unit/v2/models/` directory named `myNewEntity.model.test.js`.
-
-   - Follow the existing test structure to test all getters, setters, and interactions for `MyNewEntity`.
-   - Use Mocha, Chai, Chai-as-promised, and Sinon for testing.
-
-2. **Create Unit Test for the Collection Class**: Add another test named `myNewEntity.collection.test.js`.
-
-   - Test the methods in `MyNewEntityCollection`, particularly those interacting with ElectroDB services, such as `allByStatus`.
-
-## Step 6: Add Guard Methods (if needed)
-
-1. **Update Guards if Needed**: If your entity requires new types of validation, add guard methods in `guards.js`. The guards should be generic and not specific to field names—ensure they can be reused for different fields of the same type. Update `index.d.ts` to add TypeScript type definitions for those new guard functions if necessary.
-   ```javascript
-   export function guardStatus(propertyName, value, entityName) {
-     const allowedStatuses = ['NEW', 'IN_PROGRESS', 'COMPLETED'];
-     if (!allowedStatuses.includes(value)) {
-       throw new Error(`${propertyName} must be one of ${allowedStatuses.join(', ')} in ${entityName}`);
+       this.models.set(MyNewEntityCollection.name, myNewEntityCollection);
      }
    }
    ```
 
-## Step 7: Update the Patcher (if needed)
-
-1. **Update Patcher if Needed**: Update `patcher.js` only if there are new types of data being patched that are not yet covered by the current patch methods (e.g., adding a new type like `Date` that hasn't been handled before).
-   - Create methods like `patchString`, `patchEnum`, etc., only if the existing ones do not suffice for your new entity attributes.
+### Step 5: Write Unit and Integration Tests
 
-## Step 8: Add to Integration Tests
+1. **Create Unit Tests**: Add a file named `myNewEntity.model.test.js` in `/tests/unit/models/` to test all getters, setters, and interactions.
+   - Use Mocha, Chai, and Sinon for testing.
 
-1. **Add Integration Tests**: Update the integration test suite to include the new entity. This will help ensure that the new entity integrates well with the rest of the system. Create an integration test file named `myNewEntity.integration.test.js` in the `/tests/it/v2/` directory.
-   - Test the full lifecycle of the entity: creation, updating, querying, and deletion.
-   - Make sure the entity can be retrieved through various service methods and that relationships with other entities are properly maintained.
+2. **Create Collection Tests**: Add `myNewEntity.collection.test.js` to `/tests/unit/collections/`.
+   - Test methods interacting with ElectroDB, like `allByStatus`.
 
-## Step 9: Create JSDoc and Update Documentation
+3. **Add Integration Tests**: Create an integration test file named `myNewEntity.integration.test.js` in `/tests/integration/` to test the full lifecycle of the entity.
 
-1. **Generate JSDoc for Entity and Collection**: For each function in your model and collection files, ensure JSDoc comments are present for developers to easily understand the API.
+### Step 6: Create JSDoc and Update Documentation
 
-2. **Update Type Definitions**: Update the `index.d.ts` file to include new interfaces and types for your new entity, ensuring that IDEs can provide auto-completion and type-checking.
+1. **Generate JSDoc for Entity and Collection**: Add JSDoc comments for each function to describe the API.
+2. **Update Type Definitions**: Modify `index.d.ts` to include new interfaces and types for the entity.
 
-## Step 10: Run Tests and Verify
-
-1. **Run All Tests**: Ensure all existing and new unit tests pass using Mocha. Run:
+### Step 7: Run Tests and Verify
 
+1. **Run All Tests**:
    ```bash
-   npm run test & npm run test:it
+   npm run test && npm run test:it
    ```
 
-2. **Linter**: Run ESLint to check for any coding standard violations.
-
+2. **Run Linter**: Check for coding standard violations.
    ```bash
    npm run lint
    ```

package/src/v2/schema/opportunity.schema.js

@@ -14,7 +14,7 @@
 
 import { isNonEmptyObject, isValidUrl } from '@adobe/spacecat-shared-utils';
 
-import { v4 as uuid } from 'uuid';
+import { validate as uuidValidate, v4 as uuid } from 'uuid';
 
 /*
 Schema Doc: https://electrodb.dev/en/modeling/schema/
@@ -36,21 +36,21 @@ const OpportunitySchema = {
       // https://electrodb.dev/en/modeling/attributes/#default
       default: () => uuid(),
       // https://electrodb.dev/en/modeling/attributes/#attribute-validation
-      validation: (value) => !uuid.validate(value),
+      validate: (value) => uuidValidate(value),
     },
     siteId: {
       type: 'string',
       required: true,
-      validation: (value) => !uuid.validate(value),
+      validate: (value) => uuidValidate(value),
     },
     auditId: {
       type: 'string',
       required: true,
-      validation: (value) => !uuid.validate(value),
+      validate: (value) => uuidValidate(value),
     },
     runbook: {
       type: 'string',
-      validation: (value) => !isValidUrl(value),
+      validate: (value) => !value || isValidUrl(value),
     },
     type: {
       type: 'string',
@@ -60,7 +60,7 @@ const OpportunitySchema = {
     data: {
       type: 'any',
       required: false,
-      validation: (value) => !isNonEmptyObject(value),
+      validate: (value) => !value || isNonEmptyObject(value),
     },
     origin: {
       type: ['ESS_OPS', 'AI', 'AUTOMATION'],
@@ -80,10 +80,9 @@ const OpportunitySchema = {
       default: () => 'NEW',
     },
     guidance: {
-      type: 'map',
-      properties: {},
+      type: 'any',
       required: false,
-      validation: (value) => !isNonEmptyObject(value),
+      validate: (value) => !value || isNonEmptyObject(value),
     },
     tags: {
       type: 'set',
@@ -142,4 +141,19 @@ const OpportunitySchema = {
   },
 };
 
+/**
+ * References to other entities. This is not part of the standard ElectroDB schema, but is used
+ * to define relationships between entities in our data layer API.
+ * @type {{belongs_to: [{type: string, target: string}]}}
+ */
+OpportunitySchema.references = {
+  has_many: [
+    { type: 'has_many', target: 'Suggestions' },
+  ],
+  belongs_to: [
+    { type: 'belongs_to', target: 'Site' },
+    { type: 'belongs_to', target: 'Audit' },
+  ],
+};
+
 export default OpportunitySchema;

package/src/v2/schema/suggestion.schema.js

@@ -12,7 +12,7 @@
 
 /* c8 ignore start */
 
-import { v4 as uuid } from 'uuid';
+import { v4 as uuid, validate as uuidValidate } from 'uuid';
 import { isNonEmptyObject } from '@adobe/spacecat-shared-utils';
 
 /*
@@ -35,12 +35,12 @@ const SuggestionSchema = {
       // https://electrodb.dev/en/modeling/attributes/#default
       default: () => uuid(),
       // https://electrodb.dev/en/modeling/attributes/#attribute-validation
-      validation: (value) => !uuid.validate(value),
+      validate: (value) => uuidValidate(value),
     },
     opportunityId: {
       type: 'string',
       required: true,
-      validation: (value) => !uuid.validate(value),
+      validate: (value) => uuidValidate(value),
     },
     type: {
       type: ['CODE_CHANGE', 'CONTENT_UPDATE', 'REDIRECT_UPDATE', 'METADATA_UPDATE'],
@@ -54,13 +54,12 @@ const SuggestionSchema = {
     data: {
       type: 'any',
       required: true,
-      validation: (value) => !isNonEmptyObject(value),
+      validate: (value) => isNonEmptyObject(value),
     },
     kpiDeltas: {
-      type: 'map',
-      properties: {},
+      type: 'any',
       required: false,
-      validation: (value) => !isNonEmptyObject(value),
+      validate: (value) => !value || isNonEmptyObject(value),
     },
     status: {
       type: ['NEW', 'APPROVED', 'SKIPPED', 'FIXED', 'ERROR'],
@@ -119,4 +118,15 @@ const SuggestionSchema = {
   },
 };
 
+/**
+ * References to other entities. This is not part of the standard ElectroDB schema, but is used
+ * to define relationships between entities in our data layer API.
+ * @type {{belongs_to: [{type: string, target: string}]}}
+ */
+SuggestionSchema.references = {
+  belongs_to: [
+    { type: 'belongs_to', target: 'Opportunity' },
+  ],
+};
+
 export default SuggestionSchema;

package/src/v2/util/reference.js

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import pluralize from 'pluralize';
+
+const capitalize = (str) => str.charAt(0).toUpperCase() + str.slice(1);
+const entityNameToCollectionName = (entityName) => `${pluralize.singular(entityName)}Collection`;
+const entityNameToIdName = (collectionName) => `${collectionName.charAt(0).toLowerCase() + collectionName.slice(1)}Id`;
+const entityNameToReferenceMethodName = (target, type) => {
+  let baseName = target.charAt(0).toUpperCase() + target.slice(1);
+  baseName = type === 'has_many'
+    ? pluralize.plural(baseName)
+    : pluralize.singular(baseName);
+
+  return `get${baseName}`;
+};
+
+const idNameToEntityName = (idName) => capitalize(pluralize.singular(idName.replace('Id', '')));
+
+const keyNamesToIndexName = (keyNames) => {
+  const capitalizedKeyNames = keyNames.map((keyName) => capitalize(keyName));
+  return `by${capitalizedKeyNames.join('And')}`;
+};
+
+export {
+  capitalize,
+  entityNameToCollectionName,
+  entityNameToIdName,
+  entityNameToReferenceMethodName,
+  idNameToEntityName,
+  keyNamesToIndexName,
+};