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

package/src/v2/util/accessor.utils.js

@@ -0,0 +1,158 @@
+/*
+ * 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 { hasText, isNonEmptyObject, isNumber } from '@adobe/spacecat-shared-utils';
+
+import ValidationError from '../errors/validation.error.js';
+
+function validateValue(context, keyName, value) {
+  const { type } = context.schema.getAttribute(keyName);
+  const validator = type === 'number' ? isNumber : hasText;
+
+  if (!validator(value)) {
+    throw new ValidationError(`${keyName} is required`);
+  }
+}
+
+function parseAccessorArgs(context, requiredKeyNames, args) {
+  const keys = {};
+  for (let i = 0; i < requiredKeyNames.length; i += 1) {
+    const keyName = requiredKeyNames[i];
+    const keyValue = args[i];
+
+    validateValue(context, keyName, keyValue);
+
+    keys[keyName] = keyValue;
+  }
+
+  let options = {};
+
+  if (args.length > requiredKeyNames.length) {
+    options = args[requiredKeyNames.length];
+  }
+
+  return { keys, options };
+}
+
+function validateConfig(config) {
+  if (!isNonEmptyObject(config)) {
+    throw new Error('Config is required');
+  }
+
+  const {
+    collection, context, name, requiredKeys,
+  } = config;
+
+  if (!isNonEmptyObject(collection)) {
+    throw new Error('Collection is required');
+  }
+
+  if (!isNonEmptyObject(context)) {
+    throw new Error('Context is required');
+  }
+
+  if (!hasText(name)) {
+    throw new Error('Name is required');
+  }
+
+  if (!Array.isArray(requiredKeys)) {
+    throw new Error('Required keys must be an array');
+  }
+}
+
+/**
+ * Create an accessor for a collection. The accessor can be used to query the collection.
+ * @param {object} config - The accessor configuration.
+ * @param {boolean} [config.all=false] - Whether to return all items in the collection.
+ * @param {boolean} [config.byId=false] - Whether to return an item by ID.
+ * @param {object} config.collection - The collection to query.
+ * @param {object} config.context - The context to attach the accessor to.
+ * @param {object} [config.foreignKey] - The foreign key to use when querying by ID.
+ * @param {string} config.name - The name of the accessor.
+ * @param {string[]} [config.requiredKeys] - The required keys for the accessor.
+ * @throws {Error} - If the configuration is invalid.
+ * @returns {void}
+ */
+export function createAccessor(config) { /* eslint-disable no-underscore-dangle */
+  validateConfig(config);
+
+  const {
+    all = false,
+    byId = false,
+    collection,
+    context,
+    foreignKey,
+    name,
+    requiredKeys = [],
+  } = config;
+  if (!context._accessorCache) {
+    Object.defineProperty(context, '_accessorCache', {
+      enumerable: false,
+      configurable: true,
+      writable: true,
+      value: {},
+    });
+  }
+
+  const foreignKeys = {
+    ...isNonEmptyObject(foreignKey) && { [foreignKey.name]: foreignKey.value },
+  };
+
+  const accessor = async (...args) => {
+    const argsKey = args.length > 0 ? JSON.stringify(args) : '_';
+    const cacheKey = `${name}:${argsKey}`;
+
+    if (context._accessorCache[cacheKey] !== undefined) {
+      return context._accessorCache[cacheKey];
+    }
+
+    let result;
+
+    if (byId) {
+      if (!hasText(foreignKey.value)) {
+        result = null;
+      } else {
+        result = collection.findById(foreignKey.value);
+      }
+    } else {
+      const { keys, options } = parseAccessorArgs(collection, requiredKeys, args);
+      const allKeys = { ...foreignKeys, ...keys };
+
+      result = all
+        ? collection.allByIndexKeys(allKeys, options)
+        : collection.findByIndexKeys(allKeys, options);
+    }
+
+    result = await result;
+    context._accessorCache[cacheKey] = result;
+
+    return result;
+  };
+
+  Object.defineProperty(
+    context,
+    name,
+    {
+      enumerable: false,
+      configurable: false,
+      writable: true,
+      value: accessor,
+    },
+  );
+}
+
+export function createAccessors(configs, log) {
+  configs.forEach((config) => {
+    createAccessor(config);
+    log.info(`Created accessor ${config.name} for ${config.context.schema.getModelName()} to ${config.collection.schema.getModelName()}`);
+  });
+}

package/src/v2/util/guards.d.ts

@@ -25,6 +25,13 @@ export function guardAny(
   nullable?: boolean,
 ): void;
 
+export function guardBoolean(
+  propertyName: string,
+  value: never,
+  entityName: string,
+  nullable?: boolean,
+): void;
+
 export function guardEnum(
   propertyName: string,
   value: never,

package/src/v2/util/guards.js

@@ -32,14 +32,16 @@ const checkNullable = (value, nullable) => nullable && (value === null || value
  */
 const checkType = (value, type) => {
   switch (type) {
+    case 'any':
+      return isObject(value);
+    case 'boolean':
+      return typeof value === 'boolean';
+    case 'map':
+      return isObject(value);
     case 'string':
       return typeof value === 'string';
     case 'number':
       return typeof value === 'number';
-    case 'boolean':
-      return typeof value === 'boolean';
-    case 'object':
-      return isObject(value);
     default:
       throw new ValidationError(`Unsupported type: ${type}`);
   }
@@ -59,6 +61,21 @@ export const guardAny = (propertyName, value, entityName, nullable = false) => {
   }
 };
 
+/**
+ * Validates that a given property is a boolean.
+ * @param {String} propertyName - Name of the property being validated.
+ * @param {any} value - The value to validate.
+ * @param {String} entityName - Name of the entity containing this property.
+ * @param {boolean} [nullable] - Whether the value is nullable. Defaults to false.
+ * @throws Will throw an error if the value is not a valid boolean.
+ */
+export const guardBoolean = (propertyName, value, entityName, nullable = false) => {
+  if (checkNullable(value, nullable)) return;
+  if (typeof value !== 'boolean') {
+    throw new ValidationError(`Validation failed in ${entityName}: ${propertyName} must be a boolean`);
+  }
+};
+
 export const guardArray = (propertyName, value, entityName, type = 'string', nullable = false) => {
   if (checkNullable(value, nullable)) return;
   if (!Array.isArray(value)) {

package/src/v2/util/index.js

@@ -13,6 +13,7 @@
 export {
   guardAny,
   guardArray,
+  guardBoolean,
   guardEnum,
   guardId,
   guardMap,

package/src/v2/util/patcher.js

@@ -16,6 +16,7 @@ import ValidationError from '../errors/validation.error.js';
 
 import {
   guardAny,
+  guardBoolean,
   guardArray,
   guardEnum,
   guardId,
@@ -24,6 +25,7 @@ import {
   guardSet,
   guardString,
 } from './index.js';
+import { isNonEmptyArray } from './util.js';
 
 /**
  * Checks if a property is read-only and throws an error if it is.
@@ -39,12 +41,24 @@ const checkReadOnly = (propertyName, attribute) => {
 };
 
 class Patcher {
-  constructor(entity, record) {
+  /**
+   * Creates a new Patcher instance for an entity.
+   * @param {object} entity - The entity backing the record.
+   * @param {Schema} schema - The schema for the entity.
+   * @param {object} record - The record to patch.
+   */
+  constructor(entity, schema, record) {
     this.entity = entity;
-    this.entityName = this.entity.model.name.toLowerCase();
-    this.model = entity.model;
-    this.idName = `${this.model.name.toLowerCase()}Id`;
     this.record = record;
+
+    this.entityName = schema.getEntityName();
+    this.model = entity.model;
+    this.idName = schema.getIdName();
+
+    // holds the previous value of updated attributes
+    this.previous = {};
+
+    // holds the updates to the attributes
     this.updates = {};
 
     this.patchRecord = null;
@@ -61,24 +75,25 @@ class Patcher {
   }
 
   /**
-   * Gets the composite values for a given key from the entity schema.
    * Composite keys have to be provided to ElectroDB in order to update a record across
-   * multiple indexes.
-   * @param {Object} record - The record to get the composite values from.
-   * @param {string} key - The key to get the composite values for.
-   * @return {{}} - An object containing the composite values for the given key.
+   * multiple indexes. This method retrieves the composite values for the entity from
+   * the schema indexes and filters out any values that are being updated.
+   * @return {{}} - An object containing the composite values for the entity.
    * @private
    */
-  #getCompositeValuesForKey(record, key) {
+  #getCompositeValues() {
     const { indexes } = this.model;
     const result = {};
 
     const processComposite = (index, compositeType) => {
       const compositeArray = index[compositeType]?.facets;
-      if (Array.isArray(compositeArray) && compositeArray.includes(key)) {
+      if (isNonEmptyArray(compositeArray)) {
         compositeArray.forEach((compositeKey) => {
-          if (record[compositeKey] !== undefined) {
-            result[compositeKey] = record[compositeKey];
+          if (
+            !Object.keys(this.updates).includes(compositeKey)
+            && this.record[compositeKey] !== undefined
+          ) {
+            result[compositeKey] = this.record[compositeKey];
           }
         });
       }
@@ -94,18 +109,25 @@ class Patcher {
 
   /**
    * Sets a property on the record and updates the patch record.
-   * @param {string} propertyName - The name of the property to set.
+   * @param {string} attribute - The attribute to set.
    * @param {any} value - The value to set for the property.
    * @private
    */
-  #set(propertyName, value) {
-    const compositeValues = this.#getCompositeValuesForKey(this.record, propertyName);
-    this.patchRecord = this.#getPatchRecord().set({
-      ...compositeValues,
-      [propertyName]: value,
-    });
-    this.record[propertyName] = value;
-    this.updates[propertyName] = value;
+  #set(attribute, value) {
+    this.patchRecord = this.#getPatchRecord().set({ [attribute.name]: value });
+
+    const update = {
+      [attribute.name]: {
+        previous: this.record[attribute.name],
+        current: value,
+      },
+    };
+
+    // update the record with the update value for later save
+    this.record[attribute.name] = value;
+
+    // remember the update operation with the previous and current value
+    this.updates = { ...this.updates, ...update };
   }
 
   /**
@@ -145,6 +167,9 @@ class Patcher {
         case 'any':
           guardAny(propertyName, value, this.entityName, nullable);
           break;
+        case 'boolean':
+          guardBoolean(propertyName, value, this.entityName, nullable);
+          break;
         case 'enum':
           guardEnum(propertyName, value, attribute.enumArray, this.entityName, nullable);
           break;
@@ -168,7 +193,7 @@ class Patcher {
       }
     }
 
-    this.#set(propertyName, value);
+    this.#set(attribute, value);
   }
 
   /**
@@ -180,8 +205,12 @@ class Patcher {
     if (!this.hasUpdates()) {
       return;
     }
-    await this.#getPatchRecord().go();
-    this.record.updatedAt = new Date().getTime();
+
+    const compositeValues = this.#getCompositeValues();
+    await this.#getPatchRecord()
+      .composite(compositeValues)
+      .go();
+    this.record.updatedAt = new Date().toISOString();
   }
 
   getUpdates() {

package/src/v2/util/util.js

@@ -0,0 +1,84 @@
+/*
+ * 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 { hasText, isInteger } from '@adobe/spacecat-shared-utils';
+import pluralize from 'pluralize';
+
+const capitalize = (str) => (hasText(str) ? str[0].toUpperCase() + str.slice(1) : '');
+
+const classExtends = (clazz, base) => (typeof clazz === 'function' && clazz.prototype instanceof base);
+
+const decapitalize = (str) => (hasText(str) ? str[0].toLowerCase() + str.slice(1) : '');
+
+const collectionNameToEntityName = (collectionName) => collectionName.replace('Collection', '');
+
+const entityNameToCollectionName = (entityName) => `${capitalize(pluralize.singular(entityName))}Collection`;
+
+const entityNameToIdName = (entityName) => `${decapitalize(pluralize.singular(entityName))}Id`;
+
+const referenceToBaseMethodName = (reference) => {
+  const target = capitalize(reference.getTarget());
+  const baseName = reference.getType() === 'has_many'
+    ? pluralize.plural(target)
+    : pluralize.singular(target);
+
+  return `get${baseName}`;
+};
+
+const entityNameToAllPKValue = (entityName) => `ALL_${pluralize.plural(entityName.toUpperCase())}`;
+
+const idNameToEntityName = (idName) => capitalize(pluralize.singular(idName.replace('Id', '')));
+
+const isPositiveInteger = (value) => isInteger(value) && value > 0;
+
+const keyNamesToIndexName = (keyNames) => `by${keyNames.map(capitalize).join('And')}`;
+
+const keyNamesToMethodName = (keyNames, prefix) => prefix + keyNames.map(capitalize).join('And');
+
+const modelNameToEntityName = (modelName) => decapitalize(modelName);
+
+const sanitizeTimestamps = (data) => {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { createdAt, updatedAt, ...rest } = data;
+  return rest;
+};
+
+const sanitizeIdAndAuditFields = (entityName, data) => {
+  const idName = entityNameToIdName(entityName);
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { [idName]: _, ...rest } = data;
+  return sanitizeTimestamps(rest);
+};
+
+const incrementVersion = (version) => (isInteger(version) ? parseInt(version, 10) + 1 : 1);
+
+const isNonEmptyArray = (value) => Array.isArray(value) && value.length > 0;
+
+export {
+  capitalize,
+  classExtends,
+  collectionNameToEntityName,
+  decapitalize,
+  entityNameToAllPKValue,
+  entityNameToCollectionName,
+  entityNameToIdName,
+  idNameToEntityName,
+  incrementVersion,
+  isNonEmptyArray,
+  isPositiveInteger,
+  keyNamesToIndexName,
+  keyNamesToMethodName,
+  modelNameToEntityName,
+  referenceToBaseMethodName,
+  sanitizeIdAndAuditFields,
+  sanitizeTimestamps,
+};