[BREAKING] Transform to native ESM (#501)

BREAKING CHANGE:
This package has been transformed to native ESM. Therefore it no longer provides a CommonJS export.
If your project uses CommonJS, it needs to be converted to ESM or use a dynamic import.

For more information see also:
- https://sap.github.io/ui5-tooling/updates/migrate-v3/
- https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

Co-authored-by: Florian Vogt <florian.vogt@sap.com>
Co-authored-by: Yavor Ivanov <yavor.ivanov@sap.com>

.eslintrc.js → .eslintrc.cjs

@@ -1,4 +1,7 @@
 module.exports = {
+	"parserOptions": {
+		"sourceType": "module",
+	},
 	"env": {
 		"node": true,
 		"es2021": true
@@ -73,7 +76,8 @@ module.exports = {
 	"settings": {
 		"jsdoc": {
 			"tagNamePreference": {
-				"return": "returns"
+				"return": "returns",
+				"augments": "extends"
 			}
 		}
 	},

jsdoc-plugin.cjs

@@ -0,0 +1,9 @@
+/*
+ * This plugin fixes unexpected JSDoc behavior that prevents us from using types that start with an at-sign (@).
+ * JSDoc doesn't see "{@" as a valid type expression, probably as there's also {@link ...}.
+ */
+exports.handlers = {
+	jsdocCommentFound: function(e) {
+		e.comment = e.comment.replace(/{@ui5\//g, "{ @ui5/");
+	}
+};

jsdoc.json

@@ -3,12 +3,12 @@
 		"allowUnknownTags": false
 	},
 	"source": {
-		"include": ["README.md", "index.js"],
+		"include": ["README.md"],
 		"includePattern": ".+\\.js$",
 		"excludePattern": "(node_modules(\\\\|/))"
 	},
 	"plugins": [
-		"./jsdoc-plugin"
+		"./jsdoc-plugin.cjs"
 	],
 	"opts": {
 		"encoding": "utf8",

lib/middleware/MiddlewareManager.js

@@ -1,20 +1,23 @@
-const middlewareRepository = require("./middlewareRepository");
-const MiddlewareUtil = require("./MiddlewareUtil");
+import middlewareRepository from "./middlewareRepository.js";
+import MiddlewareUtil from "./MiddlewareUtil.js";
 const hasOwn = Function.prototype.call.bind(Object.prototype.hasOwnProperty);
 
 /**
- *
- * @typedef {object} middlewareResources
- * @property {module:@ui5/fs.AbstractReader} all Reader or Collection to read resources of the
+ * @private
+ * @typedef {object} MiddlewareResources
+ * @property {@ui5/fs.AbstractReader} all Reader or Collection to read resources of the
  *                                        root project and its dependencies
- * @property {module:@ui5/fs.AbstractReader} rootProject Reader or Collection to read resources of
+ * @property {@ui5/fs.AbstractReader} rootProject Reader or Collection to read resources of
  *                                        the project the server is started in
+ * @memberof @ui5/server/internal/MiddlewareManager
  */
 
 /**
+ * The MiddlewareManager
  *
- *
- * @memberof module:@ui5/server.middleware
+ * @private
+ * @class
+ * @alias @ui5/server/internal/MiddlewareManager
  */
 class MiddlewareManager {
 	constructor({graph, resources, options = {
@@ -33,6 +36,14 @@ class MiddlewareManager {
 		this.middlewareUtil = new MiddlewareUtil();
 	}
 
+	/**
+	 * Applies the middleware to
+	 *
+	 * @private
+	 * @param {object} app The express application object
+	 * @returns {Promise<Array<undefined>>} Promise resolving to an Array with a length of the number
+	 *      of added middlewares. The entries of the Array have a value of <code>undefined</code>.
+	 */
 	async applyMiddleware(app) {
 		await this.addStandardMiddleware();
 		await this.addCustomMiddleware();
@@ -43,6 +54,18 @@ class MiddlewareManager {
 		});
 	}
 
+	/**
+	 * Adds the given middleware configuration
+	 *
+	 * @private
+	 * @param {string} configuredMiddlewareName The name of the middleware
+	 * @param {object} [options] The Options of the middleware
+	 * @param {object} [options.customMiddleware] The custom middleware
+	 * @param {Function} [options.wrapperCallback] Callback called when middleware is called
+	 * @param {string} [options.mountPath="/"] The path hosting the middleware
+	 * @param {string} [options.beforeMiddleware] The name of the middleware called before the added middleware
+	 * @param {string} [options.afterMiddleware] The name of the middleware called after the added middleware
+	 */
 	async addMiddleware(configuredMiddlewareName, {
 		customMiddleware, wrapperCallback, mountPath = "/",
 		beforeMiddleware, afterMiddleware
@@ -51,7 +74,7 @@ class MiddlewareManager {
 		if (customMiddleware) {
 			middlewareCallback = customMiddleware;
 		} else {
-			const middlewareInfo = middlewareRepository.getMiddleware(configuredMiddlewareName);
+			const middlewareInfo = await middlewareRepository.getMiddleware(configuredMiddlewareName);
 			if (wrapperCallback) {
 				middlewareCallback = wrapperCallback(middlewareInfo);
 			} else {
@@ -98,6 +121,12 @@ class MiddlewareManager {
 		};
 	}
 
+	/**
+	 * Adds all registered standard middlewares
+	 *
+	 * @private
+	 * @returns {Promise} Resolving to <code>undefined</code> once all standard middlewares are added
+	 */
 	async addStandardMiddleware() {
 		await this.addMiddleware("csp", {
 			wrapperCallback: ({middleware: cspModule}) => {
@@ -214,6 +243,12 @@ class MiddlewareManager {
 		});
 	}
 
+	/**
+	 * Adds all registered custom middlewares
+	 *
+	 * @private
+	 * @returns {Promise} Resolving to <code>undefined</code> once all custom middlewares are added
+	 */
 	async addCustomMiddleware() {
 		const project = this.graph.getRoot();
 		const projectCustomMiddleware = project.getCustomMiddleware();
@@ -238,7 +273,7 @@ class MiddlewareManager {
 					`defines neither a "beforeMiddleware" nor an "afterMiddleware" parameter. One must be defined.`);
 			}
 			await this.addMiddleware(middlewareDef.name, {
-				customMiddleware: ({resources, middlewareUtil}) => {
+				customMiddleware: async ({resources, middlewareUtil}) => {
 					const customMiddleware = this.graph.getExtension(middlewareDef.name);
 					const specVersion = customMiddleware.getSpecVersion();
 					const options = {
@@ -254,7 +289,7 @@ class MiddlewareManager {
 						// Supply interface to MiddlewareUtil instance starting with specVersion 2.0
 						params.middlewareUtil = middlewareUtil.getInterface(specVersion);
 					}
-					return customMiddleware.getMiddleware()(params);
+					return (await customMiddleware.getMiddleware())(params);
 				},
 				mountPath: middlewareDef.mountPath,
 				beforeMiddleware: middlewareDef.beforeMiddleware,
@@ -264,4 +299,4 @@ class MiddlewareManager {
 	}
 }
 
-module.exports = MiddlewareManager;
+export default MiddlewareManager;

lib/middleware/MiddlewareUtil.js

@@ -1,3 +1,6 @@
+import parseurl from "parseurl";
+import mime from "mime-types";
+
 /**
  * Convenience functions for UI5 Server middleware.
  * An instance of this class is passed to every standard UI5 Server middleware.
@@ -8,7 +11,9 @@
  * version defined for the extension.
  *
  * @public
- * @memberof module:@ui5/server.middleware
+ * @class
+ * @alias @ui5/server/middleware/MiddlewareUtil
+ * @hideconstructor
  */
 class MiddlewareUtil {
 	/**
@@ -54,7 +59,6 @@ class MiddlewareUtil {
 	 * @public
 	 */
 	getPathname(req) {
-		const parseurl = require("parseurl");
 		let {pathname} = parseurl(req);
 		pathname = decodeURIComponent(pathname);
 		return pathname;
@@ -75,7 +79,7 @@ class MiddlewareUtil {
 	 * @property {string} type Detected content-type for the given resource path
 	 * @property {string} charset Default charset for the detected content-type
 	 * @property {string} contentType Calculated content-type header value
-	 * @memberof module:@ui5/server.middleware.MiddlewareUtil
+	 * @memberof @ui5/server/middleware/MiddlewareUtil
 	 */
 	/**
 	 * Returns MIME information derived from a given resource path.
@@ -84,11 +88,10 @@ class MiddlewareUtil {
 	 * <b>Specification Version 2.0 and above</b>.
 	 *
 	 * @param {object} resourcePath
-	 * @returns {module:@ui5/server.middleware.MiddlewareUtil.MimeInfo}
+	 * @returns {@ui5/server/middleware/MiddlewareUtil.MimeInfo}
 	 * @public
 	 */
 	getMimeInfo(resourcePath) {
-		const mime = require("mime-types");
 		const type = mime.lookup(resourcePath) || "application/octet-stream";
 		const charset = mime.charset(type);
 		return {
@@ -99,4 +102,4 @@ class MiddlewareUtil {
 	}
 }
 
-module.exports = MiddlewareUtil;
+export default MiddlewareUtil;

lib/middleware/connectUi5Proxy.js

@@ -1,9 +1,9 @@
-const ui5connect = require("connect-openui5");
+import ui5connect from "connect-openui5";
 
 function createMiddleware() {
 	return ui5connect.proxy({
 		secure: false
 	});
 }
 
-module.exports = createMiddleware;
+export default createMiddleware;

lib/middleware/csp.js

@@ -1,8 +1,10 @@
-const parseurl = require("parseurl");
-const Router = require("router");
-const querystring = require("querystring");
+import parseurl from "parseurl";
+import Router from "router";
+import querystring from "node:querystring";
+import logger from "@ui5/logger";
+import bodyParser from "body-parser";
 
-const log = require("@ui5/logger").getLogger("server:middleware:csp");
+const log = logger.getLogger("server:middleware:csp");
 
 const HEADER_CONTENT_SECURITY_POLICY = "Content-Security-Policy";
 const HEADER_CONTENT_SECURITY_POLICY_REPORT_ONLY = "Content-Security-Policy-Report-Only";
@@ -77,7 +79,6 @@ function createMiddleware(sCspUrlParameterName, oConfig) {
 	// .csplog
 	// body parser is required to parse csp-report in body (json)
 	if (serveCSPReports) {
-		const bodyParser = require("body-parser");
 		router.post("/.ui5/csp/report.csplog", bodyParser.json({type: "application/csp-report"}));
 	}
 	router.post("/.ui5/csp/report.csplog", function(req, res, next) {
@@ -196,4 +197,4 @@ function createMiddleware(sCspUrlParameterName, oConfig) {
 	return router;
 }
 
-module.exports = createMiddleware;
+export default createMiddleware;

lib/middleware/discovery.js

@@ -112,4 +112,4 @@ function createMiddleware({resources}) {
 	};
 }
 
-module.exports = createMiddleware;
+export default createMiddleware;

lib/middleware/middlewareRepository.js

@@ -1,34 +1,55 @@
 const middlewareInfos = {
 	compression: {path: "compression"},
 	cors: {path: "cors"},
-	csp: {path: "./csp"},
-	serveResources: {path: "./serveResources"},
-	serveIndex: {path: "./serveIndex"},
-	discovery: {path: "./discovery"},
-	versionInfo: {path: "./versionInfo"},
-	connectUi5Proxy: {path: "./connectUi5Proxy"},
-	serveThemes: {path: "./serveThemes"},
-	testRunner: {path: "./testRunner"},
-	nonReadRequests: {path: "./nonReadRequests"}
+	csp: {path: "./csp.js"},
+	serveResources: {path: "./serveResources.js"},
+	serveIndex: {path: "./serveIndex.js"},
+	discovery: {path: "./discovery.js"},
+	versionInfo: {path: "./versionInfo.js"},
+	connectUi5Proxy: {path: "./connectUi5Proxy.js"},
+	serveThemes: {path: "./serveThemes.js"},
+	testRunner: {path: "./testRunner.js"},
+	nonReadRequests: {path: "./nonReadRequests.js"}
 };
 
-function getMiddleware(middlewareName) {
+// see  @ui5/server/internal/middlewareRepository#getMiddleware
+async function getMiddleware(middlewareName) {
 	const middlewareInfo = middlewareInfos[middlewareName];
 
 	if (!middlewareInfo) {
 		throw new Error(`middlewareRepository: Unknown Middleware ${middlewareName}`);
 	}
 	try {
-		const middleware = require(middlewareInfo.path);
+		const {default: middleware} = await import(middlewareInfo.path);
 		return {
 			middleware
 		};
 	} catch (err) {
 		throw new Error(
-			`middlewareRepository: Failed to require middleware module for ${middlewareName}: ${err.message}`);
+			`middlewareRepository: Failed to require middleware module for ${middlewareName}:\n${err.stack}`);
 	}
 }
+/**
+ * @private
+ * @typedef {object} module:@ui5/server/internal/middlewareRepository~Middleware
+ * @property {object} middleware The middleware
+ */
 
-module.exports = {
+/**
+ * @private
+ * @module @ui5/server/internal/middlewareRepository
+ * @borrows getMiddleware as getMiddleware
+ */
+export default {
+
+	/**
+	 * Determines the desired middleware
+	 *
+	 * @private
+	 * @static
+	 * @function
+	 * @param {string} middlewareName The name of the middleware
+	 * @returns {module:@ui5/server/internal/middlewareRepository~Middleware} The middleware
+	 */
 	getMiddleware: getMiddleware
 };

lib/middleware/nonReadRequests.js

@@ -20,4 +20,4 @@ function createMiddleware() {
 	};
 }
 
-module.exports = createMiddleware;
+export default createMiddleware;