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

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 · 7858810 · 7858810
1 parent 3e37ca5
commit 7858810
Show file tree

Hide file tree

Showing 3 changed files with 199 additions and 61 deletions.
diff --git a/index.js b/index.js
@@ -2,27 +2,72 @@
  * @module @ui5/builder
  * @public
  */
-const modules = {
+module.exports = {
+	/**
+	 * @type {import('./lib/builder/builder')}
+	 */
 	builder: "./lib/builder/builder",
 	/**
 	 * @public
 	 * @alias module:@ui5/builder.processors
 	 * @namespace
 	 */
 	processors: {
+		/**
+		 * @type {import('./lib/processors/bundlers/flexChangesBundler')}
+		 */
 		flexChangesBundler: "./lib/processors/bundlers/flexChangesBundler",
+		/**
+		 * @type {import('./lib/processors/bundlers/manifestBundler')}
+		 */
 		manifestBundler: "./lib/processors/bundlers/manifestBundler",
+		/**
+		 * @type {import('./lib/processors/bundlers/moduleBundler')}
+		 */
 		moduleBundler: "./lib/processors/bundlers/moduleBundler",
+		/**
+		 * @type {import('./lib/processors/jsdoc/apiIndexGenerator')}
+		 */
 		apiIndexGenerator: "./lib/processors/jsdoc/apiIndexGenerator",
+		/**
+		 * @type {import('./lib/processors/jsdoc/jsdocGenerator')}
+		 */
 		jsdocGenerator: "./lib/processors/jsdoc/jsdocGenerator",
+		/**
+		 * @type {import('./lib/processors/jsdoc/sdkTransformer')}
+		 */
 		sdkTransformer: "./lib/processors/jsdoc/sdkTransformer",
+		/**
+		 * @type {import('./lib/processors/bootstrapHtmlTransformer')}
+		 */
 		bootstrapHtmlTransformer: "./lib/processors/bootstrapHtmlTransformer",
+		/**
+		 * @type {import('./lib/processors/debugFileCreator')}
+		 */
 		debugFileCreator: "./lib/processors/debugFileCreator",
+		/**
+		 * @type {import('./lib/processors/resourceCopier')}
+		 */
 		resourceCopier: "./lib/processors/resourceCopier",
+		/**
+		 * @type {import('./lib/processors/nonAsciiEscaper')}
+		 */
 		nonAsciiEscaper: "./lib/processors/nonAsciiEscaper",
+		/**
+		 * @type {import('./lib/processors/stringReplacer')}
+		 */
 		stringReplacer: "./lib/processors/stringReplacer",
+		/**
+		 * @type {import('./lib/processors/themeBuilder')}
+		 */
 		themeBuilder: "./lib/processors/themeBuilder",
+		/**
+		 * @type {import('./lib/processors/uglifier')}
+		 */
 		uglifier: "./lib/processors/uglifier",
+		/**
+		 * @type {import('./lib/processors/versionInfoGenerator')}
+		 */
 		versionInfoGenerator: "./lib/processors/versionInfoGenerator"
 	},
 	/**
@@ -31,24 +76,81 @@ const modules = {
 	 * @namespace
 	 */
 	tasks: {
+		/**
+		 * @type {import('./lib/tasks/bundlers/generateComponentPreload')}
+		 */
 		generateComponentPreload: "./lib/tasks/bundlers/generateComponentPreload",
+		/**
+		 * @type {import('./lib/tasks/bundlers/generateFlexChangesBundle')}
+		 */
 		generateFlexChangesBundle: "./lib/tasks/bundlers/generateFlexChangesBundle",
+		/**
+		 * @type {import('./lib/tasks/bundlers/generateLibraryPreload')}
+		 */
 		generateLibraryPreload: "./lib/tasks/bundlers/generateLibraryPreload",
+		/**
+		 * @type {import('./lib/tasks/bundlers/generateManifestBundle')}
+		 */
 		generateManifestBundle: "./lib/tasks/bundlers/generateManifestBundle",
+		/**
+		 * @type {import('./lib/tasks/bundlers/generateStandaloneAppBundle')}
+		 */
 		generateStandaloneAppBundle: "./lib/tasks/bundlers/generateStandaloneAppBundle",
+		/**
+		 * @type {import('./lib/tasks/bundlers/generateBundle')}
+		 */
 		generateBundle: "./lib/tasks/bundlers/generateBundle",
+		/**
+		 * @type {import('./lib/tasks/generateCachebusterInfo')}
+		 */
 		generateCachebusterInfo: "./lib/tasks/generateCachebusterInfo",
+		/**
+		 * @type {import('./lib/tasks/buildThemes')}
+		 */
 		buildThemes: "./lib/tasks/buildThemes",
+		/**
+		 * @type {import('./lib/tasks/createDebugFiles')}
+		 */
 		createDebugFiles: "./lib/tasks/createDebugFiles",
+		/**
+		 * @type {import('./lib/tasks/jsdoc/executeJsdocSdkTransformation')}
+		 */
 		executeJsdocSdkTransformation: "./lib/tasks/jsdoc/executeJsdocSdkTransformation",
+		/**
+		 * @type {import('./lib/tasks/jsdoc/generateApiIndex')}
+		 */
 		generateApiIndex: "./lib/tasks/jsdoc/generateApiIndex",
+		/**
+		 * @type {import('./lib/tasks/jsdoc/generateJsdoc')}
+		 */
 		generateJsdoc: "./lib/tasks/jsdoc/generateJsdoc",
+		/**
+		 * @type {import('./lib/tasks/generateVersionInfo')}
+		 */
 		generateVersionInfo: "./lib/tasks/generateVersionInfo",
+		/**
+		 * @type {import('./lib/tasks/escapeNonAsciiCharacters')}
+		 */
 		escapeNonAsciiCharacters: "./lib/tasks/escapeNonAsciiCharacters",
+		/**
+		 * @type {import('./lib/tasks/replaceCopyright')}
+		 */
 		replaceCopyright: "./lib/tasks/replaceCopyright",
+		/**
+		 * @type {import('./lib/tasks/replaceVersion')}
+		 */
 		replaceVersion: "./lib/tasks/replaceVersion",
+		/**
+		 * @type {import('./lib/tasks/transformBootstrapHtml')}
+		 */
 		transformBootstrapHtml: "./lib/tasks/transformBootstrapHtml",
+		/**
+		 * @type {import('./lib/tasks/uglify')}
+		 */
 		uglify: "./lib/tasks/uglify",
+		/**
+		 * @type {import('./lib/tasks/taskRepository')}
+		 */
 		taskRepository: "./lib/tasks/taskRepository"
 	},
 	/**
@@ -57,12 +159,33 @@ const modules = {
 	 * @namespace
 	 */
 	types: {
+		/**
+		 * @type {typeof import('./lib/types/AbstractBuilder')}
+		 */
 		AbstractBuilder: "./lib/types/AbstractBuilder",
+		/**
+		 * @type {typeof import('./lib/types/AbstractFormatter')}
+		 */
 		AbstractFormatter: "./lib/types/AbstractFormatter",
+		/**
+		 * @type {import('./lib/types/application/applicationType')}
+		 */
 		application: "./lib/types/application/applicationType",
+		/**
+		 * @type {import('./lib/types/library/libraryType')}
+		 */
 		library: "./lib/types/library/libraryType",
+		/**
+		 * @type {import('./lib/types/themeLibrary/themeLibraryType')}
+		 */
 		themeLibrary: "./lib/types/themeLibrary/themeLibraryType",
+		/**
+		 * @type {import('./lib/types/module/moduleType')}
+		 */
 		module: "./lib/types/module/moduleType",
+		/**
+		 * @type {import('./lib/types/typeRepository')}
+		 */
 		typeRepository: "./lib/types/typeRepository"
 	}
 };
@@ -82,4 +205,4 @@ function exportModules(exportRoot, modulePaths) {
 	}
 }
 
-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,61 +1,63 @@
 {
-    "tags": {
-        "allowUnknownTags": false
-    },
-    "source": {
-        "include": ["README.md", "index.js"],
-        "exclude": ["lib/lbt/utils/JSTokenizer.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 Builder",
-            "description": "UI5 Tooling - API Reference - UI5 Builder",
-            "keyword": "openui5 sapui5 ui5 build development tool api reference"
-        },
-        "search": true,
-        "wrap": true,
-        "menu": {
-            "GitHub": {
-                "href": "https://github.com/SAP/ui5-builder",
-                "target": "_blank",
-                "class": "menu-item",
-                "id": "github_link"
-            }
-        }
-    }
+	"tags": {
+		"allowUnknownTags": false
+	},
+	"source": {
+		"include": ["README.md", "index.js"],
+		"exclude": ["lib/lbt/utils/JSTokenizer.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 Builder",
+			"description": "UI5 Tooling - API Reference - UI5 Builder",
+			"keyword": "openui5 sapui5 ui5 build development tool api reference"
+		},
+		"search": true,
+		"wrap": true,
+		"menu": {
+			"GitHub": {
+				"href": "https://github.com/SAP/ui5-builder",
+				"target": "_blank",
+				"class": "menu-item",
+				"id": "github_link"
+			}
+		}
+	}
 }