@adobe/spacecat-shared-data-access 2.109.0 → 3.0.0

package/src/util/patcher.js

@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import { isNonEmptyArray, isObject } from '@adobe/spacecat-shared-utils';
+import { isObject } from '@adobe/spacecat-shared-utils';
 
 import ValidationError from '../errors/validation.error.js';
 
@@ -26,13 +26,6 @@ import {
   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.`);
@@ -48,137 +41,68 @@ const checkUpdatesAllowed = (schema) => {
 class Patcher {
   /**
    * Creates a new Patcher instance for an entity.
-   * @param {object} entity - The entity backing the record.
+   * @param {object} collection - The backing collection instance.
    * @param {Schema} schema - The schema for the entity.
    * @param {object} record - The record to patch.
    */
-  constructor(entity, schema, record) {
-    this.entity = entity;
+  constructor(collection, schema, record) {
+    this.collection = collection;
     this.schema = schema;
     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.legacyEntity = collection && typeof collection.patch === 'function'
+      ? collection
+      : null;
     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;
-  }
-
-  /**
-   * Composite keys have to be provided to ElectroDB in order to update a record across
-   * 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
-   */
-  #getCompositeValues() {
-    const { indexes } = this.model;
-    const result = {};
-
-    const processComposite = (index, compositeType) => {
-      const compositeArray = index[compositeType]?.facets;
-      if (isNonEmptyArray(compositeArray)) {
-        compositeArray.forEach((compositeKey) => {
-          if (
-            !Object.keys(this.updates).includes(compositeKey)
-            && this.record[compositeKey] !== undefined
-          ) {
-            result[compositeKey] = this.record[compositeKey];
-          }
-        });
-      }
-    };
-
-    Object.values(indexes).forEach((index) => {
-      processComposite(index, 'pk');
-      processComposite(index, 'sk');
-    });
-
-    return result;
+    return !this.schema.getAttribute(propertyName)?.required;
   }
 
-  /**
-   * Sets a property on the record and updates the patch record.
-   * @param {string} attribute - The attribute to set.
-   * @param {any} value - The value to set for the property.
-   * @private
-   */
-  #set(attribute, value) {
-    this.patchRecord = this.#getPatchRecord().set({ [attribute.name]: value });
-
-    const transmutedValue = attribute.get(value, () => {});
+  #set(propertyName, attribute, value) {
     const update = {
-      [attribute.name]: {
-        previous: this.record[attribute.name],
-        current: transmutedValue,
+      [propertyName]: {
+        previous: this.record[propertyName],
+        current: value,
       },
     };
 
-    // update the record with the update value for later save
-    this.record[attribute.name] = transmutedValue;
-
-    // remember the update operation with the previous and current value
+    const hydratedValue = typeof attribute.get === 'function'
+      ? attribute.get(value)
+      : value;
+    this.record[propertyName] = hydratedValue;
     this.updates = { ...this.updates, ...update };
+
+    if (this.legacyEntity) {
+      if (!this.patchRecord) {
+        this.patchRecord = this.legacyEntity.patch(this.#getPrimaryKeyValues());
+      }
+      this.patchRecord = this.patchRecord.set({ [propertyName]: value });
+    }
   }
 
-  /**
-   * Gets the primary key values for the entity from the schema's primary index.
-   * This supports composite primary keys (e.g., siteId + url).
-   * @return {Object} - An object containing the primary key values.
-   * @private
-   */
   #getPrimaryKeyValues() {
     const primaryKeys = this.schema.getIndexKeys('primary');
-    if (isNonEmptyArray(primaryKeys)) {
+    if (Array.isArray(primaryKeys) && primaryKeys.length > 0) {
       return primaryKeys.reduce((acc, key) => {
         acc[key] = this.record[key];
         return acc;
       }, {});
     }
-    // Fallback to default id name
     return { [this.idName]: this.record[this.idName] };
   }
 
-  /**
-   * 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.#getPrimaryKeyValues());
-    }
-    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) {
     checkUpdatesAllowed(this.schema);
 
-    const attribute = this.model.schema?.attributes[propertyName];
+    const attribute = this.schema.getAttribute(propertyName);
     if (!isObject(attribute)) {
       throw new ValidationError(`Property ${propertyName} does not exist on entity ${this.entityName}.`);
     }
@@ -189,6 +113,8 @@ class Patcher {
 
     if (isReference) {
       guardId(propertyName, value, this.entityName, nullable);
+    } else if (Array.isArray(attribute.type)) {
+      guardEnum(propertyName, value, attribute.type, this.entityName, nullable);
     } else {
       switch (attribute.type) {
         case 'any':
@@ -220,14 +146,9 @@ class Patcher {
       }
     }
 
-    this.#set(attribute, value);
+    this.#set(propertyName, attribute, 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() {
     checkUpdatesAllowed(this.schema);
 
@@ -235,11 +156,42 @@ class Patcher {
       return;
     }
 
-    const compositeValues = this.#getCompositeValues();
-    await this.#getPatchRecord()
-      .composite(compositeValues)
-      .go();
-    this.record.updatedAt = new Date().toISOString();
+    const previousUpdatedAt = this.record.updatedAt;
+    let nextUpdatedAt = new Date().toISOString();
+    if (typeof previousUpdatedAt === 'string' && previousUpdatedAt === nextUpdatedAt) {
+      const previousDate = new Date(previousUpdatedAt);
+      if (!Number.isNaN(previousDate.getTime())) {
+        nextUpdatedAt = new Date(previousDate.getTime() + 1000).toISOString();
+      }
+    }
+    this.record.updatedAt = nextUpdatedAt;
+    this.updates.updatedAt = {
+      previous: previousUpdatedAt,
+      current: nextUpdatedAt,
+    };
+
+    const keys = this.#getPrimaryKeyValues();
+    const updates = Object.keys(this.updates).reduce((acc, key) => {
+      acc[key] = this.updates[key].current;
+      return acc;
+    }, {});
+
+    if (this.collection
+      && typeof this.collection.applyUpdateWatchers === 'function'
+      && typeof this.collection.updateByKeys === 'function') {
+      const watched = this.collection.applyUpdateWatchers(this.record, updates);
+      this.record = watched.record;
+      await this.collection.updateByKeys(keys, watched.updates);
+      return;
+    }
+
+    if (this.patchRecord && typeof this.patchRecord.go === 'function') {
+      this.patchRecord = this.patchRecord.set({ updatedAt: nextUpdatedAt });
+      await this.patchRecord.go();
+      return;
+    }
+
+    throw new ValidationError(`No persistence strategy available for ${this.entityName}`);
   }
 
   getUpdates() {

package/src/util/postgrest.utils.js

@@ -0,0 +1,203 @@
+/*
+ * Copyright 2026 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 DEFAULT_PAGE_SIZE = 1000;
+
+const ENTITY_TABLE_OVERRIDES = {
+  LatestAudit: 'audits',
+};
+
+const camelToSnake = (value) => value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+
+const snakeToCamel = (value) => value.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+
+const entityToTableName = (entityName) => {
+  const override = ENTITY_TABLE_OVERRIDES[entityName];
+  if (override) {
+    return override;
+  }
+  return camelToSnake(pluralize.plural(entityName));
+};
+
+const encodeCursor = (offset) => Buffer.from(JSON.stringify({ offset }), 'utf-8').toString('base64');
+
+const decodeCursor = (cursor) => {
+  if (!cursor) {
+    return 0;
+  }
+
+  try {
+    const decoded = JSON.parse(Buffer.from(cursor, 'base64').toString('utf-8'));
+    return Number.isInteger(decoded.offset) && decoded.offset >= 0 ? decoded.offset : 0;
+  } catch (e) {
+    return 0;
+  }
+};
+
+const createFieldMaps = (schema) => {
+  const toDbMap = {};
+  const toModelMap = {};
+  const attributes = schema.getAttributes();
+  const idName = typeof schema.getIdName === 'function' ? schema.getIdName() : undefined;
+  Object.keys(attributes).forEach((modelField) => {
+    const attribute = attributes[modelField] || {};
+    if (attribute.postgrestIgnore) {
+      return;
+    }
+    const dbField = attribute.postgrestField
+      || (modelField === idName && modelField !== 'id' ? 'id' : camelToSnake(modelField));
+    toDbMap[modelField] = dbField;
+    toModelMap[dbField] = modelField;
+  });
+
+  const idAttribute = idName ? attributes[idName] : undefined;
+  if (idName
+    && idName !== 'id'
+    && idAttribute
+    && !idAttribute.postgrestIgnore) {
+    toDbMap[idName] = 'id';
+    toModelMap.id = idName;
+  }
+
+  return { toDbMap, toModelMap };
+};
+
+const toDbField = (field, map) => map[field] || camelToSnake(field);
+
+const toModelField = (field, map) => map[field] || snakeToCamel(field);
+
+const toDbRecord = (record, toDbMap, options = {}) => {
+  const { includeUnknown = false } = options;
+  return Object.entries(record).reduce((acc, [key, value]) => {
+    if (Object.prototype.hasOwnProperty.call(toDbMap, key)) {
+      acc[toDbMap[key]] = value;
+      return acc;
+    }
+
+    if (includeUnknown) {
+      acc[toDbField(key, toDbMap)] = value;
+    }
+
+    return acc;
+  }, {});
+};
+
+const looksLikeIsoDateTime = (value) => typeof value === 'string'
+  && /^\d{4}-\d{2}-\d{2}T/.test(value)
+  && /(?:Z|[+-]\d{2}:\d{2})$/.test(value);
+
+const normalizeModelValue = (value) => {
+  if (value === null) {
+    return undefined;
+  }
+
+  // PostgREST can return jsonb null scalars as [null] for some projections/aggregations.
+  // We normalize this artifact to "missing" so model payloads match v2 behavior.
+  if (Array.isArray(value) && value.length === 1 && value[0] === null) {
+    return undefined;
+  }
+
+  if (looksLikeIsoDateTime(value)) {
+    const date = new Date(value);
+    if (!Number.isNaN(date.getTime())) {
+      return date.toISOString();
+    }
+  }
+
+  return value;
+};
+
+const fromDbRecord = (record, toModelMap) => Object.entries(record).reduce((acc, [key, value]) => {
+  const normalized = normalizeModelValue(value);
+  if (normalized !== undefined) {
+    acc[toModelField(key, toModelMap)] = normalized;
+  }
+  return acc;
+}, {});
+
+const applyWhere = (query, whereFn, toDbMap) => {
+  if (typeof whereFn !== 'function') {
+    return query;
+  }
+
+  const attrs = new Proxy({}, {
+    get: (_, prop) => toDbField(String(prop), toDbMap),
+  });
+
+  const op = {
+    eq: (field, value) => ({ type: 'eq', field, value }),
+    ne: (field, value) => ({ type: 'ne', field, value }),
+    gt: (field, value) => ({ type: 'gt', field, value }),
+    gte: (field, value) => ({ type: 'gte', field, value }),
+    lt: (field, value) => ({ type: 'lt', field, value }),
+    lte: (field, value) => ({ type: 'lte', field, value }),
+    in: (field, value) => ({ type: 'in', field, value }),
+    is: (field, value) => ({ type: 'is', field, value }),
+    like: (field, value) => ({ type: 'like', field, value }),
+    ilike: (field, value) => ({ type: 'ilike', field, value }),
+    contains: (field, value) => ({ type: 'contains', field, value }),
+  };
+
+  const expression = whereFn(attrs, op);
+  if (!expression || typeof expression !== 'object') {
+    return query;
+  }
+
+  switch (expression.type) {
+    case 'eq':
+      return query.eq(expression.field, expression.value);
+    case 'ne':
+      return query.neq(expression.field, expression.value);
+    case 'gt':
+      return query.gt(expression.field, expression.value);
+    case 'gte':
+      return query.gte(expression.field, expression.value);
+    case 'lt':
+      return query.lt(expression.field, expression.value);
+    case 'lte':
+      return query.lte(expression.field, expression.value);
+    case 'in':
+      return query.in(
+        expression.field,
+        Array.isArray(expression.value) ? expression.value : [expression.value],
+      );
+    case 'is':
+      return query.is(expression.field, expression.value);
+    case 'like':
+      return query.like(expression.field, expression.value);
+    case 'ilike':
+      return query.ilike(expression.field, expression.value);
+    case 'contains': {
+      const value = Array.isArray(expression.value) ? expression.value : [expression.value];
+      return query.contains(expression.field, value);
+    }
+    default:
+      throw new Error(`Unsupported where operator: ${expression.type}`);
+  }
+};
+
+export {
+  DEFAULT_PAGE_SIZE,
+  applyWhere,
+  camelToSnake,
+  createFieldMaps,
+  decodeCursor,
+  encodeCursor,
+  entityToTableName,
+  fromDbRecord,
+  snakeToCamel,
+  toDbField,
+  toDbRecord,
+  toModelField,
+};

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "test"]
+}