@adobe/spacecat-shared-data-access 1.59.2 → 1.60.0

package/src/v2/models/{base.model.js → base/base.model.js}

@@ -12,13 +12,16 @@
 
 import { isNonEmptyObject } from '@adobe/spacecat-shared-utils';
 
-import Patcher from '../util/patcher.js';
+import { createAccessors } from '../../util/accessor.utils.js';
+import Patcher from '../../util/patcher.js';
 import {
   capitalize,
-  entityNameToCollectionName,
   entityNameToIdName,
-  entityNameToReferenceMethodName, idNameToEntityName,
-} from '../util/reference.js';
+  idNameToEntityName,
+  isNonEmptyArray,
+} from '../../util/util.js';
+
+import Reference from './reference.js';
 
 /**
  * Base - A base class for representing individual entities in the application.
@@ -40,20 +43,28 @@ class BaseModel {
    * Constructs an instance of BaseModel.
    * @constructor
    * @param {Object} electroService - The ElectroDB service used for managing entities.
-   * @param {Object} modelFactory - A factory for creating model instances.
+   * @param {EntityRegistry} entityRegistry - The registry holding entities, their schema
+   * and collection.
+   * @param {Schema} schema - The schema for the entity.
    * @param {Object} record - The initial data for the entity instance.
-   * @param {Object} log - A logger for capturing logging information.
+   * @param {Object} log - A log for capturing logging information.
    */
-  constructor(electroService, modelFactory, record, log) {
-    this.modelFactory = modelFactory;
+  constructor(electroService, entityRegistry, schema, record, log) {
+    this.electroService = electroService;
+    this.entityRegistry = entityRegistry;
+    this.schema = schema;
     this.record = record;
-    this.entityName = this.constructor.name.toLowerCase();
-    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.entityName = schema.getEntityName();
+    this.idName = entityNameToIdName(this.entityName);
+
+    this.collection = entityRegistry.getCollection(schema.getCollectionName());
+    this.entity = electroService.entities[this.entityName];
+
+    this.patcher = new Patcher(this.entity, this.schema, this.record);
+
+    this._accessorCache = {};
 
     this.#initializeReferences();
     this.#initializeAttributes();
@@ -66,23 +77,16 @@ class BaseModel {
    * @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);
+    const references = this.schema.getReferences();
 
-        this[methodName] = async () => this._fetchReference(type, target);
-      });
-    }
+    references.forEach((reference) => {
+      const accessorConfigs = reference.toAccessorConfigs(this.entityRegistry, this);
+      createAccessors(accessorConfigs, this.log);
+    });
   }
 
   #initializeAttributes() {
-    const { attributes } = this.entity.model.schema;
+    const attributes = this.schema.getAttributes();
 
     if (!isNonEmptyObject(attributes)) {
       return;
@@ -92,8 +96,9 @@ class BaseModel {
       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));
+      const isReference = this.schema
+        .getReferencesByType(Reference.TYPES.BELONGS_TO)
+        .some((ref) => ref.getTarget() === idNameToEntityName(name));
 
       if (!this[getterMethodName] || name === this.idName) {
         this[getterMethodName] = () => this.record[name];
@@ -108,64 +113,43 @@ class BaseModel {
     }
   }
 
-  /**
-   * 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];
-  }
-
-  /**
-   * 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;
+  #invalidateCache() {
+    this._accessorCache = {};
   }
 
-  /**
-   * 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} 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 _fetchReference(type, targetName) { /* eslint-disable no-underscore-dangle */
-    let result = this.#getCachedReference(targetName);
-    if (result) {
-      return result;
-    }
-
-    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() });
-    }
+  async #fetchDependents() {
+    const promises = [];
+
+    const relationshipTypes = [
+      Reference.TYPES.HAS_MANY,
+      Reference.TYPES.HAS_ONE,
+    ];
+
+    relationshipTypes.forEach((type) => {
+      const references = this.schema.getReferencesByType(type);
+      const targets = references.filter((reference) => reference.isRemoveDependents());
+
+      targets.forEach((reference) => {
+        const accessors = reference.toAccessorConfigs(this.entityRegistry, this);
+        const methodName = accessors[0].name;
+        promises.push(
+          this[methodName]()
+            .then((dependent) => {
+              if (isNonEmptyArray(dependent)) {
+                return dependent;
+              } else if (isNonEmptyObject(dependent)) {
+                return [dependent];
+              }
+
+              return null;
+            }),
+        );
+      });
+    });
 
-    if (result) {
-      await this._cacheReference(targetName, result);
-    }
+    const results = await Promise.all(promises);
 
-    return result;
+    return results.flat().filter((dependent) => dependent !== null);
   }
 
   /**
@@ -181,7 +165,7 @@ class BaseModel {
    * @returns {string} - The ISO string representing when the entity was created.
    */
   getCreatedAt() {
-    return new Date(this.record.createdAt).toISOString();
+    return this.record.createdAt;
   }
 
   /**
@@ -189,20 +173,37 @@ class BaseModel {
    * @returns {string} - The ISO string representing when the entity was last updated.
    */
   getUpdatedAt() {
-    return new Date(this.record.updatedAt).toISOString();
+    return this.record.updatedAt;
   }
 
   /**
-   * Removes the current entity from the database.
+   * Removes the current entity from the database. This method also removes any dependent
+   * entities associated with the current entity. For example, if the current entity has
+   * a has_many relationship with another entity, the dependent entity will be removed.
+   * When adding a reference to an entity, the dependent entity will be removed if the
+   * 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.
    * @async
    * @returns {Promise<BaseModel>} - A promise that resolves to the current instance of the entity
-   * after it has been removed.
+   * after it and its dependents have been removed.
    * @throws {Error} - Throws an error if the removal fails.
    */
   async remove() {
     try {
-      // todo: remove dependents (child associations)
-      await this.entity.remove({ [this.idName]: this.getId() }).go();
+      const dependents = await this.#fetchDependents();
+      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`);
+
+      await Promise.all(removePromises);
+
+      this.#invalidateCache();
+
       return this;
     } catch (error) {
       this.log.error('Failed to remove record', error);
@@ -221,14 +222,33 @@ class BaseModel {
   async save() {
     // todo: validate associations
     try {
+      this.log.info(`Saving entity ${this.entityName} with ID ${this.getId()}`);
+
       await this.patcher.save();
-      // todo: in case references are updated, clear or refresh references cache
+      this.#invalidateCache();
+
       return this;
     } catch (error) {
       this.log.error('Failed to save record', error);
       throw error;
     }
   }
+
+  /**
+   * Converts the entity attributes to a JSON object.
+   * @returns {Object} - A JSON representation of the entity attributes.
+   */
+  toJSON() {
+    const attributes = this.schema.getAttributes();
+
+    return Object.keys(attributes).reduce((json, key) => {
+      if (this.record[key] !== undefined) {
+        // eslint-disable-next-line no-param-reassign
+        json[key] = this.record[key];
+      }
+      return json;
+    }, {});
+  }
 }
 
 export default BaseModel;

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

@@ -0,0 +1,17 @@
+/*
+ * 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.
+ */
+export const INDEX_TYPES = {
+  PRIMARY: 'primary',
+  ALL: 'all',
+  BELONGS_TO: 'belongs_to',
+  OTHER: 'other',
+};

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

@@ -0,0 +1,137 @@
+/*
+ * 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 { collectionNameToEntityName, decapitalize } from '../../util/util.js';
+
+import ApiKeyCollection from '../api-key/api-key.collection.js';
+import AuditCollection from '../audit/audit.collection.js';
+import ConfigurationCollection from '../configuration/configuration.collection.js';
+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 OpportunityCollection from '../opportunity/opportunity.collection.js';
+import OrganizationCollection from '../organization/organization.collection.js';
+import SiteCandidateCollection from '../site-candidate/site-candidate.collection.js';
+import SiteCollection from '../site/site.collection.js';
+import SiteTopPageCollection from '../site-top-page/site-top-page.collection.js';
+import SuggestionCollection from '../suggestion/suggestion.collection.js';
+
+import ApiKeySchema from '../api-key/api-key.schema.js';
+import AuditSchema from '../audit/audit.schema.js';
+import ConfigurationSchema from '../configuration/configuration.schema.js';
+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 OpportunitySchema from '../opportunity/opportunity.schema.js';
+import OrganizationSchema from '../organization/organization.schema.js';
+import SiteSchema from '../site/site.schema.js';
+import SiteCandidateSchema from '../site-candidate/site-candidate.schema.js';
+import SiteTopPageSchema from '../site-top-page/site-top-page.schema.js';
+import SuggestionSchema from '../suggestion/suggestion.schema.js';
+
+/**
+ * EntityRegistry - A registry class responsible for managing entities, their schema and collection.
+ *
+ * @class EntityRegistry
+ */
+class EntityRegistry {
+  static entities = {};
+
+  /**
+   * Constructs an instance of EntityRegistry.
+   * @constructor
+   * @param {Object} service - The ElectroDB service instance used to manage entities.
+   * @param {Object} log - A logger for capturing and logging information.
+   */
+  constructor(service, log) {
+    this.service = service;
+    this.log = log;
+    this.collections = new Map();
+
+    this.#initialize();
+  }
+
+  /**
+   * Initializes the collections managed by the EntityRegistry.
+   * This method creates instances of each collection and stores them in an internal map.
+   * @private
+   */
+  #initialize() {
+    Object.values(EntityRegistry.entities).forEach(({ collection: Collection, schema }) => {
+      const collection = new Collection(this.service, this, schema, this.log);
+      this.collections.set(Collection.name, collection);
+    });
+
+    this.#logIndexes();
+  }
+
+  #logIndexes() {
+    // reduce collection schema indexes into object
+    const indexes = Object.values(EntityRegistry.entities).reduce((acc, { schema }) => {
+      acc[schema.getEntityName()] = schema.indexes;
+      return acc;
+    }, {});
+
+    this.log.debug('Indexes:', JSON.stringify(indexes, null, 2));
+  }
+
+  /**
+   * 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.
+   */
+  getCollection(collectionName) {
+    const collection = this.collections.get(collectionName);
+    if (!collection) {
+      throw new Error(`Collection ${collectionName} not found`);
+    }
+    return collection;
+  }
+
+  getCollections() {
+    const collections = {};
+    for (const [key, value] of this.collections) {
+      collections[collectionNameToEntityName(key)] = value;
+    }
+    return collections;
+  }
+
+  static getEntities() {
+    return Object.keys(this.entities).reduce((acc, key) => {
+      acc[key] = this.entities[key].schema.toElectroDBSchema();
+      return acc;
+    }, {});
+  }
+
+  static registerEntity(schema, collection) {
+    this.entities[decapitalize(schema.getEntityName())] = { schema, collection };
+  }
+}
+
+EntityRegistry.registerEntity(ApiKeySchema, ApiKeyCollection);
+EntityRegistry.registerEntity(AuditSchema, AuditCollection);
+EntityRegistry.registerEntity(ConfigurationSchema, ConfigurationCollection);
+EntityRegistry.registerEntity(ExperimentSchema, ExperimentCollection);
+EntityRegistry.registerEntity(ImportJobSchema, ImportJobCollection);
+EntityRegistry.registerEntity(ImportUrlSchema, ImportUrlCollection);
+EntityRegistry.registerEntity(KeyEventSchema, KeyEventCollection);
+EntityRegistry.registerEntity(OpportunitySchema, OpportunityCollection);
+EntityRegistry.registerEntity(OrganizationSchema, OrganizationCollection);
+EntityRegistry.registerEntity(SiteSchema, SiteCollection);
+EntityRegistry.registerEntity(SiteCandidateSchema, SiteCandidateCollection);
+EntityRegistry.registerEntity(SiteTopPageSchema, SiteTopPageCollection);
+EntityRegistry.registerEntity(SuggestionSchema, SuggestionCollection);
+
+export default EntityRegistry;

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

@@ -0,0 +1,83 @@
+/*
+ * 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 type { ValidationError } from '../../errors';
+
+export interface BaseModel {
+  getCreatedAt(): string;
+  getId(): string;
+  getUpdatedAt(): string;
+  remove(): Promise<this>;
+  save(): Promise<this>;
+  toJSON(): object;
+}
+
+export interface MultiStatusCreateResult<T> {
+  createdItems: T[],
+  errorItems: { item: object, error: ValidationError }[],
+}
+
+export interface QueryOptions {
+  index?: string;
+  limit?: number;
+  sort?: string;
+  attributes?: string[];
+}
+
+export interface BaseCollection<T extends BaseModel> {
+  all(sortKeys?: object, options?: QueryOptions): Promise<T[]>;
+  allByIndexKeys(keys: object, options?: QueryOptions): Promise<T[]>;
+  create(item: object): Promise<T>;
+  createMany(items: object[]): Promise<MultiStatusCreateResult<T>>;
+  findByAll(sortKeys?: object, options?: QueryOptions): Promise<T>;
+  findById(id: string): Promise<T>;
+  findByIndexKeys(indexKeys: object): Promise<T>;
+  removeByIds(ids: string[]): Promise<void>;
+}
+
+export interface EntityRegistry {
+  getCollection<T extends BaseModel>(collectionName: string): BaseCollection<T>;
+  getCollections(): BaseCollection<BaseModel>[];
+  getEntities(): object;
+  registerEntity(schema: object, collection: BaseCollection<BaseModel>): void;
+}
+
+export interface Reference {
+  getSortKeys(): string[];
+  getTarget(): string;
+  getType(): string;
+  isRemoveDependents(): boolean;
+}
+
+export interface Schema {
+  getAttribute(name: string): object;
+  getAttributes(): object;
+  getCollectionName(): string;
+  getEntityName(): string;
+  getIdName(): string;
+  getIndexes(): object;
+  getIndexKeys(indexName: string): string[];
+  getModelClass(): object;
+  getModelName(): string;
+  getReferences(): Reference[];
+  getReferencesByType(referenceType: string): Reference[];
+  getReferenceByTypeAndTarget(referenceType: string, target: string): Reference | undefined;
+}
+
+export interface SchemaBuilder {
+  addAttribute(name: string, data: object): SchemaBuilder;
+  addAllIndexWithComposite(...attributeNames: string[]): SchemaBuilder
+  addAllIndexWithTemplateField(fieldName: string, template: string): SchemaBuilder;
+  addIndex(name: string, partitionKey: object, sortKey: object): SchemaBuilder;
+  addReference(referenceType: string, entityName: string, sortKeys?: string[]): SchemaBuilder;
+  build(): Schema;
+}

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

@@ -0,0 +1,27 @@
+/*
+ * 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 BaseModel from './base.model.js';
+import BaseCollection from './base.collection.js';
+import EntityRegistry from './entity.registry.js';
+import Reference from './reference.js';
+import Schema from './schema.js';
+import SchemaBuilder from './schema.builder.js';
+
+export {
+  BaseModel,
+  BaseCollection,
+  EntityRegistry,
+  Reference,
+  Schema,
+  SchemaBuilder,
+};