@cap-js/change-tracking 1.1.3 → 2.0.0-beta.1

package/lib/model-enhancer.js

@@ -0,0 +1,266 @@
+const cds = require('@sap/cds');
+const LOG = cds.log('change-tracking');
+const DEBUG = cds.debug('change-tracking');
+
+const { isChangeTracked, getBaseEntity, analyzeCompositions, getService } = require('./utils/entity-collector.js');
+
+/**
+ * Add side effects annotations for actions to refresh the changes association.
+ */
+function addSideEffects(actions, entityName, hierarchyMap, model) {
+	const isRootEntity = !hierarchyMap.has(entityName);
+
+	// If not a root entity, find the parent association name
+	let parentAssociationName = null;
+	if (!isRootEntity) {
+		const parentEntityName = hierarchyMap.get(entityName);
+		const parentEntity = model.definitions[parentEntityName];
+		if (parentEntity?.elements) {
+			// Find the composition element in the parent that points to this entity
+			for (const [elemName, elem] of Object.entries(parentEntity.elements)) {
+				if (elem.type === 'cds.Composition' && elem.target === entityName) {
+					parentAssociationName = elemName;
+					break;
+				}
+			}
+		}
+	}
+
+	for (const se of Object.values(actions)) {
+		const target = isRootEntity ? 'TargetProperties' : 'TargetEntities';
+		const sideEffectAttr = se[`@Common.SideEffects.${target}`];
+		const property = isRootEntity ? 'changes' : { '=': `${parentAssociationName}.changes` };
+		if (sideEffectAttr?.length >= 0) {
+			sideEffectAttr.findIndex((item) => (item['='] ? item['='] : item) === (property['='] ? property['='] : property)) === -1 && sideEffectAttr.push(property);
+		} else {
+			se[`@Common.SideEffects.${target}`] = [property];
+		}
+	}
+}
+
+/**
+ * Returns a CQN expression for the composite key of an entity.
+ * Used for the ON condition when associating changes.
+ */
+function entityKey4(entity) {
+	const keys = [];
+	for (const k in entity.elements) {
+		const e = entity.elements[k];
+		if (!e.key) continue;
+		if (e.type === 'cds.Association') {
+			keys.push({ ref: [k, e.keys?.[0]?.ref?.[0]] });
+		} else {
+			keys.push({ ref: [k] });
+		}
+	}
+	if (keys.length <= 1) return keys;
+
+	const xpr = [];
+	for (let i = 0; i < keys.length; i++) {
+		if (i > 0) {
+			xpr.push('||');
+			xpr.push({ val: ';' });
+			xpr.push('||');
+		}
+		const keyAsStr = { ...keys[i], cast: { type: 'cds.String' } };
+		xpr.push({ func: 'LENGTH', args: [keyAsStr] });
+		xpr.push('||');
+		xpr.push({ val: ',' });
+		xpr.push('||');
+		xpr.push(keyAsStr);
+	}
+	return xpr;
+}
+
+/**
+ * Replace ENTITY placeholders in ON conditions.
+ */
+function _replaceTablePlaceholders(on, tableName) {
+	return on.map((part) => {
+		if (part?.val === 'ENTITY') return { ...part, val: tableName };
+		return part;
+	});
+}
+
+/**
+ * Check if a facet already exists for the changes composition.
+ */
+function hasFacetForComp(comp, facets) {
+	return facets.some((f) => f.Target === `${comp.name}/@UI.LineItem` || (f.Facets && hasFacetForComp(comp, f.Facets)));
+}
+
+/**
+ * Enhance the CDS model with change tracking associations, facets, and side effects.
+ * Returns the updated hierarchyMap and collectedEntities for use by trigger generation.
+ */
+function enhanceModel(m) {
+	if (m.meta?.flavor !== 'inferred') {
+		// In MTX scenarios with extensibility the runtime model for deployed apps is not
+		// inferred but xtended and the logic requires inferred.
+		DEBUG?.(`Skipping model enhancement because model flavour is '${m.meta?.flavor}' and not 'inferred'`);
+		return;
+	}
+	const _enhanced = 'sap.changelog.enhanced';
+	if (m.meta?.[_enhanced]) return; // already enhanced
+
+	// Get definitions from Dummy entity in our models
+	const { 'sap.changelog.aspect': aspect } = m.definitions;
+	if (!aspect) return; // some other model
+	const {
+		'@UI.Facets': [facet],
+		elements: { changes }
+	} = aspect;
+
+	const hierarchyMap = analyzeCompositions(m);
+	const collectedEntities = new Map();
+
+	const replaceReferences = (xpr, depth) => {
+		const parents = [];
+		for (let i = 0; i < depth; i++) parents.push('parent');
+		for (const ele of xpr) {
+			if (ele.ref && ele.ref[0] === 'changes') {
+				const lastEle = ele.ref.pop();
+				ele.ref.push(parents.join('_') + '_' + lastEle);
+			}
+		}
+		return xpr;
+	};
+	if (cds.env.requires['change-tracking'].maxDisplayHierarchyDepth > 1) {
+		const depth = cds.env.requires['change-tracking'].maxDisplayHierarchyDepth;
+		const parents = [];
+		for (let i = 1; i < depth; i++) {
+			parents.push('parent');
+			m.definitions['sap.changelog.ChangeView'].query.SELECT.columns.push(
+				{
+					ref: ['change', ...parents, 'entityKey'],
+					as: parents.join('_') + '_' + 'entityKey'
+				},
+				{
+					ref: ['change', ...parents, 'entity'],
+					as: parents.join('_') + '_' + 'entity'
+				}
+			);
+			m.definitions['sap.changelog.ChangeView'].elements[parents.join('_') + '_' + 'entityKey'] = structuredClone(m.definitions['sap.changelog.ChangeView'].elements.entityKey);
+			m.definitions['sap.changelog.ChangeView'].elements[parents.join('_') + '_' + 'entity'] = structuredClone(m.definitions['sap.changelog.ChangeView'].elements.entity);
+		}
+	}
+	for (let name in m.definitions) {
+		const entity = m.definitions[name];
+		const isServiceEntity = entity.kind === 'entity' && !!(entity.query || entity.projection);
+		const serviceName = getService(name, m);
+		if (isServiceEntity && isChangeTracked(entity) && serviceName) {
+			// Collect change-tracked service entity name with its underlying DB entity name
+			const baseInfo = getBaseEntity(entity, m);
+			if (!baseInfo) continue;
+			const { baseRef: dbEntityName } = baseInfo;
+
+			if (!collectedEntities.has(dbEntityName)) collectedEntities.set(dbEntityName, []);
+			collectedEntities.get(dbEntityName).push(name);
+
+			// Skip adding association to ChangeView if the entity has only association keys, as it cannot be independently identified and is likely an inline composition target
+			const entityKeys = Object.values(entity.elements).filter((e) => e.key);
+			const hasOnlyAssociationKeys = entityKeys.length > 0 && entityKeys.every((e) => e.type === 'cds.Association');
+			if (hasOnlyAssociationKeys) {
+				DEBUG?.(`Skipping changes association for ${name} - inline composition target with no independent key`);
+			} else if (!entity['@changelog.disable_assoc']) {
+				// Add association to ChangeView
+				const keys = entityKey4(entity);
+				if (!keys.length) continue; // skip if no key attribute is defined
+
+				const onCondition = changes.on.flatMap((p) => (p?.ref && p.ref[0] === 'ID' ? keys : [p]));
+				const tableName = (entity.projection ?? entity.query?.SELECT)?.from?.ref[0];
+				const onTemplate = _replaceTablePlaceholders(onCondition, tableName);
+				const on = cds.env.requires['change-tracking'].maxDisplayHierarchyDepth > 1 ? [{ xpr: structuredClone(onTemplate) }] : onTemplate;
+				for (let i = 1; i < cds.env.requires['change-tracking'].maxDisplayHierarchyDepth; i++) {
+					on.push('or', { xpr: replaceReferences(structuredClone(onTemplate), i) });
+				}
+				const assoc = new cds.builtin.classes.Association({ ...changes, on });
+				assoc.target = `${serviceName}.ChangeView`;
+				if (!m.definitions[`${serviceName}.ChangeView`]) {
+					m.definitions[`${serviceName}.ChangeView`] = structuredClone(m.definitions['sap.changelog.ChangeView']);
+					m.definitions[`${serviceName}.ChangeView`].query = {
+						SELECT: {
+							from: {
+								ref: ['sap.changelog.ChangeView']
+							},
+							columns: ['*']
+						}
+					};
+
+					for (const ele in m.definitions[`${serviceName}.ChangeView`].elements) {
+						if (m.definitions[`${serviceName}.ChangeView`].elements[ele]?.target && !m.definitions[`${serviceName}.ChangeView`].elements[ele]?.target.startsWith(serviceName)) {
+							const target = m.definitions[`${serviceName}.ChangeView`].elements[ele]?.target;
+							const serviceEntity = Object.keys(m.definitions)
+								.filter((e) => e.startsWith(serviceName))
+								.find((e) => {
+									let baseE = e;
+									while (baseE) {
+										if (baseE === target) {
+											return true;
+										}
+										const artefact = m.definitions[baseE];
+										const cqn = artefact.projection ?? artefact.query?.SELECT;
+										if (!cqn) {
+											return false;
+										}
+										// from.args is the case for joins
+										baseE = cqn.from?.ref?.[0] ?? cqn.from?.args?.[0]?.ref?.[0];
+									}
+									return false;
+								});
+							if (serviceEntity) {
+								m.definitions[`${serviceName}.ChangeView`].elements[ele].target = serviceEntity;
+							}
+						}
+					}
+				}
+
+				DEBUG?.(
+					`\n
+          extend ${name} with {
+            changes : Association to many ${assoc.target} on ${assoc.on.map((x) => x.ref?.join('.') || x.val || x).join(' ')};
+          }
+        `.replace(/ {8}/g, '')
+				);
+
+				const query = entity.projection || entity.query?.SELECT;
+				if (query) {
+					(query.columns ??= ['*']).push({ as: 'changes', cast: assoc });
+					entity.elements.changes = assoc;
+				}
+
+				if (entity['@changelog.disable_facet'] !== undefined) {
+					LOG.warn(
+						`@changelog.disable_facet is deprecated! You can just define your own Facet for the changes association or annotate the changes association on ${entity.name} with not readable via @Capabilities.NavigationRestrictions.RestrictedProperties`
+					);
+				}
+
+				let facets = entity['@UI.Facets'];
+
+				if (!facets) {
+					DEBUG?.(`${entity.name} does not have a @UI.Facets annotation and thus the change tracking section is not added.`);
+				}
+				// Add UI.Facet for Change History List
+				if (
+					facets &&
+					!entity['@changelog.disable_facet'] &&
+					!hasFacetForComp(changes, entity['@UI.Facets']) &&
+					!entity['@Capabilities.NavigationRestrictions.RestrictedProperties']?.some((restriction) => restriction.NavigationProperty?.['='] === 'changes' && restriction.ReadRestrictions?.Readable === false)
+				) {
+					facets.push(facet);
+				}
+			}
+
+			if (entity.actions) {
+				const baseInfo = getBaseEntity(entity, m);
+				if (baseInfo) {
+					const { baseRef: dbEntityName } = baseInfo;
+					addSideEffects(entity.actions, dbEntityName, hierarchyMap, m);
+				}
+			}
+		}
+	}
+	(m.meta ??= {})[_enhanced] = true;
+}
+
+module.exports = { enhanceModel };

package/lib/postgres/composition.js

@@ -0,0 +1,191 @@
+const utils = require('../utils/change-tracking.js');
+const { getModel, toSQL, compositeKeyExpr } = require('./sql-expressions.js');
+
+/**
+ * Builds rootObjectID select for composition of many
+ */
+function buildCompOfManyRootObjectIDSelect(rootEntity, rootObjectIDs, binding, refRow) {
+	if (!rootObjectIDs || rootObjectIDs.length === 0) return `'${rootEntity.name}'`;
+
+	const rootKeys = utils.extractKeys(rootEntity.keys);
+	if (rootKeys.length !== binding.length) return `'${rootEntity.name}'`;
+
+	const where = {};
+	for (let i = 0; i < rootKeys.length; i++) {
+		where[rootKeys[i]] = { val: `${refRow}.${binding[i]}` };
+	}
+
+	const parts = [];
+	for (const oid of rootObjectIDs) {
+		const query = SELECT.one.from(rootEntity.name).columns(oid.name).where(where);
+		parts.push(`COALESCE((${toSQL(query)})::TEXT, '')`);
+	}
+
+	const concatLogic = `CONCAT_WS(', ', ${parts.join(', ')})`;
+	const rootEntityKeyExpr = compositeKeyExpr(binding.map((k) => `${refRow}.${k}`));
+
+	return `COALESCE(NULLIF(${concatLogic}, ''), ${rootEntityKeyExpr})`;
+}
+
+function buildCompositionOfOneParentBlock(compositionParentInfo, rootObjectIDs) {
+	const model = getModel();
+	const { parentEntityName, compositionFieldName, parentKeyBinding } = compositionParentInfo;
+	const { compositionName, childKeys } = parentKeyBinding;
+
+	const parentFKFields = childKeys.map((k) => `${compositionName}_${k}`);
+	const parentEntity = model.definitions[parentEntityName];
+	const parentKeys = utils.extractKeys(parentEntity.keys);
+	const parentWhereClause = parentFKFields.map((fk, i) => `${fk} = rec.${childKeys[i]}`).join(' AND ');
+
+	// Build the parent key expression via subquery (reverse lookup)
+	const parentKeyExpr = compositeKeyExpr(parentKeys.map((pk) => `(SELECT ${pk} FROM ${utils.transformName(parentEntityName)} WHERE ${parentWhereClause})`));
+
+	// Build rootObjectID expression for the parent entity
+	let rootObjectIDExpr;
+	if (rootObjectIDs?.length > 0) {
+		const oidSelects = rootObjectIDs.map((oid) => `(SELECT ${oid.name}::TEXT FROM ${utils.transformName(parentEntityName)} WHERE ${parentWhereClause})`);
+		rootObjectIDExpr = oidSelects.length > 1 ? `CONCAT_WS(', ', ${oidSelects.join(', ')})` : oidSelects[0];
+	} else {
+		rootObjectIDExpr = parentKeyExpr;
+	}
+
+	// Build the composition parent block with dynamic modification determination
+	return `SELECT CASE WHEN COUNT(*) > 0 THEN 'create' ELSE 'update' END INTO comp_parent_modification
+                FROM sap_changelog_changes
+                WHERE entity = '${parentEntityName}'
+                AND entitykey = ${parentKeyExpr}
+                AND modification = 'create'
+                AND transactionid = transaction_id;
+            
+            IF EXISTS (SELECT 1 FROM ${utils.transformName(parentEntityName)} WHERE ${parentWhereClause}) THEN
+                SELECT id INTO comp_parent_id FROM sap_changelog_changes WHERE entity = '${parentEntityName}'
+                    AND entitykey = ${parentKeyExpr}
+                    AND attribute = '${compositionFieldName}'
+                    AND valuedatatype = 'cds.Composition'
+                    AND transactionid = transaction_id;
+                IF comp_parent_id IS NULL THEN
+                    comp_parent_id := gen_random_uuid();
+                    INSERT INTO sap_changelog_changes
+                        (ID, PARENT_ID, ATTRIBUTE, ENTITY, ENTITYKEY, OBJECTID, CREATEDAT, CREATEDBY, VALUEDATATYPE, MODIFICATION, TRANSACTIONID)
+                        VALUES (
+                            comp_parent_id,
+                            NULL,
+                            '${compositionFieldName}',
+                            '${parentEntityName}',
+                            ${parentKeyExpr},
+                            ${rootObjectIDExpr},
+                            now(),
+                            user_id,
+                            'cds.Composition',
+                            comp_parent_modification,
+                            transaction_id
+                        );
+                END IF;
+            END IF;`;
+}
+
+function buildCompositionParentBlock(compositionParentInfo, rootObjectIDs, modification, grandParentCompositionInfo = null) {
+	const model = getModel();
+	const { parentEntityName, compositionFieldName, parentKeyBinding } = compositionParentInfo;
+
+	// Handle composition of one (parent has FK to child - need reverse lookup)
+	if (parentKeyBinding.type === 'compositionOfOne') {
+		return buildCompositionOfOneParentBlock(compositionParentInfo, rootObjectIDs);
+	}
+
+	const parentKeyExpr = compositeKeyExpr(parentKeyBinding.map((k) => `rec.${k}`));
+
+	// Build rootObjectID expression for the parent entity
+	const rootEntity = model.definitions[parentEntityName];
+	const rootObjectIDExpr = buildCompOfManyRootObjectIDSelect(rootEntity, rootObjectIDs, parentKeyBinding, 'rec');
+
+	let grandparentBlock = '';
+	let grandparentLookupExpr = 'NULL';
+
+	if (grandParentCompositionInfo) {
+		// When we have grandparent info, we need to:
+		// 1. Create grandparent entry (Order.orderItems) for current transaction if not exists
+		// 2. Create parent entry (OrderItem.notes) linking to the grandparent entry
+		const { grandParentEntityName, grandParentCompositionFieldName, grandParentKeyBinding } = grandParentCompositionInfo;
+
+		// Build WHERE clause to find the parent entity record
+		const parentEntity = model.definitions[parentEntityName];
+		const parentKeys = utils.extractKeys(parentEntity.keys);
+		const parentWhere = parentKeys.map((pk, i) => `${pk} = rec.${parentKeyBinding[i]}`).join(' AND ');
+
+		// Build the grandparent key expression from the parent record
+		const grandParentKeyExpr = compositeKeyExpr(grandParentKeyBinding.map((k) => `(SELECT ${k} FROM ${utils.transformName(parentEntityName)} WHERE ${parentWhere})`));
+
+		// Create grandparent entry if not exists in this transaction
+		grandparentBlock = `-- First ensure grandparent entry exists for this transaction
+            SELECT id INTO comp_grandparent_id FROM sap_changelog_changes WHERE entity = '${grandParentEntityName}'
+                AND entitykey = ${grandParentKeyExpr}
+                AND attribute = '${grandParentCompositionFieldName}'
+                AND valuedatatype = 'cds.Composition'
+                AND transactionid = transaction_id;
+            IF comp_grandparent_id IS NULL THEN
+                comp_grandparent_id := gen_random_uuid();
+                INSERT INTO sap_changelog_changes
+                    (ID, PARENT_ID, ATTRIBUTE, ENTITY, ENTITYKEY, OBJECTID, CREATEDAT, CREATEDBY, VALUEDATATYPE, MODIFICATION, TRANSACTIONID)
+                    VALUES (
+                        comp_grandparent_id,
+                        NULL,
+                        '${grandParentCompositionFieldName}',
+                        '${grandParentEntityName}',
+                        ${grandParentKeyExpr},
+                        ${grandParentKeyExpr},
+                        now(),
+                        user_id,
+                        'cds.Composition',
+                        'update',
+                        transaction_id
+                    );
+            END IF;`;
+
+		grandparentLookupExpr = 'comp_grandparent_id';
+	}
+
+	// Determine modification dynamically: 'create' if parent was just created, 'update' otherwise
+	// This handles both deep insert (parent created in same tx) and independent insert (parent already existed)
+	const modificationExpr = grandParentCompositionInfo
+		? `'${modification}'` // When grandparent exists, use provided modification
+		: `CASE WHEN EXISTS (
+                    SELECT 1 FROM sap_changelog_changes
+                    WHERE entity = '${parentEntityName}'
+                    AND entitykey = ${parentKeyExpr}
+                    AND modification = 'create'
+                    AND transactionid = transaction_id
+                ) THEN 'create' ELSE 'update' END`;
+
+	// PL/pgSQL block that checks for existing parent entry and creates one if needed
+	return `${grandparentBlock}
+            SELECT id INTO comp_parent_id FROM sap_changelog_changes WHERE entity = '${parentEntityName}'
+                AND entitykey = ${parentKeyExpr}
+                AND attribute = '${compositionFieldName}'
+                AND valuedatatype = 'cds.Composition'
+                AND transactionid = transaction_id;
+            IF comp_parent_id IS NULL THEN
+                comp_parent_id := gen_random_uuid();
+                INSERT INTO sap_changelog_changes
+                    (ID, PARENT_ID, ATTRIBUTE, ENTITY, ENTITYKEY, OBJECTID, CREATEDAT, CREATEDBY, VALUEDATATYPE, MODIFICATION, TRANSACTIONID)
+                    VALUES (
+                        comp_parent_id,
+                        ${grandparentLookupExpr},
+                        '${compositionFieldName}',
+                        '${parentEntityName}',
+                        ${parentKeyExpr},
+                        ${rootObjectIDExpr},
+                        now(),
+                        user_id,
+                        'cds.Composition',
+                        ${modificationExpr},
+                        transaction_id
+                    );
+            END IF;`;
+}
+
+module.exports = {
+	buildCompOfManyRootObjectIDSelect,
+	buildCompositionOfOneParentBlock,
+	buildCompositionParentBlock
+};

package/lib/postgres/register.js

@@ -0,0 +1,44 @@
+const cds = require('@sap/cds');
+
+const { getEntitiesForTriggerGeneration, collectEntities } = require('../utils/entity-collector.js');
+const { getLabelTranslations } = require('../localization.js');
+const { prepareCSNForTriggers, generateTriggersForEntities } = require('../utils/trigger-utils.js');
+
+function registerPostgresCompilerHook() {
+	cds.on('compile.to.dbx', (csn, options, next) => {
+		const ddl = next();
+		if (options?.dialect !== 'postgres') return ddl;
+
+		const { generatePostgresTriggers } = require('./triggers.js');
+		const { runtimeCSN, hierarchy, entities } = prepareCSNForTriggers(csn);
+
+		const triggers = generateTriggersForEntities(runtimeCSN, hierarchy, entities, generatePostgresTriggers);
+
+		if (triggers.length === 0) return ddl;
+
+		// Handle standard compilation (array) or delta compilation (object with createsAndAlters/drops)
+		if (Array.isArray(ddl)) {
+			return [...ddl, ...triggers];
+		} else if (ddl.createsAndAlters) {
+			ddl.createsAndAlters.push(...triggers);
+			return ddl;
+		}
+
+		return ddl;
+	});
+}
+
+async function deployPostgresLabels() {
+	const db = cds.env.requires?.db;
+	if (db?.kind !== 'postgres') return;
+
+	const model = cds.context?.model ?? cds.model;
+	const { collectedEntities } = collectEntities(model);
+	const entities = getEntitiesForTriggerGeneration(model.definitions, collectedEntities);
+	const labels = getLabelTranslations(entities, model);
+	const { i18nKeys } = cds.entities('sap.changelog');
+
+	await Promise.all([cds.delete(i18nKeys), cds.insert(labels).into(i18nKeys)]);
+}
+
+module.exports = { registerPostgresCompilerHook, deployPostgresLabels };