[FIX] Node.js API: TypeScript type definition support (#334)

Lazy-loading in the index.js breaks the automatic type definition detection from TypeScript when using the module via require. Therefore we need to manually declare the exported types. Adds a small jsdoc-plugin to remove the import() comments as JSDoc is unable to parse them.
SAP · Jul 14, 2020 · b66f9cc · b66f9cc
1 parent afde827
commit b66f9cc
Show file tree

Hide file tree

Showing 3 changed files with 95 additions and 72 deletions.
diff --git a/index.js b/index.js
@@ -2,26 +2,34 @@
  * @module @ui5/server
  * @public
  */
-const modules = {
+module.exports = {
+	/**
+	 * @type {import('./lib/server')}
+	 */
 	server: "./lib/server",
+	/**
+	 * @type {import('./lib/sslUtil')}
+	 */
 	sslUtil: "./lib/sslUtil",
+	/**
+	 * @type {import('./lib/middleware/middlewareRepository')}
+	 */
 	middlewareRepository: "./lib/middleware/middlewareRepository"
 };
 
 function exportModules(exportRoot, modulePaths) {
-	for (const moduleName in modulePaths) {
-		if (Object.prototype.hasOwnProperty.call(modulePaths, moduleName)) {
-			if (typeof modulePaths[moduleName] === "object") {
-				exportRoot[moduleName] = {};
-				exportModules(exportRoot[moduleName], modulePaths[moduleName]);
-			} else {
-				Object.defineProperty(exportRoot, moduleName, {
-					get() {
-						return require(modulePaths[moduleName]);
-					}
-				});
-			}
+	for (const moduleName of Object.keys(modulePaths)) {
+		if (typeof modulePaths[moduleName] === "object") {
+			exportRoot[moduleName] = {};
+			exportModules(exportRoot[moduleName], modulePaths[moduleName]);
+		} else {
+			Object.defineProperty(exportRoot, moduleName, {
+				get() {
+					return require(modulePaths[moduleName]);
+				}
+			});
 		}
 	}
 }
-exportModules(module.exports, modules);
+
+exportModules(module.exports, JSON.parse(JSON.stringify(module.exports)));
diff --git a/jsdoc-plugin.js b/jsdoc-plugin.js
@@ -0,0 +1,13 @@
+/*
+ * Removes JSDoc comments with TypeScript import() declarations (used in index.js)
+ */
+
+const IMPORT_PATTERN = /{(?:typeof )?import\(["'][^"']*["']\)[ .|}><,)=#\n]/;
+
+exports.handlers = {
+	jsdocCommentFound: function(e) {
+		if (IMPORT_PATTERN.test(e.comment)) {
+			e.comment = "";
+		}
+	}
+};
diff --git a/jsdoc.json b/jsdoc.json
@@ -1,60 +1,62 @@
 {
-    "tags": {
-        "allowUnknownTags": false
-    },
-    "source": {
-        "include": ["README.md", "index.js"],
-        "includePattern": ".+\\.js$",
-        "excludePattern": "(node_modules(\\\\|/))"
-    },
-    "plugins": [],
-    "opts": {
-        "template": "node_modules/docdash/",
-        "encoding": "utf8",
-        "destination": "jsdocs/",
-        "recurse": true,
-        "verbose": true,
-        "access": "public"
-    },
-    "templates": {
-        "cleverLinks": false,
-        "monospaceLinks": false,
-        "default": {
-            "useLongnameInNav": true
-        }
-    },
-    "openGraph": {
-        "title": "UI5 Tooling - API Reference",
-        "type": "website",
-        "image": "https://sap.github.io/ui5-tooling/docs/images/UI5_logo_wide.png",
-        "site_name": "UI5 Tooling - API Reference",
-        "url": "https://sap.github.io/ui5-tooling/"
-    },
-    "docdash": {
-        "sectionOrder": [
-            "Modules",
-            "Namespaces",
-            "Classes",
-            "Externals",
-            "Events",
-            "Mixins",
-            "Tutorials",
-            "Interfaces"
-        ],
-        "meta": {
-            "title": "UI5 Tooling - API Reference - UI5 Server",
-            "description": "UI5 Tooling - API Reference - UI5 Server",
-            "keyword": "openui5 sapui5 ui5 build development tool api reference"
-        },
-        "search": true,
-        "wrap": true,
-        "menu": {
-            "GitHub": {
-                "href": "https://github.com/SAP/ui5-server",
-                "target": "_blank",
-                "class": "menu-item",
-                "id": "github_link"
-            }
-        }
-    }
+	"tags": {
+		"allowUnknownTags": false
+	},
+	"source": {
+		"include": ["README.md", "index.js"],
+		"includePattern": ".+\\.js$",
+		"excludePattern": "(node_modules(\\\\|/))"
+	},
+	"plugins": [
+		"./jsdoc-plugin"
+	],
+	"opts": {
+		"template": "node_modules/docdash/",
+		"encoding": "utf8",
+		"destination": "jsdocs/",
+		"recurse": true,
+		"verbose": true,
+		"access": "public"
+	},
+	"templates": {
+		"cleverLinks": false,
+		"monospaceLinks": false,
+		"default": {
+			"useLongnameInNav": true
+		}
+	},
+	"openGraph": {
+		"title": "UI5 Tooling - API Reference",
+		"type": "website",
+		"image": "https://sap.github.io/ui5-tooling/docs/images/UI5_logo_wide.png",
+		"site_name": "UI5 Tooling - API Reference",
+		"url": "https://sap.github.io/ui5-tooling/"
+	},
+	"docdash": {
+		"sectionOrder": [
+			"Modules",
+			"Namespaces",
+			"Classes",
+			"Externals",
+			"Events",
+			"Mixins",
+			"Tutorials",
+			"Interfaces"
+		],
+		"meta": {
+			"title": "UI5 Tooling - API Reference - UI5 Server",
+			"description": "UI5 Tooling - API Reference - UI5 Server",
+			"keyword": "openui5 sapui5 ui5 build development tool api reference"
+		},
+		"search": true,
+		"wrap": true,
+		"menu": {
+			"GitHub": {
+				"href": "https://github.com/SAP/ui5-server",
+				"target": "_blank",
+				"class": "menu-item",
+				"id": "github_link"
+			}
+		}
+	}
 }