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

package/lib/csn-enhancements/timezoneProperties.js

@@ -0,0 +1,81 @@
+const cds = require('@sap/cds');
+const { compositeKeyExpr: compositeKeyExprSqlite } = require('../sqlite/sql-expressions');
+const { compositeKeyExpr: compositeKeyExprHANA } = require('../hana/sql-expressions');
+const { compositeKeyExpr: compositeKeyExprPG } = require('../postgres/sql-expressions');
+const { isChangeTracked } = require('../utils/entity-collector');
+
+function collectTrackedPropertiesWithTimezone(m) {
+	const timezoneProperties = [];
+	for (const name in m.definitions) {
+		const entity = m.definitions[name];
+		if (entity.kind !== 'entity' || entity.query || entity.projection || !isChangeTracked(entity)) {
+			continue;
+		}
+		for (const ele in entity.elements) {
+			const element = entity.elements[ele];
+			if (!element['@Common.Timezone'] || element._foreignKey4) {
+				continue;
+			}
+			timezoneProperties.push({
+				property: ele,
+				entity: name,
+				timezone: element['@Common.Timezone']?.['=']
+					? // Where condition is replaced when select is inserted into ChangeView
+						SELECT.from(name).alias('timezoneSubSelect').where('1 = 1').columns(element['@Common.Timezone']['='])
+					: element['@Common.Timezone']
+			});
+		}
+	}
+	return timezoneProperties;
+}
+
+function isDeploy2Check(target) {
+	try {
+		cds.build?.register(target, class ABC extends cds.build.Plugin {});
+	} catch (err) {
+		if (err.message.match(/already registered/)) {
+			return true;
+		}
+	}
+	return false;
+}
+
+function enhanceChangeViewWithTimeZones(changeView, m) {
+	const compositeKeyExpr =
+		isDeploy2Check('hana') && m.meta.creator.match(/v6/)
+			? compositeKeyExprHANA
+			: isDeploy2Check('postgres') && m.meta.creator.match(/v6/)
+				? compositeKeyExprPG
+				: cds.env.requires?.db.kind === 'sqlite' && !cds.build
+					? compositeKeyExprSqlite
+					: cds.env.requires?.db.kind === 'postgres' && (!cds.build || cds.env.profiles.includes('pg'))
+						? compositeKeyExprPG
+						: compositeKeyExprHANA;
+	const timezoneProperties = collectTrackedPropertiesWithTimezone(m);
+	const timezoneColumn = changeView.query.SELECT.columns.find((c) => c.as && c.as === 'valueTimeZone');
+	if (timezoneProperties.length === 0) return;
+	delete timezoneColumn.val;
+	timezoneColumn.xpr = ['case'];
+	for (const timezoneProp of timezoneProperties) {
+		timezoneColumn.xpr.push('when', { ref: ['attribute'] }, '=', { val: timezoneProp.property }, 'and', { ref: ['entity'] }, '=', { val: timezoneProp.entity }, 'then');
+		if (timezoneProp.timezone.SELECT) {
+			const subSelect = structuredClone(timezoneProp.timezone);
+			const keys = Object.keys(m.definitions[timezoneProp.entity].elements).filter((e) => m.definitions[timezoneProp.entity].elements[e].key);
+			subSelect.SELECT.where = [
+				{ ref: ['change', 'entityKey'] },
+				'=',
+				// REVISIT: once HIERARCHY_COMPOSITE_ID is available on all DBs, use native CQN
+				compositeKeyExpr(keys)
+			];
+			timezoneColumn.xpr.push(subSelect);
+		} else {
+			timezoneColumn.xpr.push({ val: timezoneProp.timezone });
+		}
+	}
+	timezoneColumn.xpr.push('else', { val: null }, 'end');
+}
+
+module.exports = {
+	collectTrackedPropertiesWithTimezone,
+	enhanceChangeViewWithTimeZones
+};

package/lib/h2/java-codegen.js

@@ -709,7 +709,7 @@ function _generateObjectIDCalculation(objectIDs, entity, refRow, model) {
 
 	for (const oid of objectIDs) {
 		if (oid.included) {
-			parts.push(`SELECT CAST(? AS VARCHAR) AS val`);
+			parts.push(`SELECT COALESCE(CAST(? AS VARCHAR), '<empty>') AS val`);
 			bindings.push(`${refRow}.getString("${oid.name}")`);
 		} else {
 			// Sub-select needed (Lookup)

package/lib/hana/register.js

@@ -1,7 +1,7 @@
 const cds = require('@sap/cds');
-const { fs } = cds.utils;
 
-const { prepareCSNForTriggers, generateTriggersForEntities, writeLabelsCSV, ensureUndeployJsonHasTriggerPattern } = require('../utils/trigger-utils.js');
+const { prepareCSNForTriggers, generateTriggersForEntities, ensureUndeployJsonHasTriggerPattern } = require('../utils/trigger-utils.js');
+const { getLabelTranslations } = require('../localization.js');
 
 function registerHDICompilerHook() {
 	const _hdi_migration = cds.compiler.to.hdi.migration;
@@ -10,19 +10,48 @@ function registerHDICompilerHook() {
 		const { runtimeCSN, hierarchy, entities } = prepareCSNForTriggers(csn, true);
 
 		const triggers = generateTriggersForEntities(runtimeCSN, hierarchy, entities, generateHANATriggers);
-
+		const data = [];
 		if (triggers.length > 0) {
 			delete csn.definitions['sap.changelog.CHANGE_TRACKING_DUMMY']['@cds.persistence.skip'];
-			writeLabelsCSV(entities, runtimeCSN);
-			const dir = 'db/src/gen/data/';
-			fs.writeFileSync(`${dir}/sap.changelog-CHANGE_TRACKING_DUMMY.csv`, `X\n1`);
 			ensureUndeployJsonHasTriggerPattern();
+
+			const labels = getLabelTranslations(entities, runtimeCSN);
+			const header = 'ID;locale;text';
+			const escape = (v) => {
+				const s = String(v ?? '');
+				return s.includes(';') || s.includes('\n') || s.includes('"') ? `"${s.replace(/"/g, '""')}"` : s;
+			};
+			const rows = labels.map((row) => `${escape(row.ID)};${escape(row.locale)};${escape(row.text)}`);
+			const i18nContent = [header, ...rows].join('\n') + '\n';
+
+			data.push(
+				{
+					name: 'sap.changelog-CHANGE_TRACKING_DUMMY',
+					sql: 'X\n1',
+					suffix: '.csv'
+				},
+				{
+					name: 'sap.changelog-i18nKeys',
+					sql: i18nContent,
+					suffix: '.csv'
+				}
+			);
 		}
 
 		const ret = _hdi_migration(csn, options, beforeImage);
-		ret.definitions = [...ret.definitions, ...triggers];
+		ret.definitions = ret.definitions.concat(triggers).concat(data);
 		return ret;
 	};
+
+	// REVISIT: Remove once time casting is fixed in cds-dbs
+	cds.on('serving', async () => {
+		if (cds.env.requires?.db.kind !== 'hana') return;
+		const db = await cds.connect.to('db');
+		db.before('*', () => {
+			// to_time conversion is necessary else HANA tries to convert to timestamp implicitly causing an SQL crash
+			db.class.CQN2SQL.OutputConverters.Time = (e) => `to_char(to_time(${e}), 'HH24:MI:SS')`;
+		});
+	});
 }
 
 module.exports = { registerHDICompilerHook };

package/lib/hana/sql-expressions.js

@@ -152,7 +152,7 @@ function buildObjectIDExpr(objectIDs, entity, rowRef, model) {
 	const parts = [];
 	for (const oid of objectIDs) {
 		if (oid.included) {
-			parts.push(`TO_NVARCHAR(:${rowRef}.${oid.name})`);
+			parts.push(`COALESCE(TO_NVARCHAR(:${rowRef}.${oid.name}), '<empty>')`);
 		} else {
 			const where = keys.reduce((acc, k) => {
 				acc[k] = { val: `:${rowRef}.${k}` };

package/lib/postgres/register.js

@@ -26,6 +26,18 @@ function registerPostgresCompilerHook() {
 
 		return ddl;
 	});
+
+	// REVISIT: Remove once time casting is fixed in cds-dbs
+	cds.on('serving', async () => {
+		if (cds.env.requires?.db.kind !== 'postgres') return;
+		const db = await cds.connect.to('db');
+		db.before('*', () => {
+			db.class.CQN2SQL.OutputConverters.Date = (e) => `to_date(${e}::text, 'YYYY-MM-DD')`;
+			db.class.CQN2SQL.OutputConverters.Time = (e) => `to_timestamp(${e}::text, 'HH24:MI:SS')::TIME`;
+			db.class.CQN2SQL.OutputConverters.DateTime = (e) => `to_timestamp(${e}::text, 'YYYY-MM-DD"T"HH24:MI:SS"Z"')::timestamp`;
+			db.class.CQN2SQL.OutputConverters.Timestamp = (e) => `to_timestamp(${e}::text, 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"')::timestamp`;
+		});
+	});
 }
 
 async function deployPostgresLabels() {

package/lib/postgres/sql-expressions.js

@@ -137,7 +137,7 @@ function buildObjectIDAssignment(objectIDs, entity, keys, recVar, targetVar, mod
 	const parts = [];
 	for (const oid of objectIDs) {
 		if (oid.included) {
-			parts.push(`${recVar}.${oid.name}::TEXT`);
+			parts.push(`COALESCE(${recVar}.${oid.name}::TEXT, '<empty>')`);
 		} else {
 			const where = keys.reduce((acc, k) => {
 				acc[k] = { val: `${recVar}.${k}` };

package/lib/sqlite/sql-expressions.js

@@ -148,7 +148,7 @@ function buildObjectIDSelect(objectIDs, entityName, entityKeys, refRow, model) {
 		objectID.selectSQL = toSQL(query, model);
 	}
 
-	const unionParts = objectIDs.map((id) => (id.included ? `SELECT ${refRow}.${id.name} AS value WHERE ${refRow}.${id.name} IS NOT NULL` : `SELECT (${id.selectSQL}) AS value`));
+	const unionParts = objectIDs.map((id) => (id.included ? `SELECT COALESCE(${refRow}.${id.name}, '<empty>') AS value` : `SELECT (${id.selectSQL}) AS value`));
 
 	return `(SELECT GROUP_CONCAT(value, ', ') FROM (${unionParts.join('\nUNION ALL\n')}))`;
 }

package/lib/utils/change-tracking.js

@@ -105,8 +105,12 @@ function extractTrackedColumns(entity, model = cds.context?.model ?? cds.model,
 		// Use override annotation if provided, otherwise use the element's own annotation
 		const changelogAnnotation = overrideAnnotations?.elementAnnotations?.[name] ?? col['@changelog'];
 
-		// Skip non-changelog columns + association columns (we want the generated FKs instead)
-		if (!changelogAnnotation || col._foreignKey4 || col['@odata.foreignKey4']) continue;
+		// Skip foreign key columns (we want the generated FKs instead)
+		if (col._foreignKey4 || col['@odata.foreignKey4']) continue;
+
+		// Auto-include composition elements, unless explicitly defined with @changelog: false
+		const isComposition = col.type === 'cds.Composition';
+		if ((!changelogAnnotation && !isComposition) || changelogAnnotation === false) continue;
 
 		// skip any PersonalData* annotation
 		const hasPersonalData = Object.keys(col).some((k) => k.startsWith('@PersonalData'));

package/lib/utils/composition-helpers.js

@@ -2,8 +2,6 @@ const utils = require('./change-tracking.js');
 
 /**
  * Finds composition parent info for an entity.
- * Checks if root entity has a @changelog annotation on a composition field pointing to this entity.
- *
  * Returns null if not found, or an object with:
  *   { parentEntityName, compositionFieldName, parentKeyBinding, isCompositionOfOne }
  */
@@ -13,9 +11,9 @@ function getCompositionParentInfo(entity, rootEntity, rootMergedAnnotations) {
 	for (const [elemName, elem] of Object.entries(rootEntity.elements)) {
 		if (elem.type !== 'cds.Composition' || elem.target !== entity.name) continue;
 
-		// Check if this composition has @changelog annotation
+		// Check if this composition has @changelog: false annotation
 		const changelogAnnotation = rootMergedAnnotations?.elementAnnotations?.[elemName] ?? elem['@changelog'];
-		if (!changelogAnnotation) continue;
+		if (changelogAnnotation === false) continue;
 
 		// Found a tracked composition - get the FK binding from child to parent
 		const parentKeyBinding = utils.getCompositionParentBinding(entity, rootEntity);
@@ -46,12 +44,12 @@ function getCompositionParentInfo(entity, rootEntity, rootMergedAnnotations) {
 function getGrandParentCompositionInfo(rootEntity, grandParentEntity, grandParentMergedAnnotations, grandParentCompositionField) {
 	if (!grandParentEntity || !grandParentCompositionField) return null;
 
-	// Check if the grandparent's composition field has @changelog annotation
+	// Check if the grandparent's composition field has @changelog: false annotation
 	const elem = grandParentEntity.elements?.[grandParentCompositionField];
 	if (!elem || elem.type !== 'cds.Composition' || elem.target !== rootEntity.name) return null;
 
 	const changelogAnnotation = grandParentMergedAnnotations?.elementAnnotations?.[grandParentCompositionField] ?? elem['@changelog'];
-	if (!changelogAnnotation) return null;
+	if (changelogAnnotation === false) return null;
 
 	// Get FK binding from rootEntity to grandParentEntity
 	const grandParentKeyBinding = utils.getCompositionParentBinding(rootEntity, grandParentEntity);

package/lib/utils/entity-collector.js

@@ -8,6 +8,11 @@ function isChangeTracked(entity) {
 	return Object.values(entity.elements).some((e) => e['@changelog']);
 }
 
+function _hasTrackedElements(entity) {
+	if (!entity?.elements) return false;
+	return Object.values(entity.elements).some((e) => e['@changelog'] && e['@changelog'] !== false);
+}
+
 // Compares two @changelog annotation values for equality
 function _annotationsEqual(a, b) {
 	// Handle null/undefined/false cases
@@ -97,20 +102,27 @@ function _mergeChangelogAnnotations(dbEntity, serviceEntities) {
 	};
 }
 
-function getEntitiesForTriggerGeneration(model, collected) {
-	const result = [];
-	const processedDbEntities = new Set();
+function _extractServiceAnnotations(serviceEntity) {
+	const entityAnnotation = serviceEntity['@changelog'];
+	const elementAnnotations = {};
+	for (const element of serviceEntity.elements) {
+		if (element['@changelog'] !== undefined) {
+			elementAnnotations[element.name] = element['@changelog'];
+		}
+	}
+	return { entity: serviceEntity, entityAnnotation, elementAnnotations };
+}
 
-	// Process collected service entities - resolve entities and annotations from names
+// Resolve collected service entities into DB entities with merged annotations
+function _collectServiceEntities(model, collected, result, processed) {
 	for (const [dbEntityName, serviceEntityNames] of collected) {
-		processedDbEntities.add(dbEntityName);
+		processed.add(dbEntityName);
 		const dbEntity = model[dbEntityName];
 		if (!dbEntity) {
 			DEBUG?.(`DB entity ${dbEntityName} not found in model, skipping`);
 			continue;
 		}
 
-		// Resolve service entities and extract their annotations
 		const serviceEntities = [];
 		for (const name of serviceEntityNames) {
 			const serviceEntity = model[name];
@@ -118,21 +130,7 @@ function getEntitiesForTriggerGeneration(model, collected) {
 				DEBUG?.(`Service entity ${name} not found in model, skipping`);
 				continue;
 			}
-
-			// Extract @changelog annotations from the service entity
-			const entityAnnotation = serviceEntity['@changelog'];
-			const elementAnnotations = {};
-			for (const element of serviceEntity.elements) {
-				if (element['@changelog'] !== undefined) {
-					elementAnnotations[element.name] = element['@changelog'];
-				}
-			}
-
-			serviceEntities.push({
-				entity: serviceEntity,
-				entityAnnotation,
-				elementAnnotations
-			});
+			serviceEntities.push(_extractServiceAnnotations(serviceEntity));
 		}
 
 		try {
@@ -144,42 +142,68 @@ function getEntitiesForTriggerGeneration(model, collected) {
 			throw error;
 		}
 	}
+}
 
-	// Add table entities that have @changelog but weren't collected
+// Include standalone DB entities that have @changelog but no service projection
+function _collectStandaloneEntities(model, result, processed) {
 	for (const def of model) {
 		const isTableEntity = def.kind === 'entity' && !def.query && !def.projection;
-		if (!isTableEntity || processedDbEntities.has(def.name)) continue;
+		if (!isTableEntity || processed.has(def.name)) continue;
 
 		if (isChangeTracked(def)) {
-			// No service entities collected, use null for mergedAnnotations (use entity's own annotations)
 			result.push({ dbEntityName: def.name, mergedAnnotations: null });
-			processedDbEntities.add(def.name);
+			processed.add(def.name);
 			DEBUG?.(`Including DB entity ${def.name} directly (no service entities collected)`);
 		}
 	}
+}
 
-	// Add composition-of-many target entities that have @changelog on the composition field
-	for (const { dbEntityName, mergedAnnotations } of [...result]) {
-		const dbEntity = model[dbEntityName];
+/**
+ * Auto-discover composition target entities up to the configured hierarchy depth
+ * Compositions are auto-tracked when the parent is tracked and field is not set to @changelog: false, and target has at least one @changelog element (or the field has an explicit @changelog)
+ */
+function _discoverCompositionTargets(model, result, processed) {
+	const maxDepth = cds.env.requires?.['change-tracking']?.maxDisplayHierarchyDepth ?? 3;
+	let currentEntities = [...result];
+
+	for (let depth = 1; depth < maxDepth; depth++) {
+		const newEntities = [];
 
-		for (const element of Object.values(dbEntity.elements)) {
-			if (element.type !== 'cds.Composition' || !element.is2many || !element.target) continue;
+		for (const { dbEntityName, mergedAnnotations } of currentEntities) {
+			const dbEntity = model[dbEntityName];
+			if (!dbEntity) continue;
 
-			const changelogAnnotation = mergedAnnotations?.elementAnnotations?.[element.name] ?? element['@changelog'];
-			if (!changelogAnnotation) continue;
+			for (const element of Object.values(dbEntity.elements)) {
+				if (element.type !== 'cds.Composition' || !element.target) continue;
+				if (processed.has(element.target)) continue;
 
-			// Skip if target entity is already processed
-			if (processedDbEntities.has(element.target)) continue;
+				const changelogAnnotation = mergedAnnotations?.elementAnnotations?.[element.name] ?? element['@changelog'];
+				if (changelogAnnotation === false) continue;
 
-			const targetEntity = model[element.target];
-			if (!targetEntity) continue;
+				const targetEntity = model[element.target];
+				if (!targetEntity) continue;
+				if (!changelogAnnotation && !_hasTrackedElements(targetEntity)) continue;
 
-			// Add target entity with null mergedAnnotations (it uses its own annotations, if any)
-			result.push({ dbEntityName: element.target, mergedAnnotations: null });
-			processedDbEntities.add(element.target);
-			DEBUG?.(`Including composition target ${element.target} for tracked composition ${element.name} on ${dbEntityName}`);
+				const entry = { dbEntityName: element.target, mergedAnnotations: null };
+				result.push(entry);
+				processed.add(element.target);
+				newEntities.push(entry);
+				DEBUG?.(`Including composition target ${element.target} for ${changelogAnnotation ? 'tracked' : 'auto-tracked'} composition ${element.name} on ${dbEntityName} (depth ${depth})`);
+			}
 		}
+
+		if (newEntities.length === 0) break;
+		currentEntities = newEntities;
 	}
+}
+
+function getEntitiesForTriggerGeneration(model, collected) {
+	const result = [];
+	const processed = new Set();
+
+	_collectServiceEntities(model, collected, result, processed);
+	_collectStandaloneEntities(model, result, processed);
+	_discoverCompositionTargets(model, result, processed);
 
 	return result;
 }
@@ -225,11 +249,12 @@ function analyzeCompositions(csn) {
 
 	// Second pass: build hierarchy with grandparent info
 	const hierarchy = new Map();
+	const maxDepth = cds.env.requires?.['change-tracking']?.maxDisplayHierarchyDepth ?? 3;
 	for (const [childName, parentInfo] of childParentMap) {
 		const { parent: parentName, compositionField } = parentInfo;
 
-		// Check if the parent itself has a parent (grandparent)
-		const grandParentInfo = childParentMap.get(parentName);
+		// Only include grandparent info if maxDisplayHierarchyDepth allows it (depth > 2 needed for grandparent)
+		const grandParentInfo = maxDepth > 2 ? childParentMap.get(parentName) : null;
 
 		hierarchy.set(childName, {
 			parent: parentName,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cap-js/change-tracking",
-	"version": "2.0.0-beta.2",
+	"version": "2.0.0-beta.4",
 	"publishConfig": {
 		"access": "public",
 		"tag": "beta"
@@ -44,7 +44,6 @@
 		"requires": {
 			"change-tracking": {
 				"model": "@cap-js/change-tracking",
-				"considerLocalizedValues": false,
 				"maxDisplayHierarchyDepth": 3,
 				"preserveDeletes": false
 			}