feat(framework): introduce runtimes and version info (#4491)

Author: vladitasev

packages/base/.eslintignore

@@ -12,3 +12,4 @@ postcss.config.js
 package-scripts.js
 .eslintrc.js
 src/renderer/directives/style-map.js
+src/util/metaUrl.js

packages/base/hash.txt

@@ -1 +1 @@
-o94uov3PET7YqHV/VdedxOnCg5M=
+RNSU7YzpfGMOwn0wc5+tQL7ZLGs=

packages/base/lib/generate-version-info/index.js

@@ -0,0 +1,27 @@
+const fs = require('fs');
+const mkdirp = require('mkdirp');
+
+const version = JSON.parse(fs.readFileSync("package.json")).version;
+
+// Parse version
+const matches = version.match(/^([0-9]+)\.([0-9]+)\.([0-9]+)(.*)$/);
+if (!matches) {
+	throw new Error("Unsupported version format");
+}
+
+const isNext = version.match(/[a-f0-9]{9}$/);
+const buildTime = Math.floor(new Date().getTime() / 1000);
+
+const fileContent = `const VersionInfo = {
+	version: "${version}",
+	major: ${matches[1]},
+	minor: ${matches[2]},
+	patch: ${matches[3]},
+	suffix: "${matches[4]}",
+	isNext: ${isNext ? "true" : "false"},
+	buildTime: ${buildTime},
+};
+export default VersionInfo;`;
+
+mkdirp.sync("dist/generated/");
+fs.writeFileSync("dist/generated/VersionInfo.js", fileContent);

packages/base/package-scripts.js

@@ -2,6 +2,7 @@ const resolve = require("resolve");
 
 const assetParametersScript = resolve.sync("@ui5/webcomponents-base/lib/generate-asset-parameters/index.js");
 const stylesScript = resolve.sync("@ui5/webcomponents-base/lib/generate-styles/index.js");
+const versionScript = resolve.sync("@ui5/webcomponents-base/lib/generate-version-info/index.js");
 const serve = resolve.sync("@ui5/webcomponents-tools/lib/serve/index.js");
 const generateHash = resolve.sync("@ui5/webcomponents-tools/lib/hash/generate.js");
 const hashIsUpToDate = resolve.sync("@ui5/webcomponents-tools/lib/hash/upToDate.js");
@@ -13,7 +14,7 @@ const UP_TO_DATE = `node "${hashIsUpToDate}" dist/ hash.txt && echo "Up to date.
 const scripts = {
 	clean: "rimraf dist && rimraf .port",
 	lint: "eslint . --config config/.eslintrc.js",
-	prepare: "nps clean integrate copy generateAssetParameters generateStyles",
+	prepare: "nps clean integrate copy generateAssetParameters generateVersionInfo generateStyles",
 	integrate: {
 		default: "nps integrate.copy-used-modules integrate.copy-overlay integrate.replace-amd integrate.replace-export-true integrate.replace-export-false integrate.amd-to-es6 integrate.replace-global-core-usage integrate.esm-abs-to-rel integrate.third-party",
 		"copy-used-modules": `node "${copyUsedModules}" ./used-modules.txt dist/`,
@@ -40,6 +41,7 @@ const scripts = {
 		test: `copy-and-watch "test/**/*.*" dist/test-resources`,
 	},
 	generateAssetParameters: `node "${assetParametersScript}"`,
+	generateVersionInfo: `node "${versionScript}"`,
 	generateStyles: `node "${stylesScript}"`,
 	watch: {
 		default: 'concurrently "nps watch.test" "nps watch.src" "nps watch.bundle" "nps watch.styles"',

packages/base/src/Boot.js

@@ -4,6 +4,7 @@ import insertFontFace from "./FontFace.js";
 import insertSystemCSSVars from "./SystemCSSVars.js";
 import { getTheme } from "./config/Theme.js";
 import applyTheme from "./theming/applyTheme.js";
+import { registerCurrentRuntime } from "./Runtimes.js";
 import { getFeature } from "./FeaturesRegistry.js";
 
 let booted = false;
@@ -23,6 +24,8 @@ const boot = async () => {
 		return;
 	}
 
+	registerCurrentRuntime();
+
 	const OpenUI5Support = getFeature("OpenUI5Support");
 	if (OpenUI5Support) {
 		await OpenUI5Support.init();

packages/base/src/CustomElementsRegistry.js

@@ -1,11 +1,18 @@
 import setToArray from "./util/setToArray.js";
+import getSharedResource from "./getSharedResource.js";
+import { getCurrentRuntimeIndex, compareRuntimes, getAllRuntimes } from "./Runtimes.js";
+
+const Tags = getSharedResource("Tags", new Map());
 
 const Definitions = new Set();
-const Failures = new Set();
+let Failures = {};
 let failureTimeout;
 
+const UNKNOWN_RUNTIME = "unknown";
+
 const registerTag = tag => {
 	Definitions.add(tag);
+	Tags.set(tag, getCurrentRuntimeIndex());
 };
 
 const isTagRegistered = tag => {
@@ -17,18 +24,67 @@ const getAllRegisteredTags = () => {
 };
 
 const recordTagRegistrationFailure = tag => {
-	Failures.add(tag);
+	let tagRegRuntimeIndex = Tags.get(tag);
+	if (tagRegRuntimeIndex === undefined) {
+		tagRegRuntimeIndex = UNKNOWN_RUNTIME; // If the tag is taken, but not registered in Tags, then a version before 1.1.0 defined it => use the "unknown" key
+	}
+	Failures[tagRegRuntimeIndex] = Failures[tagRegRuntimeIndex] || new Set();
+	Failures[tagRegRuntimeIndex].add(tag);
+
 	if (!failureTimeout) {
 		failureTimeout = setTimeout(() => {
 			displayFailedRegistrations();
+			Failures = {};
 			failureTimeout = undefined;
 		}, 1000);
 	}
 };
 
 const displayFailedRegistrations = () => {
-	console.warn(`The following tags have already been defined by a different UI5 Web Components version: ${setToArray(Failures).join(", ")}`); // eslint-disable-line
-	Failures.clear();
+	const allRuntimes = getAllRuntimes();
+	const currentRuntimeIndex = getCurrentRuntimeIndex();
+	const currentRuntime = allRuntimes[currentRuntimeIndex];
+
+	let message = `Multiple UI5 Web Components instances detected.`;
+
+	if (allRuntimes.length > 1) {
+		message = `${message}\nLoading order (versions before 1.1.0 not listed): ${allRuntimes.map(runtime => `\n${runtime.description} ${runtime.url}`).join("")}`;
+	}
+
+	Object.keys(Failures).forEach(otherRuntimeIndex => {
+		let comparison;
+		let otherRuntime;
+
+		if (otherRuntimeIndex === UNKNOWN_RUNTIME) { // version < 1.1.0 defined the tag
+			comparison = 1; // the current runtime is considered newer
+			otherRuntime = {
+				description: `Older unknown runtime`,
+			};
+		} else {
+			comparison = compareRuntimes(currentRuntimeIndex, otherRuntimeIndex);
+			otherRuntime = allRuntimes[otherRuntimeIndex];
+		}
+
+		let compareWord;
+		if (comparison > 0) {
+			compareWord = "an older";
+		} else if (comparison < 0) {
+			compareWord = "a newer";
+		} else {
+			compareWord = "the same";
+		}
+		message = `${message}\n\n"${currentRuntime.description}" failed to define ${Failures[otherRuntimeIndex].size} tag(s) as they were defined by a runtime of ${compareWord} version "${otherRuntime.description}": ${setToArray(Failures[otherRuntimeIndex]).sort().join(", ")}.`;
+
+		if (comparison > 0) {
+			message = `${message}\nWARNING! If your code uses features of the above web components, unavailable in ${otherRuntime.description}, it might not work as expected!`;
+		} else {
+			message = `${message}\nSince the above web components were defined by the same or newer version runtime, they should be compatible with your code.`;
+		}
+	});
+
+	message = `${message}\n\nTo prevent other runtimes from defining tags that you use, consider using scoping or have third-party libraries use scoping: https://github.com/SAP/ui5-webcomponents/blob/master/docs/2-advanced/03-scoping.md.`;
+
+	console.warn(message); // eslint-disable-line
 };
 
 export {

packages/base/src/Runtimes.js

@@ -0,0 +1,109 @@
+import VersionInfo from "./generated/VersionInfo.js";
+import getSharedResource from "./getSharedResource.js";
+import metaUrl from "./util/metaUrl.js"; // eslint-disable-line
+
+let currentRuntimeIndex;
+let currentRuntimeAlias = "";
+
+const compareCache = new Map();
+
+/**
+ * Central registry where all runtimes register themselves by pushing an object.
+ * The index in the registry servers as an ID for the runtime.
+ * @type {*}
+ */
+const Runtimes = getSharedResource("Runtimes", []);
+
+/**
+ * Registers the current runtime in the shared runtimes resource registry
+ */
+const registerCurrentRuntime = () => {
+	if (currentRuntimeIndex === undefined) {
+		currentRuntimeIndex = Runtimes.length;
+		Runtimes.push({
+			...VersionInfo,
+			url: metaUrl,
+			alias: currentRuntimeAlias,
+			description: `Runtime ${currentRuntimeIndex} - ver ${VersionInfo.version}${currentRuntimeAlias ? ` (${currentRuntimeAlias})` : ""}`,
+		});
+	}
+};
+
+/**
+ * Returns the index of the current runtime's object in the shared runtimes resource registry
+ * @returns {*}
+ */
+const getCurrentRuntimeIndex = () => {
+	return currentRuntimeIndex;
+};
+
+/**
+ * Compares two runtimes and returns 1 if the first is of a bigger version, -1 if the second is of a bigger version, and 0 if equal
+ * @param index1 The index of the first runtime to compare
+ * @param index2 The index of the second runtime to compare
+ * @returns {number}
+ */
+const compareRuntimes = (index1, index2) => {
+	const cacheIndex = `${index1},${index2}`;
+	if (compareCache.has(cacheIndex)) {
+		return compareCache.get(cacheIndex);
+	}
+
+	const runtime1 = Runtimes[index1];
+	const runtime2 = Runtimes[index2];
+
+	if (!runtime1 || !runtime2) {
+		throw new Error("Invalid runtime index supplied");
+	}
+
+	// If any of the two is a next version, bigger buildTime wins
+	if (runtime1.isNext || runtime2.isNext) {
+		return runtime1.buildTime - runtime2.buildTime;
+	}
+
+	// If major versions differ, bigger one wins
+	const majorDiff = runtime1.major - runtime2.major;
+	if (majorDiff) {
+		return majorDiff;
+	}
+
+	// If minor versions differ, bigger one wins
+	const minorDiff = runtime1.minor - runtime2.minor;
+	if (minorDiff) {
+		return minorDiff;
+	}
+
+	// If patch versions differ, bigger one wins
+	const patchDiff = runtime1.patch - runtime2.patch;
+	if (patchDiff) {
+		return patchDiff;
+	}
+
+	// Bigger suffix wins, f.e. rc10 > rc9
+	// Important: suffix is alphanumeric, must use natural compare
+	const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: "base" });
+	const result = collator.compare(runtime1.suffix, runtime2.suffix);
+
+	compareCache.set(cacheIndex, result);
+	return result;
+};
+
+/**
+ * Set an alias for the the current app/library/microfrontend which will appear in debug messages and console warnings
+ * @param alias
+ */
+const setRuntimeAlias = alias => {
+	currentRuntimeAlias = alias;
+};
+
+const getAllRuntimes = () => {
+	return Runtimes;
+};
+
+export {
+	getCurrentRuntimeIndex,
+	registerCurrentRuntime,
+	compareRuntimes,
+	setRuntimeAlias,
+	getAllRuntimes,
+};

packages/base/src/util/metaUrl.js

@@ -0,0 +1,3 @@
+const metaUrl = import.meta.url;
+
+export default metaUrl;

packages/main/csp.js renamed to packages/main/bundle.common.bootstrap.js

@@ -1,5 +1,8 @@
+import { setRuntimeAlias } from "@ui5/webcomponents-base/dist/Runtimes.js";
 import { setPackageCSSRoot, setUseLinks } from "@ui5/webcomponents-base/dist/CSP.js";
 
+setRuntimeAlias("UI5 Web Components Playground");
+
 setUseLinks(false); // !document.adoptedStyleSheets
 setPackageCSSRoot("@ui5/webcomponents-base", "/resources/css/base/");
 setPackageCSSRoot("@ui5/webcomponents-theming", "/resources/css/theming/");

packages/main/bundle.common.js

@@ -1,7 +1,7 @@
 import { addCustomCSS, attachThemeLoaded, detachThemeLoaded } from "@ui5/webcomponents-base/dist/Theming.js";
 // import "./customI18n.js";
 
-import "./csp.js"; // import from a separate module to ensure that the code has executed before other modules are executed
+import "./bundle.common.bootstrap.js"; // code that needs to be executed before other modules
 
 // Calendars
 import "@ui5/webcomponents-localization/dist/features/calendar/Buddhist.js";