@adobe/spacecat-shared-data-access 1.53.0 → 1.54.0

package/src/v2/util/guards.js

@@ -0,0 +1,165 @@
+/*
+ * 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, isNumber, isObject } from '@adobe/spacecat-shared-utils';
+import { validate as validateUUID } from 'uuid';
+
+import { ValidationError } from '../errors/index.js';
+
+/**
+ * Checks if a value is nullable and if the value is null or undefined.
+ * @param {any} value - The value to check.
+ * @param {boolean} nullable - Whether the value is nullable.
+ * @return {boolean} True if the value is nullable and null or undefined, false otherwise.
+ */
+const checkNullable = (value, nullable) => nullable && (value === null || value === undefined);
+
+/**
+ * Checks if a value is of a given type.
+ * Supported types are 'string', 'number', 'boolean', 'object', and 'uuid'.
+ * @param {any} value
+ * @param {string} type
+ * @return {boolean} True if the value is of the given type, false otherwise.
+ */
+const checkType = (value, type) => {
+  switch (type) {
+    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}`);
+  }
+};
+
+/**
+ * Validates that a given property of any type is not null or undefined.
+ * @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 null or undefined.
+ */
+export const guardAny = (propertyName, value, entityName, nullable = false) => {
+  if (!checkNullable(value, nullable) && (value === undefined || value === null)) {
+    throw new ValidationError(`Validation failed in ${entityName}: ${propertyName} is required`);
+  }
+};
+
+export const guardArray = (propertyName, value, entityName, type = 'string', nullable = false) => {
+  if (checkNullable(value, nullable)) return;
+  if (!Array.isArray(value)) {
+    throw new ValidationError(`Validation failed in ${entityName}: ${propertyName} must be an array`);
+  }
+  if (!value.every((v) => checkType(v, type))) {
+    throw new ValidationError(`Validation failed in ${entityName}: ${propertyName} must contain items of type ${type}`);
+  }
+};
+
+/**
+ * Validates that a given property is a set (unique array) of a given type (defaults to string).
+ * @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 {String} [type] - The type of the items in the set. Defaults to 'string'.
+ * @param {boolean} [nullable] - Whether the value is nullable. Defaults to false.
+ * @throws Will throw an error if the value is not a valid set (unique array) of a given type.
+ */
+export const guardSet = (propertyName, value, entityName, type = 'string', nullable = false) => {
+  if (checkNullable(value, nullable)) return;
+  if (!Array.isArray(value) || new Set(value).size !== value.length) {
+    throw new ValidationError(`Validation failed in ${entityName}: ${propertyName} must be a unique array (set)`);
+  }
+  if (!value.every((v) => checkType(v, type))) {
+    throw new ValidationError(`Validation failed in ${entityName}: ${propertyName} must contain items of type ${type}`);
+  }
+};
+
+/**
+ * Validates that a given property is a string.
+ * @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 string.
+ */
+export const guardString = (propertyName, value, entityName, nullable = false) => {
+  if (checkNullable(value, nullable)) return;
+  if (!hasText(value)) {
+    throw new ValidationError(`Validation failed in ${entityName}: ${propertyName} is required`);
+  }
+};
+
+/**
+ * Validates that a given property is of an enum type.
+ * @param {String} propertyName - Name of the property being validated.
+ * @param {any} value - The value to validate.
+ * @param {Array<String>} enumValues - Allowed enum values.
+ * @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 enum value.
+ */
+export const guardEnum = (propertyName, value, enumValues, entityName, nullable = false) => {
+  if (checkNullable(value, nullable)) return;
+  if (!enumValues.includes(value)) {
+    throw new ValidationError(`Validation failed in ${entityName}: ${propertyName} must be one of ${enumValues}`);
+  }
+};
+
+/**
+ * Validates that a given property is a valid ID.
+ * @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 ID.
+ */
+export const guardId = (propertyName, value, entityName, nullable = false) => {
+  if (checkNullable(value, nullable)) return;
+  if (!validateUUID(value)) {
+    throw new ValidationError(`Validation failed in ${entityName}: ${propertyName} must be a valid UUID`);
+  }
+};
+
+/**
+ * Validates that a given property is a map (object).
+ * @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 map (object).
+ */
+export const guardMap = (propertyName, value, entityName, nullable = false) => {
+  if (checkNullable(value, nullable)) return;
+  if (!isObject(value)) {
+    throw new ValidationError(`Validation failed in ${entityName}: ${propertyName} must be an object`);
+  }
+};
+
+/**
+ * Validates that a given property is a number.
+ * @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 number.
+ */
+export const guardNumber = (propertyName, value, entityName, nullable = false) => {
+  if (checkNullable(value, nullable)) return;
+  if (!isNumber(value)) {
+    throw new ValidationError(`Validation failed in ${entityName}: ${propertyName} must be a number`);
+  }
+};

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

@@ -0,0 +1,13 @@
+/*
+ * 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 type * from './guards.d.ts';

package/src/v2/util/index.js

@@ -0,0 +1,22 @@
+/*
+ * 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 {
+  guardAny,
+  guardArray,
+  guardEnum,
+  guardId,
+  guardMap,
+  guardNumber,
+  guardSet,
+  guardString,
+} from './guards.js';

package/src/v2/util/patcher.js

@@ -0,0 +1,183 @@
+/*
+ * 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 { isObject } from '@adobe/spacecat-shared-utils';
+
+import ValidationError from '../errors/validation.error.js';
+
+import {
+  guardAny,
+  guardArray,
+  guardEnum,
+  guardId,
+  guardMap,
+  guardNumber,
+  guardSet,
+  guardString,
+} from './index.js';
+
+/**
+ * Checks if a property is read-only and throws an error if it is.
+ * @param {string} propertyName - The name of the property to check.
+ * @param {Object} attribute - The attribute to check.
+ * @throws {Error} - Throws an error if the property is read-only.
+ * @private
+ */
+const checkReadOnly = (propertyName, attribute) => {
+  if (attribute.readOnly) {
+    throw new ValidationError(`The property ${propertyName} is read-only and cannot be updated.`);
+  }
+};
+
+class Patcher {
+  constructor(entity, 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.patchRecord = null;
+  }
+
+  /**
+   * Checks if a property is nullable.
+   * @param {string} propertyName - The name of the property to check.
+   * @return {boolean} True if the property is nullable, false otherwise.
+   * @private
+   */
+  #isAttributeNullable(propertyName) {
+    return !this.model.schema.attributes[propertyName]?.required;
+  }
+
+  /**
+   * 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.
+   * @private
+   */
+  #getCompositeValuesForKey(record, key) {
+    const { indexes } = this.model;
+    const result = {};
+
+    const processComposite = (index, compositeType) => {
+      const compositeArray = index[compositeType]?.facets;
+      if (Array.isArray(compositeArray) && compositeArray.includes(key)) {
+        compositeArray.forEach((compositeKey) => {
+          if (record[compositeKey] !== undefined) {
+            result[compositeKey] = record[compositeKey];
+          }
+        });
+      }
+    };
+
+    Object.values(indexes).forEach((index) => {
+      processComposite(index, 'pk');
+      processComposite(index, 'sk');
+    });
+
+    return result;
+  }
+
+  /**
+   * Sets a property on the record and updates the patch record.
+   * @param {string} propertyName - The name of the property 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;
+  }
+
+  /**
+   * Gets the patch record for the entity. If it does not exist, it will be created.
+   * @return {Object} - The patch record for the entity.
+   * @private
+   */
+  #getPatchRecord() {
+    if (!this.patchRecord) {
+      this.patchRecord = this.entity.patch({ [this.idName]: this.record[this.idName] });
+    }
+    return this.patchRecord;
+  }
+
+  /**
+   * Patches a value for a given property on the entity. This method will validate the value
+   * against the schema and throw an error if the value is invalid. If the value is declared as
+   * a reference, it will validate the ID format.
+   * @param {string} propertyName - The name of the property to patch.
+   * @param {any} value - The value to patch.
+   * @param {boolean} [isReference=false] - Whether the value is a reference to another entity.
+   */
+  patchValue(propertyName, value, isReference = false) {
+    const attribute = this.model.schema?.attributes[propertyName];
+    if (!isObject(attribute)) {
+      throw new ValidationError(`Property ${propertyName} does not exist on entity ${this.entityName}.`);
+    }
+
+    checkReadOnly(propertyName, attribute);
+
+    const nullable = this.#isAttributeNullable(propertyName);
+
+    if (isReference) {
+      guardId(propertyName, value, this.entityName, nullable);
+    } else {
+      switch (attribute.type) {
+        case 'any':
+          guardAny(propertyName, value, this.entityName, nullable);
+          break;
+        case 'enum':
+          guardEnum(propertyName, value, attribute.enumArray, this.entityName, nullable);
+          break;
+        case 'list':
+          guardArray(propertyName, value, this.entityName, attribute.items?.type, nullable);
+          break;
+        case 'map':
+          guardMap(propertyName, value, this.entityName, nullable);
+          break;
+        case 'number':
+          guardNumber(propertyName, value, this.entityName, nullable);
+          break;
+        case 'set':
+          guardSet(propertyName, value, this.entityName, attribute.items?.type, nullable);
+          break;
+        case 'string':
+          guardString(propertyName, value, this.entityName, nullable);
+          break;
+        default:
+          throw new ValidationError(`Unsupported type for property ${propertyName}`);
+      }
+    }
+
+    this.#set(propertyName, value);
+  }
+
+  /**
+   * Saves the current state of the entity to the database.
+   * @return {Promise<void>}
+   * @throws {Error} - Throws an error if the save operation fails.
+   */
+  async save() {
+    await this.#getPatchRecord().go();
+    this.record.updatedAt = new Date().getTime();
+  }
+}
+
+export default Patcher;