[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>
SAP · Oct 24, 2022 · 05e3013 · 05e3013
1 parent 8edc10c
commit 05e3013
Show file tree

Hide file tree

Showing 39 changed files with 2,037 additions and 2,807 deletions.
diff --git a/.eslintrc.js → .eslintrc.cjs b/.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"
  }
  }
  },

diff --git a/index.js b/index.js
diff --git a/jsdoc-plugin.cjs b/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/");
+ }
+};
diff --git a/jsdoc-plugin.js b/jsdoc-plugin.js
diff --git a/jsdoc.json b/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",

diff --git a/lib/middleware/MiddlewareManager.js b/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;
diff --git a/lib/middleware/MiddlewareUtil.js b/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;
diff --git a/lib/middleware/connectUi5Proxy.js b/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;
diff --git a/lib/middleware/csp.js b/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;
diff --git a/lib/middleware/discovery.js b/lib/middleware/discovery.js
@@ -112,4 +112,4 @@ function createMiddleware({resources}) {
  };
 }
 
-module.exports = createMiddleware;
+export default createMiddleware;
diff --git a/lib/middleware/middlewareRepository.js b/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
 };
diff --git a/lib/middleware/nonReadRequests.js b/lib/middleware/nonReadRequests.js
@@ -20,4 +20,4 @@ function createMiddleware() {
  };
 }
 
-module.exports = createMiddleware;
+export default createMiddleware;