@ui5/builder 3.0.0-rc.3 → 3.0.0-rc.4

package/CHANGELOG.md

@@ -2,7 +2,13 @@
 All notable changes to this project will be documented in this file.  
 This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
-A list of unreleased changes can be found [here](https://github.com/SAP/ui5-builder/compare/v3.0.0-rc.3...HEAD).
+A list of unreleased changes can be found [here](https://github.com/SAP/ui5-builder/compare/v3.0.0-rc.4...HEAD).
+
+<a name="v3.0.0-rc.4"></a>
+## [v3.0.0-rc.4] - 2023-02-03
+### Features
+- **minify task:** Use workerpool for terser ([#875](https://github.com/SAP/ui5-builder/issues/875)) [`ff4c6fb`](https://github.com/SAP/ui5-builder/commit/ff4c6fbd81c912239cd578fdcd452364ac4ae859)
+
 
 <a name="v3.0.0-rc.3"></a>
 ## [v3.0.0-rc.3] - 2023-01-24
@@ -846,6 +852,7 @@ to load the custom bundle file instead.
 - Add ability to configure component preloads and custom bundles [`2241e5f`](https://github.com/SAP/ui5-builder/commit/2241e5ff98fd95f1f80cc74959655ae7a9c660e7)
 
 
+[v3.0.0-rc.4]: https://github.com/SAP/ui5-builder/compare/v3.0.0-rc.3...v3.0.0-rc.4
 [v3.0.0-rc.3]: https://github.com/SAP/ui5-builder/compare/v3.0.0-rc.2...v3.0.0-rc.3
 [v3.0.0-rc.2]: https://github.com/SAP/ui5-builder/compare/v3.0.0-rc.1...v3.0.0-rc.2
 [v3.0.0-rc.1]: https://github.com/SAP/ui5-builder/compare/v3.0.0-rc.0...v3.0.0-rc.1

package/lib/processors/jsdoc/lib/createIndexFiles.cjs

@@ -1,7 +1,7 @@
 /*
  * Node script to create cross-library API index files for use in the UI5 SDKs.
  *
- * (c) Copyright 2009-2022 SAP SE or an SAP affiliate company.
+ * (c) Copyright 2009-2023 SAP SE or an SAP affiliate company.
  * Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
  */
 

package/lib/processors/jsdoc/lib/transformApiJson.cjs

@@ -1,7 +1,7 @@
 /*
  * Node script to preprocess api.json files for use in the UI5 SDKs.
  *
- * (c) Copyright 2009-2022 SAP SE or an SAP affiliate company.
+ * (c) Copyright 2009-2023 SAP SE or an SAP affiliate company.
  * Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
  */
 

package/lib/processors/jsdoc/lib/ui5/plugin.cjs

@@ -1,7 +1,7 @@
 /*
  * JSDoc3 plugin for UI5 documentation generation.
  *
- * (c) Copyright 2009-2022 SAP SE or an SAP affiliate company.
+ * (c) Copyright 2009-2023 SAP SE or an SAP affiliate company.
  * Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
  */
 
@@ -21,12 +21,18 @@
  *   experimental
  *
  *   final
+ * 
+ *   hideconstructor
  *
  *   interface
  *
  *   implements
  *
+ *   ui5-omissible-param
  *
+ *   ui5-restricted
+ *
+ * 
  *
  * It furthermore listens to the following JSDoc3 events to implement additional functionality
  *
@@ -2594,6 +2600,13 @@ exports.defineTags = function(dictionary) {
 			}
 		}
 	});
+	dictionary.defineTag('ui5-omissible-params', {
+		onTagged: function(doclet, tag) {
+			if ( tag.value ) {
+				ui5data(doclet).omissibleParams = tag.value.trim().split(/\s*,\s*/);
+			}
+		}
+	});
 
 	/**
 	 * Mark a doclet as synthetic.
@@ -3151,13 +3164,19 @@ exports.astNodeVisitor = {
 					typeString += `(${paramTypes.join(", ")})`;
 				}
 				if (parsedType.result) {
-					typeString += `:${toTypeString(parsedType.result)}`;
+					let resultType = toTypeString(parsedType.result);
+					// ensure the function result remains belonging together even when a union of the entire function with other types is created
+					// Example: ensure parentheses around function result in:  function(int):({rows: int, columns: int}|null)|undefined
+					if (parsedType.result.type === "TypeUnion") {
+						resultType = `(${resultType})`;
+					}
+					typeString += `:${resultType}`;
 				}
 				types.push(typeString);
 				// #### END: MODIFIED BY SAP
 				break;
 			 case TYPES.NameExpression:
-				 types.push(parsedType.name);
+				types.push(parsedType.name);
 				break;
 			case TYPES.NullLiteral:
 				types.push('null');

package/lib/processors/jsdoc/lib/ui5/template/publish.cjs

@@ -1,7 +1,7 @@
 /*
  * JSDoc3 template for UI5 documentation generation.
  *
- * (c) Copyright 2009-2022 SAP SE or an SAP affiliate company.
+ * (c) Copyright 2009-2023 SAP SE or an SAP affiliate company.
  * Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
  */
 
@@ -2856,6 +2856,7 @@ function createAPIJSON4Symbol(symbol, omitDefaults) {
 			}
 		}
 
+		const omissibleParams = new Set(member.__ui5 && member.__ui5.omissibleParams);
 		if ( member.params && member.params.length > 0 ) {
 			collection("parameters");
 			for ( let j = 0; j < member.params.length; j++) {
@@ -2867,6 +2868,13 @@ function createAPIJSON4Symbol(symbol, omitDefaults) {
 				attrib("name", param.name);
 				attrib("type", listTypes(param.type));
 				attrib("optional", !!param.optional, false, /* raw = */true);
+				if ( omissibleParams.has(param.name) ) {
+					if ( !param.optional ) {
+						throw new Error(`@param ${param.name} is specified in '@ui5-omissible-params' for '${member.name}', but not marked as optional. Only optional params can be omissible.`);
+					}
+					attrib("omissible", true, false, /* raw = */true);
+					omissibleParams.delete(param.name);
+				}
 				if ( param.variable ) {
 					attrib("repeatable", !!param.variable, false, /* raw = */true);
 				}
@@ -2882,6 +2890,9 @@ function createAPIJSON4Symbol(symbol, omitDefaults) {
 			}
 			endCollection("parameters");
 		}
+		if ( omissibleParams.size > 0 ) {
+			throw new Error(`parameter(s) '${[...omissibleParams].join("' and '")}' specified as '@ui5-omissible-params' for '${member.name}' missing among the actual @params`);
+		} 
 
 		exceptions(member);
 

package/lib/processors/minifier.js

@@ -1,21 +1,43 @@
+import {fileURLToPath} from "node:url";
 import posixPath from "node:path/posix";
-import {minify} from "terser";
+import os from "node:os";
+import workerpool from "workerpool";
 import Resource from "@ui5/fs/Resource";
+import {getLogger} from "@ui5/logger";
+const log = getLogger("builder:processors:minifier");
 
-/**
- * Preserve comments which contain:
- * <ul>
- *  <li>copyright notice</li>
- *  <li>license terms</li>
- *  <li>"@ui5-bundle"</li>
- *  <li>"@ui5-bundle-raw-include"</li>
- * </ul>
- *
- * @type {RegExp}
- */
-const copyrightCommentsAndBundleCommentPattern = /copyright|\(c\)(?:[0-9]+|\s+[0-9A-Za-z])|released under|license|\u00a9|^@ui5-bundle-raw-include |^@ui5-bundle /i;
 const debugFileRegex = /((?:\.view|\.fragment|\.controller|\.designtime|\.support)?\.js)$/;
 
+const MIN_WORKERS = 2;
+const MAX_WORKERS = 4;
+const osCpus = os.cpus().length || 1;
+const maxWorkers = Math.max(Math.min(osCpus - 1, MAX_WORKERS), MIN_WORKERS);
+
+// Shared workerpool across all executions until the taskUtil cleanup is triggered
+let pool;
+
+function getPool(taskUtil) {
+	if (!pool) {
+		log.verbose(`Creating workerpool with up to ${maxWorkers} workers (available CPU cores: ${osCpus})`);
+		const workerPath = fileURLToPath(new URL("./minifierWorker.js", import.meta.url));
+		pool = workerpool.pool(workerPath, {
+			workerType: "auto",
+			maxWorkers
+		});
+		taskUtil.registerCleanupTask(() => {
+			log.verbose(`Terminating workerpool`);
+			const poolToBeTerminated = pool;
+			pool = null;
+			poolToBeTerminated.terminate();
+		});
+	}
+	return pool;
+}
+
+async function minifyInWorker(options, taskUtil) {
+	return getPool(taskUtil).exec("execMinification", [options]);
+}
+
 /**
  * @public
  * @module @ui5/builder/processors/minifier
@@ -40,13 +62,29 @@ const debugFileRegex = /((?:\.view|\.fragment|\.controller|\.designtime|\.suppor
  *
  * @param {object} parameters Parameters
  * @param {@ui5/fs/Resource[]} parameters.resources List of resources to be processed
+ * @param {@ui5/builder/tasks/TaskUtil|object} [parameters.taskUtil] TaskUtil instance.
+ *    Required when using the <code>useWorkers</code> option
  * @param {object} [parameters.options] Options
  * @param {boolean} [parameters.options.addSourceMappingUrl=true]
- * 				Whether to add a sourceMappingURL reference to the end of the minified resource
+ *   Whether to add a sourceMappingURL reference to the end of the minified resource
+ * @param {boolean} [parameters.options.useWorkers=false]
+ *  Whether to offload the minification task onto separate CPU threads. This often speeds up the build process
  * @returns {Promise<module:@ui5/builder/processors/minifier~MinifierResult[]>}
- * 				Promise resolving with object of resource, dbgResource and sourceMap
+ *   Promise resolving with object of resource, dbgResource and sourceMap
  */
-export default async function({resources, options: {addSourceMappingUrl = true} = {}}) {
+export default async function({resources, taskUtil, options: {addSourceMappingUrl = true, useWorkers = false} = {}}) {
+	let minify;
+	if (useWorkers) {
+		if (!taskUtil) {
+			// TaskUtil is required for worker support
+			throw new Error(`Minifier: Option 'useWorkers' requires a taskUtil instance to be provided`);
+		}
+		minify = minifyInWorker;
+	} else {
+		// Do not use workerpool
+		minify = (await import("./minifierWorker.js")).default;
+	}
+
 	return Promise.all(resources.map(async (resource) => {
 		const dbgPath = resource.getPath().replace(debugFileRegex, "-dbg$1");
 		const dbgResource = await resource.clone();
@@ -54,43 +92,26 @@ export default async function({resources, options: {addSourceMappingUrl = true}
 
 		const filename = posixPath.basename(resource.getPath());
 		const code = await resource.getString();
-		try {
-			const sourceMapOptions = {
-				filename
-			};
-			if (addSourceMappingUrl) {
-				sourceMapOptions.url = filename + ".map";
-			}
-			const dbgFilename = posixPath.basename(dbgPath);
-			const result = await minify({
-				// Use debug-name since this will be referenced in the source map "sources"
-				[dbgFilename]: code
-			}, {
-				output: {
-					comments: copyrightCommentsAndBundleCommentPattern,
-					wrap_func_args: false
-				},
-				compress: false,
-				mangle: {
-					reserved: [
-						"jQuery",
-						"jquery",
-						"sap",
-					]
-				},
-				sourceMap: sourceMapOptions
-			});
-			resource.setString(result.code);
-			const sourceMapResource = new Resource({
-				path: resource.getPath() + ".map",
-				string: result.map
-			});
-			return {resource, dbgResource, sourceMapResource};
-		} catch (err) {
-			// Note: err.filename contains the debug-name
-			throw new Error(
-				`Minification failed with error: ${err.message} in file ${filename} ` +
-				`(line ${err.line}, col ${err.col}, pos ${err.pos})`);
+
+		const sourceMapOptions = {
+			filename
+		};
+		if (addSourceMappingUrl) {
+			sourceMapOptions.url = filename + ".map";
 		}
+		const dbgFilename = posixPath.basename(dbgPath);
+
+		const result = await minify({
+			filename,
+			dbgFilename,
+			code,
+			sourceMapOptions
+		}, taskUtil);
+		resource.setString(result.code);
+		const sourceMapResource = new Resource({
+			path: resource.getPath() + ".map",
+			string: result.map
+		});
+		return {resource, dbgResource, sourceMapResource};
 	}));
 }

package/lib/processors/minifierWorker.js

@@ -0,0 +1,77 @@
+import workerpool from "workerpool";
+import {minify} from "terser";
+
+/**
+ * @private
+ * @module @ui5/builder/tasks/minifyWorker
+ */
+
+/**
+ * Preserve comments which contain:
+ * <ul>
+ *  <li>copyright notice</li>
+ *  <li>license terms</li>
+ *  <li>"@ui5-bundle"</li>
+ *  <li>"@ui5-bundle-raw-include"</li>
+ * </ul>
+ *
+ * @type {RegExp}
+ */
+const copyrightCommentsAndBundleCommentPattern = /copyright|\(c\)(?:[0-9]+|\s+[0-9A-Za-z])|released under|license|\u00a9|^@ui5-bundle-raw-include |^@ui5-bundle /i;
+
+/**
+ * Task to minify resources.
+ *
+ * @private
+ * @function default
+ * @static
+ *
+ * @param {object} parameters Parameters
+ * @param {string} parameters.filename
+ * @param {string} parameters.dbgFilename
+ * @param {string} parameters.code
+ * @param {object} parameters.sourceMapOptions
+ * @returns {Promise<undefined>} Promise resolving once minification of the resource has finished
+ */
+export default async function execMinification({
+	filename,
+	dbgFilename,
+	code,
+	sourceMapOptions
+}) {
+	try {
+		return await minify({
+			// Use debug-name since this will be referenced in the source map "sources"
+			[dbgFilename]: code
+		}, {
+			output: {
+				comments: copyrightCommentsAndBundleCommentPattern,
+				wrap_func_args: false
+			},
+			compress: false,
+			mangle: {
+				reserved: [
+					"jQuery",
+					"jquery",
+					"sap",
+				]
+			},
+			sourceMap: sourceMapOptions
+		});
+	} catch (err) {
+		// Note: err.filename contains the debug-name
+		throw new Error(
+			`Minification failed with error: ${err.message} in file ${filename} ` +
+			`(line ${err.line}, col ${err.col}, pos ${err.pos})`);
+	}
+}
+
+// Test execution via ava is never done on the main thread
+/* istanbul ignore else */
+if (!workerpool.isMainThread) {
+	// Script got loaded through workerpool
+	// => Create a worker and register public functions
+	workerpool.worker({
+		execMinification
+	});
+}

package/lib/tasks/minify.js

@@ -25,8 +25,10 @@ export default async function({workspace, taskUtil, options: {pattern, omitSourc
 	const resources = await workspace.byGlob(pattern);
 	const processedResources = await minifier({
 		resources,
+		taskUtil,
 		options: {
-			addSourceMappingUrl: !omitSourceMapResources
+			addSourceMappingUrl: !omitSourceMapResources,
+			useWorkers: !!taskUtil,
 		}
 	});
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ui5/builder",
-	"version": "3.0.0-rc.3",
+	"version": "3.0.0-rc.4",
 	"description": "UI5 Tooling - Builder",
 	"author": {
 		"name": "SAP SE",
@@ -28,7 +28,7 @@
 		"./internal/jsdoc/template/publish": "./lib/processors/jsdoc/lib/ui5/template/publish.cjs"
 	},
 	"engines": {
-		"node": "^16.18.0 || >=18.0.0",
+		"node": "^16.18.0 || >=18.12.0",
 		"npm": ">= 8"
 	},
 	"scripts": {
@@ -118,8 +118,8 @@
 	},
 	"dependencies": {
 		"@jridgewell/sourcemap-codec": "^1.4.14",
-		"@ui5/fs": "^3.0.0-rc.4",
-		"@ui5/logger": "^3.0.1-rc.2",
+		"@ui5/fs": "^3.0.0-rc.5",
+		"@ui5/logger": "^3.0.1-rc.3",
 		"cheerio": "1.0.0-rc.12",
 		"escape-unicode": "^0.2.0",
 		"escope": "^4.0.0",
@@ -128,14 +128,15 @@
 		"jsdoc": "^3.6.11",
 		"less-openui5": "^0.11.6",
 		"pretty-data": "^0.40.0",
-		"rimraf": "^4.1.1",
+		"rimraf": "^4.1.2",
 		"semver": "^7.3.8",
 		"terser": "^5.16.1",
+		"workerpool": "^6.3.1",
 		"xml2js": "^0.4.23"
 	},
 	"devDependencies": {
 		"@istanbuljs/esm-loader-hook": "^0.2.0",
-		"@ui5/project": "^3.0.0-rc.6",
+		"@ui5/project": "^3.0.0-rc.7",
 		"ava": "^5.1.1",
 		"chai": "^4.3.7",
 		"chai-fs": "^2.0.0",
@@ -143,10 +144,10 @@
 		"cross-env": "^7.0.3",
 		"depcheck": "^1.4.3",
 		"docdash": "^2.0.1",
-		"eslint": "^8.32.0",
+		"eslint": "^8.33.0",
 		"eslint-config-google": "^0.14.0",
 		"eslint-plugin-ava": "^14.0.0",
-		"eslint-plugin-jsdoc": "^39.6.7",
+		"eslint-plugin-jsdoc": "^39.7.4",
 		"esmock": "^2.1.0",
 		"nyc": "^15.1.0",
 		"open-cli": "^7.1.0",