@cap-js/change-tracking 2.0.0-beta.4 → 2.0.0-beta.5

package/CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
-## Version 2.0.0-beta.5 - tbd
+## Version 2.0.0-beta.6 - tbd
 
 ### Added
 
@@ -12,6 +12,15 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
 ### Changed
 
+## Version 2.0.0-beta.5 - 17.03.26
+
+### Added
+- Support dynamic localized label lookup, meaning if for example a property is change tracked and its change tracking label (@changelog : [<association>.<localized_prop>]) points to one localized property from its code list entity, the label is dynamically fetched when the change is read based on the users locale.
+
+### Fixed
+- Postgres considers `disable*Tracking` for children changes
+- Human-readable `@changelog` annotation supports combination of direct entity elements and association elements
+
 ## Version 2.0.0-beta.4 - 16.03.26
 
 ### Added

package/README.md

@@ -177,12 +177,44 @@ customer @changelog: [customer.name];
 
 <img width="1300" alt="change-history-value-hr" src="_assets/changes-value-hr-wbox.png">
 
+#### Localized values
+If a human-readable value is annotated for the changelog, it will be localized.
+
+```cds
+extend Incidents with elements {
+  status: Association to one Status @changelog: [status.descr];
+}
+
+entity Status {
+  key code: String(1);
+      descr: localized String(20);
+}
+```
+
+By default the value label stored for the change is localized in the language of the user who caused the change. Meaning if a German speaking user changes the status, the human-readable value would be by default in German.
+
+In cases, like above, where the human-readable value only consists of one field, targets a localized property and goes along the (un-)managed association, a dynamic human-readable value is used, meaning if an English-speaking user looks at the changes, the value label will be shown in English, for a French-speaking user in French and so on.
+
 ### Tracing any kind of change
 
 Change tracking is implemented with Database triggers and supports HANA Cloud, SQLite, Postgres and H2.
 
 Leveraging database triggers means any change will be tracked no matter how it is represented in the service. Thus tracking changes made via unions, or via views with joins will still work.
 
+#### Tracking datetime fields with a fixed time zone
+
+The plugin supports tracking datetime field changes when the field has a time zone annotated.
+
+```cds
+extend Incidents with elements {
+  closedAt : DateTime @changelog @Common.Timezone : 'Europe/Berlin';
+  openedAt : DateTime @changelog @Common.Timezone : openedTimeZone;
+  openedTimeZone : String @Common.IsTimezone;
+}
+```
+
+In both cases the plugin will show the annotated time zone for change values in changes for the two fields. In the second case the time zone is dynamically fetched and modifications to the time zone field will also reflect in the change records for that field.
+
 ## Advanced Options
 
 ### Altered table view

package/lib/csn-enhancements/dynamicLocalization.js

@@ -0,0 +1,106 @@
+const cds = require('@sap/cds');
+const { isChangeTracked, getBaseEntity, getBaseElement } = require('../utils/entity-collector');
+const DEBUG = cds.debug('change-tracking');
+
+/**
+ * Dynamic localization, primarily for code list scenarios, where a status field is change tracked but its localized label should be shown.
+ * @param {*} serviceName
+ * @param {*} m
+ */
+function collectTrackedPropertiesWithDynamicLocalization(serviceName, m) {
+	const dynamicLocalizationProperties = [];
+	for (const name in m.definitions) {
+		if (!name.startsWith(serviceName) || m.definitions[name].kind !== 'entity' || !isChangeTracked(m.definitions[name])) {
+			continue;
+		}
+		const entity = m.definitions[name];
+		const base = getBaseEntity(entity, m);
+		if (!base) continue;
+		for (const ele in entity.elements) {
+			const element = entity.elements[ele];
+			if (!Array.isArray(element['@changelog']) || element['@changelog'].length !== 1 || !element['@changelog'][0]?.['='] || element._foreignKey4) {
+				continue;
+			}
+			const segments = element['@changelog'][0]['='].split('.');
+			const baseEleInfo = getBaseElement(ele, entity, m);
+			const basePropertyName = baseEleInfo?.baseElement ?? ele;
+			// Managed association target or as fallback unmanaged association target
+			const target = element.target ?? m.definitions[base.baseRef ?? name].elements[segments[0]].target;
+			const basePropertyInUnmanagedOnCondition = m.definitions[base.baseRef ?? name].elements[segments[0]].on?.some((r) => r.ref && r.ref[0] === basePropertyName);
+			const isLocalizedField = m.definitions[target].elements?.[segments[1]]?.localized;
+			const amountOfKeys = Object.keys(m.definitions[target].elements).filter((e) => m.definitions[target].elements[e].key).length;
+			if (!target || (segments[0] !== basePropertyName && !basePropertyInUnmanagedOnCondition) || segments.length !== 2 || !isLocalizedField || amountOfKeys > 1) {
+				DEBUG &&
+					DEBUG(
+						`Dynamic localization lookup is not performed on ${ele} of ${name} for the path "${element['@changelog'][0]['=']}". Only paths which follow the properties association, which only navigate one level deep and where the last property is localized are supported.`
+					);
+				continue;
+			}
+
+			if (!dynamicLocalizationProperties.some((prop) => prop.property === basePropertyName && prop.entity === base.baseRef)) {
+				dynamicLocalizationProperties.push({
+					property: basePropertyName,
+					entity: base.baseRef,
+					dynamicLabel: SELECT.from(target + '.texts')
+						.alias('localizationSubSelect')
+						.where('1 = 1')
+						.columns(segments[1])
+				});
+			}
+			DEBUG && DEBUG(`${ele} of ${name} is change tracked and its logs are visualized using a dynamic localized label lookup targeting ${target + '.texts'} for the label ${segments[1]}.`);
+		}
+	}
+	return dynamicLocalizationProperties;
+}
+
+function enhanceChangeViewWithLocalization(serviceName, changeViewName, m) {
+	const changeView = m.definitions[changeViewName];
+	if (changeView['@changelog.internal.localizationEnhanced']) return;
+	DEBUG && DEBUG(`Enhance change view ${changeViewName} with dynamic localization setup.`);
+	const localizationProperties = collectTrackedPropertiesWithDynamicLocalization(serviceName, m);
+	if (!localizationProperties.length) return;
+	const changeViewCqn = changeView.projection ?? changeView.query.SELECT;
+	changeViewCqn.columns ??= ['*'];
+	changeViewCqn.from.as ??= 'change';
+	let valueChangedFromLabel = changeViewCqn.columns.find((c) => c.as && c.as === 'valueChangedFromLabel');
+	if (!valueChangedFromLabel) {
+		changeViewCqn.columns.push({
+			cast: { type: 'cds.String' },
+			xpr: [{ ref: ['valueChangedFromLabel'] }],
+			as: 'valueChangedFromLabel'
+		});
+		valueChangedFromLabel = changeViewCqn.columns.at(-1);
+	}
+	let valueChangedToLabel = changeViewCqn.columns.find((c) => c.as && c.as === 'valueChangedToLabel');
+	if (!valueChangedToLabel) {
+		changeViewCqn.columns.push({
+			cast: { type: 'cds.String' },
+			xpr: [{ ref: ['valueChangedToLabel'] }],
+			as: 'valueChangedToLabel'
+		});
+		valueChangedToLabel = changeViewCqn.columns.at(-1);
+	}
+	const originalValueChangedFrom = valueChangedFromLabel.xpr;
+	const originalValueChangedTo = valueChangedToLabel.xpr;
+	valueChangedFromLabel.xpr = ['case'];
+	valueChangedToLabel.xpr = ['case'];
+	for (const localizationProp of localizationProperties) {
+		valueChangedFromLabel.xpr.push('when', { ref: ['attribute'] }, '=', { val: localizationProp.property }, 'and', { ref: ['entity'] }, '=', { val: localizationProp.entity }, 'then');
+		const subSelect = structuredClone(localizationProp.dynamicLabel);
+		const keys = Object.keys(m.definitions[localizationProp.dynamicLabel.SELECT.from.ref[0]].elements).filter((e) => e !== 'locale' && m.definitions[localizationProp.dynamicLabel.SELECT.from.ref[0]].elements[e].key);
+		subSelect.SELECT.where = [{ ref: [changeViewCqn.from.as, 'valueChangedFrom'] }, '=', { ref: ['localizationSubSelect', keys[0]] }, 'and', { ref: ['localizationSubSelect', 'locale'] }, '=', { ref: ['$user', 'locale'] }];
+		valueChangedFromLabel.xpr.push({ func: 'COALESCE', args: [subSelect, { xpr: originalValueChangedFrom }] });
+
+		valueChangedToLabel.xpr.push('when', { ref: ['attribute'] }, '=', { val: localizationProp.property }, 'and', { ref: ['entity'] }, '=', { val: localizationProp.entity }, 'then');
+		const subSelect2 = structuredClone(localizationProp.dynamicLabel);
+		subSelect2.SELECT.where = [{ ref: [changeViewCqn.from.as, 'valueChangedTo'] }, '=', { ref: ['localizationSubSelect', keys[0]] }, 'and', { ref: ['localizationSubSelect', 'locale'] }, '=', { ref: ['$user', 'locale'] }];
+		valueChangedToLabel.xpr.push({ func: 'COALESCE', args: [subSelect2, { xpr: originalValueChangedTo }] });
+	}
+	valueChangedFromLabel.xpr.push('else', { xpr: originalValueChangedFrom }, 'end');
+	valueChangedToLabel.xpr.push('else', { xpr: originalValueChangedTo }, 'end');
+	changeView['@changelog.internal.localizationEnhanced'] = true;
+}
+
+module.exports = {
+	enhanceChangeViewWithLocalization
+};

package/lib/csn-enhancements/index.js

@@ -4,6 +4,7 @@ const DEBUG = cds.debug('change-tracking');
 const { isChangeTracked, getBaseEntity, analyzeCompositions, getService } = require('../utils/entity-collector.js');
 const { addSideEffects, addUIFacet } = require('./annotations.js');
 const { enhanceChangeViewWithTimeZones } = require('./timezoneProperties.js');
+const { enhanceChangeViewWithLocalization } = require('./dynamicLocalization.js');
 
 /**
  * Returns a CQN expression for the composite key of an entity.
@@ -173,6 +174,7 @@ function enhanceModel(m) {
 							}
 						}
 					}
+					enhanceChangeViewWithLocalization(serviceName, `${serviceName}.ChangeView`, m);
 				}
 
 				DEBUG?.(

package/lib/h2/java-codegen.js

@@ -18,7 +18,7 @@ function _toSQL(query, model) {
 	return cqn2sql.SELECT(sqlCQN);
 }
 
-function handleAssocLookup(column, refRow, model) {
+function handleAssocLookup(column, assocPaths, refRow, model) {
 	let bindings = [];
 	let where = {};
 
@@ -36,11 +36,11 @@ function handleAssocLookup(column, refRow, model) {
 		bindings = column.on.map((assoc) => `${refRow}.getString("${assoc}")`);
 	}
 
-	const alt = column.alt.map((s) => s.split('.').slice(1).join('.'));
+	const alt = assocPaths.map((s) => s.split('.').slice(1).join('.'));
 	const columns = alt.length === 1 ? alt[0] : utils.buildConcatXpr(alt);
 
 	// Check if target entity has localized data
-	const localizedInfo = utils.getLocalizedLookupInfo(column.target, column.alt, model);
+	const localizedInfo = utils.getLocalizedLookupInfo(column.target, assocPaths, model);
 
 	if (localizedInfo) {
 		// Build locale-aware lookup: try .texts table first, fall back to base entity
@@ -676,12 +676,40 @@ function _prepareValueExpression(col, rowVar) {
 
 // Returns label expression for a column
 function _prepareLabelExpression(col, rowVar, model) {
-	if (col.target && col.alt) {
-		const { sql, bindings } = handleAssocLookup(col, rowVar, model);
-		return { sqlExpr: sql, bindings: bindings };
+	if (!col.alt || col.alt.length === 0) {
+		return { sqlExpr: 'NULL', bindings: [] };
 	}
-	// No label for scalars or associations without @changelog override
-	return { sqlExpr: 'NULL', bindings: [] };
+
+	const sqlParts = [];
+	const allBindings = [];
+	let assocBatch = [];
+
+	const flushAssocBatch = () => {
+		if (assocBatch.length > 0) {
+			const { sql, bindings } = handleAssocLookup(col, assocBatch, rowVar, model);
+			sqlParts.push(sql);
+			allBindings.push(...bindings);
+			assocBatch = [];
+		}
+	};
+
+	for (const entry of col.alt) {
+		if (entry.source === 'assoc') {
+			assocBatch.push(entry.path);
+		} else {
+			flushAssocBatch();
+			sqlParts.push('?');
+			allBindings.push(`${rowVar}.getString("${entry.path}")`);
+		}
+	}
+	flushAssocBatch();
+
+	if (sqlParts.length === 0) {
+		return { sqlExpr: 'NULL', bindings: [] };
+	}
+
+	const sqlExpr = sqlParts.length === 1 ? sqlParts[0] : sqlParts.join(" || ', ' || ");
+	return { sqlExpr, bindings: allBindings };
 }
 
 function _wrapInTryCatch(sql, bindings) {

package/lib/hana/sql-expressions.js

@@ -100,14 +100,9 @@ function getWhereCondition(col, modification) {
 }
 
 /**
- * Returns SQL expression for a column's label (looked-up value for associations)
+ * Builds scalar subselect for association label lookup with locale awareness
  */
-function getLabelExpr(col, refRow, model) {
-	if (!(col.target && col.alt)) {
-		return `NULL`;
-	}
-
-	// Builds inline SELECT expression for association label lookup with locale support
+function buildAssocLookup(col, assocPaths, refRow, model) {
 	let where = {};
 	if (col.foreignKeys) {
 		where = col.foreignKeys.reduce((acc, k) => {
@@ -121,11 +116,11 @@ function getLabelExpr(col, refRow, model) {
 		}, {});
 	}
 
-	const alt = col.alt.map((s) => s.split('.').slice(1).join('.'));
+	const alt = assocPaths.map((s) => s.split('.').slice(1).join('.'));
 	const columns = alt.length === 1 ? alt[0] : utils.buildConcatXpr(alt);
 
 	// Check for localization
-	const localizedInfo = utils.getLocalizedLookupInfo(col.target, col.alt, model);
+	const localizedInfo = utils.getLocalizedLookupInfo(col.target, assocPaths, model);
 	if (localizedInfo) {
 		const textsWhere = { ...where, locale: { func: 'SESSION_CONTEXT', args: [{ val: 'LOCALE' }] } };
 		const textsQuery = SELECT.one.from(localizedInfo.textsEntity).columns(columns).where(textsWhere);
@@ -137,6 +132,35 @@ function getLabelExpr(col, refRow, model) {
 	return `(${toSQL(query, model)})`;
 }
 
+/**
+ * Returns SQL expression for a column's label (looked-up value for associations)
+ */
+function getLabelExpr(col, refRow, model) {
+	if (!col.alt || col.alt.length === 0) return `NULL`;
+
+	const parts = [];
+	let assocBatch = [];
+
+	const flushAssocBatch = () => {
+		if (assocBatch.length > 0) {
+			parts.push(buildAssocLookup(col, assocBatch, refRow, model));
+			assocBatch = [];
+		}
+	};
+
+	for (const entry of col.alt) {
+		if (entry.source === 'assoc') {
+			assocBatch.push(entry.path);
+		} else {
+			flushAssocBatch();
+			parts.push(`TO_NVARCHAR(:${refRow}.${entry.path})`);
+		}
+	}
+	flushAssocBatch();
+
+	return parts.length === 0 ? `NULL` : parts.join(" || ', ' || ");
+}
+
 /**
  * Builds SQL expression for objectID (entity display name)
  * Uses @changelog annotation fields, falling back to entity name

package/lib/postgres/sql-expressions.js

@@ -84,9 +84,13 @@ function getWhereCondition(col, modification) {
 }
 
 /**
- * Builds scalar subselect for association label lookup with locale support
+ * Builds scalar subselect for association label lookup with locale support.
+ * @param {Object} column Column entry with target, foreignKeys/on, etc.
+ * @param {string[]} assocPaths Array of association paths (format: "assocName.field")
+ * @param {string} refRow Trigger row reference ('NEW' or 'OLD')
+ * @param {*} model CSN model
  */
-function buildAssocLookup(column, refRow, model) {
+function buildAssocLookup(column, assocPaths, refRow, model) {
 	let where = {};
 	if (column.foreignKeys) {
 		where = column.foreignKeys.reduce((acc, k) => {
@@ -100,11 +104,11 @@ function buildAssocLookup(column, refRow, model) {
 		}, {});
 	}
 
-	const alt = column.alt.map((s) => s.split('.').slice(1).join('.'));
+	const alt = assocPaths.map((s) => s.split('.').slice(1).join('.'));
 	const columns = alt.length === 1 ? alt[0] : utils.buildConcatXpr(alt);
 
 	// Check for localization
-	const localizedInfo = utils.getLocalizedLookupInfo(column.target, column.alt, model);
+	const localizedInfo = utils.getLocalizedLookupInfo(column.target, assocPaths, model);
 	if (localizedInfo) {
 		const textsWhere = { ...where, locale: { func: 'current_setting', args: [{ val: 'cap.locale' }, { val: true }] } };
 		const textsQuery = SELECT.one.from(localizedInfo.textsEntity).columns(columns).where(textsWhere);
@@ -117,13 +121,34 @@ function buildAssocLookup(column, refRow, model) {
 }
 
 /**
- * Returns SQL expression for a column's label (looked-up value for associations)
+ * Returns SQL expression for a column's label (looked-up value for associations).
+ * Iterates over col.alt entries in order, grouping consecutive association paths
+ * into a single subquery and emitting local references inline from the trigger row.
  */
 function getLabelExpr(col, refRow, model) {
-	if (col.target && col.alt) {
-		return buildAssocLookup(col, refRow, model);
+	if (!col.alt || col.alt.length === 0) return 'NULL';
+
+	const parts = [];
+	let assocBatch = [];
+
+	const flushAssocBatch = () => {
+		if (assocBatch.length > 0) {
+			parts.push(buildAssocLookup(col, assocBatch, refRow, model));
+			assocBatch = [];
+		}
+	};
+
+	for (const entry of col.alt) {
+		if (entry.source === 'assoc') {
+			assocBatch.push(entry.path);
+		} else {
+			flushAssocBatch();
+			parts.push(`${refRow}.${entry.path}::TEXT`);
+		}
 	}
-	return 'NULL';
+	flushAssocBatch();
+
+	return parts.length === 0 ? 'NULL' : parts.join(" || ', ' || ");
 }
 
 /**

package/lib/postgres/triggers.js

@@ -1,7 +1,9 @@
+const cds = require('@sap/cds');
 const utils = require('../utils/change-tracking.js');
 const { getCompositionParentInfo, getGrandParentCompositionInfo } = require('../utils/composition-helpers.js');
 const { getSkipCheckCondition, compositeKeyExpr, buildObjectIDAssignment, buildInsertBlock, extractTrackedDbColumns } = require('./sql-expressions.js');
 const { buildCompositionParentBlock } = require('./composition.js');
+const config = cds.env.requires['change-tracking'];
 
 /**
  * Generates the PL/pgSQL function body for the main change tracking trigger
@@ -18,9 +20,9 @@ function buildFunctionBody(entity, columns, objectIDs, rootEntity, rootObjectIDs
 	const deleteBlock = columns.length > 0 ? buildInsertBlock(columns, 'delete', entity, model, hasCompositionParent) : '';
 
 	// Build composition parent blocks if needed
-	const createParentBlock = compositionParentInfo ? buildCompositionParentBlock(compositionParentInfo, rootObjectIDs, 'create', model, grandParentCompositionInfo) : '';
-	const updateParentBlock = compositionParentInfo ? buildCompositionParentBlock(compositionParentInfo, rootObjectIDs, 'update', model, grandParentCompositionInfo) : '';
-	const deleteParentBlock = compositionParentInfo ? buildCompositionParentBlock(compositionParentInfo, rootObjectIDs, 'delete', model, grandParentCompositionInfo) : '';
+	const createParentBlock = compositionParentInfo && !config?.disableCreateTracking ? buildCompositionParentBlock(compositionParentInfo, rootObjectIDs, 'create', model, grandParentCompositionInfo) : '';
+	const updateParentBlock = compositionParentInfo && !config?.disableUpdateTracking ? buildCompositionParentBlock(compositionParentInfo, rootObjectIDs, 'update', model, grandParentCompositionInfo) : '';
+	const deleteParentBlock = compositionParentInfo && !config?.disableDeleteTracking ? buildCompositionParentBlock(compositionParentInfo, rootObjectIDs, 'delete', model, grandParentCompositionInfo) : '';
 
 	return `
         DECLARE

package/lib/sqlite/sql-expressions.js

@@ -95,7 +95,7 @@ function getWhereCondition(col, modification) {
 /**
  * Builds scalar subselect for association label lookup with locale awareness
  */
-function buildAssocLookup(column, refRow, entityKey, model) {
+function buildAssocLookup(column, assocPaths, refRow, entityKey, model) {
 	const where = column.foreignKeys
 		? column.foreignKeys.reduce((acc, k) => {
 				acc[k] = { val: `${refRow}.${column.name}_${k}` };
@@ -107,12 +107,12 @@ function buildAssocLookup(column, refRow, entityKey, model) {
 				return acc;
 			}, {});
 
-	// Drop the first part of column.alt (association name)
-	const alt = column.alt.map((s) => s.split('.').slice(1).join('.'));
+	// Drop the first part of each path (association name)
+	const alt = assocPaths.map((s) => s.split('.').slice(1).join('.'));
 	const columns = alt.length === 1 ? alt[0] : utils.buildConcatXpr(alt);
 
 	// Check for localization
-	const localizedInfo = utils.getLocalizedLookupInfo(column.target, column.alt, model);
+	const localizedInfo = utils.getLocalizedLookupInfo(column.target, assocPaths, model);
 	if (localizedInfo) {
 		const textsWhere = { ...where, locale: { func: 'session_context', args: [{ val: '$user.locale' }] } };
 		const textsQuery = SELECT.one.from(localizedInfo.textsEntity).columns(columns).where(textsWhere);
@@ -128,10 +128,30 @@ function buildAssocLookup(column, refRow, entityKey, model) {
  * Returns SQL expression for a column's label (looked-up value for associations)
  */
 function getLabelExpr(col, refRow, entityKey, model) {
-	if (col.target && col.alt) {
-		return buildAssocLookup(col, refRow, entityKey, model);
+	if (!col.alt || col.alt.length === 0) return 'NULL';
+
+	const parts = [];
+	let assocBatch = [];
+
+	const flushAssocBatch = () => {
+		if (assocBatch.length > 0) {
+			parts.push(buildAssocLookup(col, assocBatch, refRow, entityKey, model));
+			assocBatch = [];
+		}
+	};
+
+	for (const entry of col.alt) {
+		if (entry.source === 'assoc') {
+			assocBatch.push(entry.path);
+		} else {
+			// local field: flush any pending association batch first, then emit local ref
+			flushAssocBatch();
+			parts.push(`${refRow}.${entry.path}`);
+		}
 	}
-	return 'NULL';
+	flushAssocBatch();
+
+	return parts.length === 0 ? 'NULL' : parts.join(" || ', ' || ");
 }
 
 /**

package/lib/utils/change-tracking.js

@@ -173,7 +173,9 @@ function extractTrackedColumns(entity, model = cds.context?.model ?? cds.model,
 				const changelogPaths = changelogAnnotation.map((c) => c['=']);
 				for (const path of changelogPaths) {
 					const p = validateChangelogPath(entity, path, model);
-					if (p) alt.push(p);
+					if (!p) continue;
+					if (p.includes('.')) alt.push({ path: p, source: 'assoc' });
+					else alt.push({ path: p, source: 'local' });
 				}
 				if (alt.length > 0) entry.alt = alt;
 			}
@@ -352,6 +354,7 @@ function getCompositionParentBinding(targetEntity, rootEntity) {
 }
 
 function getLocalizedLookupInfo(targetEntityName, altFields, model = cds.context?.model ?? cds.model) {
+	if (!altFields || altFields.length === 0) return null;
 	const targetEntity = model.definitions[targetEntityName];
 	if (!targetEntity) return null;
 

package/lib/utils/entity-collector.js

@@ -227,6 +227,25 @@ function getBaseEntity(entity, model) {
 	}
 }
 
+function getBaseElement(element, entity, model) {
+	const cqn = entity.projection ?? entity.query?.SELECT;
+	if (!cqn) return null;
+	element = cqn.columns?.find((c) => c.as === element && c.ref)?.ref?.[0] ?? element;
+
+	const baseRef = cqn.from?.ref?.[0];
+	if (!baseRef || !model) return null;
+
+	const baseEntity = model.definitions[baseRef];
+	if (!baseEntity) return null;
+	const baseCQN = baseEntity.projection ?? baseEntity.query?.SELECT ?? baseEntity.query?.SET;
+	// If base entity is also a projection, recurse
+	if (baseCQN) {
+		return getBaseElement(element, baseEntity, model);
+	} else {
+		return { baseRef, baseElement: element };
+	}
+}
+
 // Analyze composition hierarchy in CSN
 function analyzeCompositions(csn) {
 	// First pass: build child -> { parent, compositionField } map
@@ -318,5 +337,6 @@ module.exports = {
 	getBaseEntity,
 	analyzeCompositions,
 	getService,
-	collectEntities
+	collectEntities,
+	getBaseElement
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cap-js/change-tracking",
-	"version": "2.0.0-beta.4",
+	"version": "2.0.0-beta.5",
 	"publishConfig": {
 		"access": "public",
 		"tag": "beta"