@cap-js/change-tracking 1.1.4 → 2.0.0-beta.2

package/package.json

@@ -1,6 +1,10 @@
 {
 	"name": "@cap-js/change-tracking",
-	"version": "1.1.4",
+	"version": "2.0.0-beta.2",
+	"publishConfig": {
+		"access": "public",
+		"tag": "beta"
+	},
 	"description": "CDS plugin providing out-of-the box support for automatic capturing, storing, and viewing of the change records of modeled entities.",
 	"repository": "cap-js/change-tracking",
 	"author": "SAP SE (https://www.sap.com)",
@@ -16,6 +20,13 @@
 	"scripts": {
 		"lint": "npx eslint .",
 		"test": "npx jest --silent",
+		"test:sqlite": "CDS_ENV=sqlite npx jest --silent",
+		"test:postgres": "npm run start:pg && CDS_ENV=pg npx jest --runInBand --silent",
+		"test:hana": "npm run start:hana && cds bind --exec -- npx jest --silent",
+		"start:pg": "cd tests/bookshop/ && docker compose -f pg-stack.yml up -d && npm run deploy:postgres && cd ../..",
+		"deploy:postgres": "CDS_ENV=pg cds build --production && cds deploy --profile pg",
+		"start:hana": "cd tests/bookshop/ && cds deploy -2 hana && cd ../..",
+		"test:all": "npm run test:sqlite && npm run test:postgres && npm run test:hana",
 		"format": "npx -y prettier@3 . --write",
 		"format:check": "npx -y prettier@3 --check ."
 	},
@@ -26,22 +37,21 @@
 		"node": ">=20.0.0"
 	},
 	"devDependencies": {
-		"@cap-js/attachments": "^2",
 		"@cap-js/cds-test": "*",
-		"@cap-js/change-tracking": "file:.",
-		"@cap-js/sqlite": "^1 || ^2",
-		"express": "^4"
+		"@cap-js/cds-types": "^0.16.0"
 	},
 	"cds": {
 		"requires": {
 			"change-tracking": {
 				"model": "@cap-js/change-tracking",
-				"considerLocalizedValues": false
+				"considerLocalizedValues": false,
+				"maxDisplayHierarchyDepth": 3,
+				"preserveDeletes": false
 			}
 		}
 	},
 	"jest": {
-		"testTimeout": 10000
+		"testTimeout": 180000
 	},
 	"workspaces": [
 		"tests/*"

package/lib/change-log.js

@@ -1,538 +0,0 @@
-const cds = require('@sap/cds');
-const getTemplate = require('@sap/cds/libx/_runtime/common/utils/template'); // REVISIT: bad usage of internal stuff
-const { templateProcessor, retrieveFirstKey } = require('./template-processor');
-const LOG = cds.log('change-log');
-
-const { getNameFromPathVal, getUUIDFromPathVal, getCurObjFromReqData, getCurObjFromDbQuery, getObjectId, getDBEntity, getEntityByContextPath, getObjIdElementNamesInArray, getValueEntityType, splitPath } = require('./entity-helper');
-const { localizeLogFields } = require('./localization');
-const isRoot = 'change-tracking-isRootEntity';
-const hasParent = 'change-tracking-parentEntity';
-
-function formatDecimal(str, scale) {
-	if (typeof str === 'number' && !isNaN(str)) {
-		str = String(str);
-	} else return str;
-
-	if (scale > 0) {
-		let parts = str.split('.');
-		let decimalPart = parts[1] || '';
-
-		while (decimalPart.length < scale) {
-			decimalPart += '0';
-		}
-
-		return `${parts[0]}.${decimalPart}`;
-	}
-
-	return str;
-}
-
-const _getRootEntityPathVals = function (txContext, entity, entityKey) {
-	const serviceEntityPathVals = [];
-	const entityIDs = _getEntityIDs(txContext.params);
-
-	let path = txContext.path.split('/');
-
-	if (txContext.event === 'CREATE') {
-		const curEntityPathVal = `${entity.name}(${entityKey})`;
-		serviceEntityPathVals.push(curEntityPathVal);
-		txContext.hasComp && entityIDs.pop();
-	} else {
-		// When deleting Composition of one node via REST API in draft-disabled mode,
-		// the child node ID would be missing in URI
-		if (txContext.event === 'DELETE' && !entityIDs.find((x) => x === entityKey)) {
-			entityIDs.push(entityKey);
-		}
-		const curEntity = getEntityByContextPath(path, txContext.hasComp);
-		const curEntityID = entityIDs.pop();
-		const curEntityPathVal = `${curEntity.name}(${curEntityID})`;
-		serviceEntityPathVals.push(curEntityPathVal);
-	}
-
-	while (_isCompositionContextPath(path, txContext.hasComp)) {
-		const hostEntity = getEntityByContextPath((path = path.slice(0, -1)), txContext.hasComp);
-		const hostEntityID = entityIDs.pop();
-		const hostEntityPathVal = `${hostEntity.name}(${hostEntityID})`;
-		serviceEntityPathVals.unshift(hostEntityPathVal);
-	}
-
-	return serviceEntityPathVals;
-};
-
-const _getAllPathVals = function (txContext) {
-	const pathVals = [];
-	const paths = txContext.path.split('/');
-	const entityIDs = _getEntityIDs(txContext.params);
-
-	for (let idx = 0; idx < paths.length; idx++) {
-		const entity = getEntityByContextPath(paths.slice(0, idx + 1), txContext.hasComp);
-		const entityID = entityIDs[idx];
-		const entityPathVal = `${entity.name}(${entityID})`;
-		pathVals.push(entityPathVal);
-	}
-
-	return pathVals;
-};
-
-function convertSubjectToParams(subject) {
-	let params = [];
-	let subjectRef = [];
-	subject?.ref?.forEach((item) => {
-		if (typeof item === 'string') {
-			subjectRef.push(item);
-			return;
-		}
-
-		const keys = {};
-		let id = item.id;
-		if (!id) return;
-		for (let j = 0; j < item?.where?.length; j = j + 4) {
-			const key = item.where[j].ref[0];
-			const value = item.where[j + 2].val;
-			if (key !== 'IsActiveEntity') keys[key] = value;
-		}
-		params.push(keys);
-	});
-	return params.length > 0 ? params : subjectRef;
-}
-
-const _getEntityIDs = function (txParams) {
-	const entityIDs = [];
-	for (const param of txParams) {
-		let id = '';
-		if (typeof param === 'object' && !Array.isArray(param)) {
-			id = param.ID;
-		}
-		if (typeof param === 'string') {
-			id = param;
-		}
-		if (id) {
-			entityIDs.push(id);
-		}
-	}
-	return entityIDs;
-};
-
-/**
- *
- * @param {*} tx
- * @param {*} changes
- *
- * When consuming app implement '@changelog' on an association element,
- * change history will use attribute on associated entity which are specified instead of default technical foreign key.
- *
- * eg:
- * entity PurchasedProductFootprints    @(cds.autoexpose): cuid, managed {
- * ...
- * '@changelog': [Plant.identifier]
- * '@mandatory' Plant : Association to one Plant;
- * ...
- * }
- */
-const _formatAssociationContext = async function (changes, reqData) {
-	for (const change of changes) {
-		const a = cds.model.definitions[change.serviceEntity].elements[change.attribute];
-		if (a?.type !== 'cds.Association') continue;
-
-		const semkeys = getObjIdElementNamesInArray(a['@changelog']);
-		if (!semkeys.length) continue;
-
-		const ID = a.keys[0].ref[0] || 'ID';
-		const [[from], [to]] = await cds.db.run(
-			cds.env.requires['change-tracking'].considerLocalizedValues
-				? [
-						SELECT.localized
-							.from(a.target)
-							.where({ [ID]: change.valueChangedFrom })
-							.limit(1),
-						SELECT.localized
-							.from(a.target)
-							.where({ [ID]: change.valueChangedTo })
-							.limit(1)
-					]
-				: [
-						SELECT.from(a.target)
-							.where({ [ID]: change.valueChangedFrom })
-							.limit(1),
-						SELECT.from(a.target)
-							.where({ [ID]: change.valueChangedTo })
-							.limit(1)
-					]
-		);
-
-		const fromObjId = await getObjectId(reqData, a.target, semkeys, { curObjFromDbQuery: from || undefined }); // Note: ... || undefined is important for subsequent object destructuring with defaults
-		if (fromObjId) change.valueChangedFrom = fromObjId;
-
-		const toObjId = await getObjectId(reqData, a.target, semkeys, { curObjFromDbQuery: to || undefined }); // Note: ... || undefined is important for subsequent object destructuring with defaults
-		if (toObjId) change.valueChangedTo = toObjId;
-
-		const isVLvA = a['@Common.ValueList.viaAssociation'];
-		if (!isVLvA) change.valueDataType = getValueEntityType(a.target, semkeys);
-	}
-};
-
-const _getChildChangeObjId = async function (change, childNodeChange, curNodePathVal, reqData, target) {
-	const composition = cds.model.definitions[change.serviceEntity].elements[change.attribute];
-	const objIdElements = composition ? composition['@changelog'] : null;
-	const objIdElementNames = getObjIdElementNamesInArray(objIdElements);
-
-	return _getObjectIdByPath(reqData, curNodePathVal, childNodeChange._path, target, objIdElementNames);
-};
-
-const _formatCompositionContext = async function (changes, reqData, target) {
-	const childNodeChanges = [];
-
-	for (const change of changes) {
-		if (typeof change.valueChangedTo === 'object' && change.valueChangedTo instanceof Date !== true) {
-			if (!Array.isArray(change.valueChangedTo)) {
-				change.valueChangedTo = [change.valueChangedTo];
-			}
-			for (const childNodeChange of change.valueChangedTo) {
-				const curChange = Object.assign({}, change);
-				const path = splitPath(childNodeChange._path);
-				const curNodePathVal = path.pop();
-				curChange.modification = childNodeChange._op;
-				const objId = await _getChildChangeObjId(change, childNodeChange, curNodePathVal, reqData, target);
-				_formatCompositionValue(curChange, objId, childNodeChange, childNodeChanges);
-			}
-			change.valueChangedTo = undefined;
-		}
-	}
-	changes.push(...childNodeChanges);
-};
-
-const _formatCompositionValue = function (curChange, objId, childNodeChange, childNodeChanges) {
-	if (curChange.modification === undefined) {
-		return;
-	} else if (curChange.modification === 'delete') {
-		curChange.valueChangedFrom = objId;
-		curChange.valueChangedTo = '';
-	} else if (curChange.modification === 'update') {
-		curChange.valueChangedFrom = objId;
-		curChange.valueChangedTo = objId;
-	} else {
-		curChange.valueChangedFrom = '';
-		curChange.valueChangedTo = objId;
-	}
-	curChange.valueDataType = _formatCompositionEntityType(curChange);
-	// Since req.diff() will record the managed data, change history will filter those logs only be changed managed data
-	const managedAttrs = ['modifiedAt', 'modifiedBy'];
-	if (curChange.modification === 'update') {
-		const rowOldAttrs = Object.keys(childNodeChange._old);
-		const diffAttrs = rowOldAttrs.filter((attr) => managedAttrs.indexOf(attr) === -1);
-		if (!diffAttrs.length) {
-			return;
-		}
-	}
-	childNodeChanges.push(curChange);
-};
-
-const _formatCompositionEntityType = function (change) {
-	const composition = cds.model.definitions[change.serviceEntity].elements[change.attribute];
-	const objIdElements = composition ? composition['@changelog'] : null;
-
-	if (Array.isArray(objIdElements)) {
-		// In this case, the attribute is a composition
-		const objIdElementNames = getObjIdElementNamesInArray(objIdElements);
-		return getValueEntityType(composition.target, objIdElementNames);
-	}
-	return '';
-};
-
-const _getObjectIdByPath = async function (reqData, nodePathVal, serviceEntityPath, target, /**optional*/ objIdElementNames) {
-	const curObjFromReqData = getCurObjFromReqData(reqData, nodePathVal, serviceEntityPath);
-	const entityName = getNameFromPathVal(nodePathVal);
-	const entityUUID = getUUIDFromPathVal(nodePathVal);
-	const obj = await getCurObjFromDbQuery(entityName, { [retrieveFirstKey(target)]: entityUUID });
-	const curObj = { curObjFromReqData, curObjFromDbQuery: obj };
-	return getObjectId(reqData, entityName, objIdElementNames, curObj);
-};
-
-const _formatObjectID = async function (changes, reqData, target) {
-	const objectIdCache = new Map();
-	for (const change of changes) {
-		const path = splitPath(change.serviceEntityPath);
-		const curNodePathVal = path.pop();
-		const parentNodePathVal = path.pop();
-
-		let curNodeObjId = objectIdCache.get(curNodePathVal);
-		if (!curNodeObjId) {
-			curNodeObjId = await _getObjectIdByPath(reqData, curNodePathVal, change.serviceEntityPath, target);
-			objectIdCache.set(curNodePathVal, curNodeObjId);
-		}
-
-		let parentNodeObjId = objectIdCache.get(parentNodePathVal);
-		if (!parentNodeObjId && parentNodePathVal) {
-			parentNodeObjId = await _getObjectIdByPath(reqData, parentNodePathVal, change.serviceEntityPath, target);
-			objectIdCache.set(parentNodePathVal, parentNodeObjId);
-		}
-
-		change.entityID = curNodeObjId;
-		change.parentEntityID = parentNodeObjId;
-		change.parentKey = getUUIDFromPathVal(parentNodePathVal);
-	}
-};
-
-const _isCompositionContextPath = function (aPath, hasComp) {
-	if (!aPath) return;
-	if (typeof aPath === 'string') aPath = aPath.split('/');
-	if (aPath.length < 2) return false;
-	const target = getEntityByContextPath(aPath, hasComp);
-	const parent = getEntityByContextPath(aPath.slice(0, -1), hasComp);
-	if (!parent.compositions) return false;
-	return Object.values(parent.compositions).some((c) => c._target === target);
-};
-
-const _formatChangeLog = async function (changes, req) {
-	await _formatObjectID(changes, req.data, req.target);
-	await _formatAssociationContext(changes, req.data);
-	await _formatCompositionContext(changes, req.data, req.target);
-};
-
-const _afterReadChangeView = function (data, req) {
-	if (!data) return;
-	if (!Array.isArray(data)) data = [data];
-	localizeLogFields(data, req.locale);
-};
-
-function _trackedChanges4(srv, target, diff) {
-	const template = getTemplate('change-logging', srv, target, { pick: (e) => e['@changelog'] });
-	if (!template.elements.size) return;
-
-	const changes = [];
-	diff._path = `${target.name}(${diff[retrieveFirstKey(target)]})`;
-
-	templateProcessor({
-		template,
-		row: diff,
-		processFn: ({ row, key, element }) => {
-			const from = row._old?.[key];
-			const to = row[key];
-			const eleParentKeys = element.parent.keys;
-			if (from === to) return;
-
-			/**
-			 *
-			 * HANA driver always filling up the defined decimal places with zeros,
-			 * need to skip the change log if the value is not changed.
-			 * Example:
-			 * entity Books : cuid {
-			 *   price     : Decimal(11, 4);
-			 * }
-			 * When price is updated from 3000.0000 to 3000,
-			 * the change log should not be created.
-			 */
-			if (row._op === 'update' && element.type === 'cds.Decimal' && cds.db.kind === 'hana' && typeof to === 'number') {
-				const scaleNum = element.scale || 0;
-				if (from === formatDecimal(to, scaleNum)) return;
-			}
-
-			/**
-			 *
-			 * For the Inline entity such as Items,
-			 * further filtering is required on the keys
-			 * within the 'association' and 'foreign key' to ultimately retain the keys of the entity itself.
-			 * entity Order : cuid {
-			 *   title      : String;
-			 *   Items      : Composition of many {
-			 *     key ID   : UUID;
-			 *     quantity : Integer;
-			 *   }
-			 * }
-			 */
-			const keys = Object.keys(eleParentKeys)
-				.filter((k) => k !== 'IsActiveEntity')
-				.filter((k) => eleParentKeys[k]?.type !== 'cds.Association') // Skip association
-				.filter((k) => !eleParentKeys[k]?.['@odata.foreignKey4']) // Skip foreign key
-				.map((k) => `${k}=${row[k]}`)
-				.join(', ');
-
-			changes.push({
-				serviceEntityPath: row._path,
-				entity: getDBEntity(element.parent).name,
-				serviceEntity: element.parent.name,
-				attribute: element['@odata.foreignKey4'] || key,
-				valueChangedFrom: from ?? '',
-				valueChangedTo: to ?? '',
-				valueDataType: element.type,
-				modification: row._op,
-				keys
-			});
-		}
-	});
-
-	return changes.length && changes;
-}
-
-const _prepareChangeLogForComposition = async function (entity, entityKey, changes, req) {
-	const rootEntityPathVals = _getRootEntityPathVals(req.context, entity, entityKey);
-
-	if (rootEntityPathVals.length < 2) {
-		LOG.info("Parent entity doesn't exist.");
-		return;
-	}
-
-	const parentEntityPathVal = rootEntityPathVals[rootEntityPathVals.length - 2];
-	const parentKey = getUUIDFromPathVal(parentEntityPathVal);
-	const serviceEntityPath = rootEntityPathVals.join('/');
-	const parentServiceEntityPath = _getAllPathVals(req.context)
-		.slice(0, rootEntityPathVals.length - 2)
-		.join('/');
-
-	for (const change of changes) {
-		change.parentEntityID = await _getObjectIdByPath(req.data, parentEntityPathVal, parentServiceEntityPath, entity);
-		change.parentKey = parentKey;
-		change.serviceEntityPath = serviceEntityPath;
-	}
-
-	const rootEntity = getNameFromPathVal(rootEntityPathVals[0]);
-	const rootEntityID = getUUIDFromPathVal(rootEntityPathVals[0]);
-	return [rootEntity, rootEntityID];
-};
-
-async function generatePathAndParams(req, entityKey) {
-	const { target, data } = req;
-	const { ID, foreignKey, parentEntity } = getAssociationDetails(target);
-	const hasParentAndForeignKey = parentEntity && data[foreignKey];
-	const targetEntity = hasParentAndForeignKey ? parentEntity : target;
-	const targetKey = hasParentAndForeignKey ? data[foreignKey] : entityKey;
-
-	let compContext = {
-		path: hasParentAndForeignKey ? `${parentEntity.name}/${target.name}` : `${target.name}`,
-		params: hasParentAndForeignKey ? [{ [ID]: data[foreignKey] }, { [ID]: entityKey }] : [{ [ID]: entityKey }],
-		hasComp: true
-	};
-
-	if (hasParentAndForeignKey && isRootEntity(parentEntity)) {
-		return compContext;
-	}
-
-	let parentAssoc = await processEntity(targetEntity, targetKey, compContext);
-	while (parentAssoc && !isRootEntity(parentAssoc.entity)) {
-		parentAssoc = await processEntity(parentAssoc.entity, parentAssoc.ID, compContext);
-	}
-	return compContext;
-}
-
-async function processEntity(entity, entityKey, compContext) {
-	if (!entity || !entityKey || !compContext) return;
-
-	const { ID, foreignKey, parentEntity } = getAssociationDetails(entity);
-
-	if (!foreignKey || !parentEntity) return;
-
-	const parentResult = await SELECT.one
-		.from(entity.name)
-		.where({ [ID]: entityKey })
-		.columns(foreignKey);
-
-	if (!parentResult || typeof parentResult !== 'object') return;
-
-	const hasForeignKey = parentResult[foreignKey];
-	if (!hasForeignKey) return;
-
-	compContext.path = `${parentEntity.name}/${compContext.path}`;
-	compContext.params.unshift({ [ID]: hasForeignKey });
-
-	return {
-		entity: parentEntity,
-		[ID]: hasForeignKey
-	};
-}
-
-function getAssociationDetails(entity) {
-	if (!entity || typeof entity !== 'object') return {};
-
-	const { name } = entity;
-	if (!name || typeof name !== 'string') return {};
-
-	const definition = cds.model.definitions[name];
-	if (!definition) return {};
-
-	const assocName = entity[hasParent]?.associationName ?? definition[hasParent]?.associationName;
-	if (!assocName) return {};
-
-	const elements = entity.elements || {};
-	const assoc = elements[assocName];
-	if (!assoc) return {};
-
-	const parentEntity = assoc._target;
-	const foreignKey = assoc.keys?.[0]?.$generatedFieldName;
-	const ID = assoc.keys?.[0]?.ref?.[0] ?? 'ID';
-
-	return { ID, foreignKey, parentEntity };
-}
-
-function isRootEntity(entity) {
-	return entity[isRoot] || cds.model.definitions[entity.name]?.[isRoot] || false;
-}
-
-function isEmpty(value) {
-	return value === null || value === undefined || value === '';
-}
-
-async function track_changes(req) {
-	const config = cds.env.requires['change-tracking'];
-
-	if ((req.event === 'UPDATE' && config?.disableUpdateTracking) || (req.event === 'CREATE' && config?.disableCreateTracking) || (req.event === 'DELETE' && config?.disableDeleteTracking)) {
-		return;
-	}
-
-	let diff = await req.diff();
-	if (!diff) return;
-
-	const diffs = Array.isArray(diff) ? diff : [diff];
-	const changes = (await Promise.all(diffs.map((item) => trackChangesForDiff(item, req, this)))).filter(Boolean);
-
-	if (changes.length > 0) {
-		await INSERT.into('sap.changelog.ChangeLog').entries(changes);
-	}
-}
-
-async function trackChangesForDiff(diff, req, that) {
-	let target = req.target;
-	let compContext = null;
-	let entityKey = diff[retrieveFirstKey(target)];
-	let isTopLevel = isRootEntity(target);
-	const params = convertSubjectToParams(req.subject);
-	if (req.subject.ref.length === 1 && params.length === 1 && !isTopLevel) {
-		compContext = await generatePathAndParams(req, entityKey);
-	}
-	let isComposition = _isCompositionContextPath(compContext?.path || req.path, compContext?.hasComp);
-	if (req.event === 'DELETE' && isTopLevel && !cds.env.requires['change-tracking']?.preserveDeletes) {
-		await DELETE.from(`sap.changelog.ChangeLog`).where({ entityKey });
-		return;
-	}
-
-	let changes = _trackedChanges4(that, target, diff);
-	if (!changes) return;
-
-	await _formatChangeLog(changes, req);
-	if (isComposition) {
-		let reqInfo = {
-			data: req.data,
-			context: {
-				path: compContext?.path || req.path,
-				params: compContext?.params || params,
-				event: req.event,
-				hasComp: compContext?.hasComp
-			}
-		};
-		[target, entityKey] = await _prepareChangeLogForComposition(target, entityKey, changes, reqInfo);
-	}
-	const dbEntity = getDBEntity(target);
-	return {
-		entity: dbEntity.name,
-		entityKey: entityKey,
-		serviceEntity: target.name || target,
-		changes: changes
-			.filter((c) => !isEmpty(c.valueChangedFrom) || !isEmpty(c.valueChangedTo))
-			.map((c) => ({
-				...c,
-				valueChangedFrom: `${c.valueChangedFrom ?? ''}`,
-				valueChangedTo: `${c.valueChangedTo ?? ''}`
-			}))
-	};
-}
-
-module.exports = { track_changes, _afterReadChangeView };