refactor(types): add initial types to CommonJsExportsParserPlugin

TheLarkInn · TheLarkInn · commit 4a1b8cefb982 · 2023-04-23T05:35:52.000Z
diff --git a/lib/dependencies/CommonJsDependencyHelpers.js b/lib/dependencies/CommonJsDependencyHelpers.js
@@ -7,6 +7,15 @@
 
 const RuntimeGlobals = require("../RuntimeGlobals");
 
+/** @typedef {import("../Module")} Module */
+/** @typedef {"exports" | "module.exports" | "this" | "Object.defineProperty(exports)" | "Object.defineProperty(module.exports)" | "Object.defineProperty(this)"} CommonJSDependencyBaseKeywords */
+
+/**
+ * @param {CommonJSDependencyBaseKeywords} depBase commonjs dependency base
+ * @param {Module} module module
+ * @param {Set<string>} runtimeRequirements runtime requirements
+ * @returns {[string, string]} type and base
+ */
 exports.handleDependencyBase = (depBase, module, runtimeRequirements) => {
 	let base = undefined;
 	let type;
diff --git a/lib/dependencies/CommonJsExportsParserPlugin.js b/lib/dependencies/CommonJsExportsParserPlugin.js
@@ -16,11 +16,21 @@ const DynamicExports = require("./DynamicExports");
 const HarmonyExports = require("./HarmonyExports");
 const ModuleDecoratorDependency = require("./ModuleDecoratorDependency");
 
+/** @typedef {import("estree").Super} Super */
+/** @typedef {import("estree").CallExpression} CallExpression */
 /** @typedef {import("estree").Expression} ExpressionNode */
+/** @typedef {import("estree").Expression} Expression */
+/** @typedef {import("estree").AssignmentExpression} AssignmentExpression */
+
 /** @typedef {import("../NormalModule")} NormalModule */
 /** @typedef {import("../javascript/BasicEvaluatedExpression")} BasicEvaluatedExpression */
 /** @typedef {import("../javascript/JavascriptParser")} JavascriptParser */
+/** @typedef {import("./CommonJsDependencyHelpers").CommonJSDependencyBaseKeywords} CommonJSDependencyBaseKeywords */
 
+/**
+ * @param {TODO} expr expression
+ * @returns {Expression} returns the value of property descriptor
+ */
 const getValueOfPropertyDescription = expr => {
 	if (expr.type !== "ObjectExpression") return;
 	for (const property of expr.properties) {
@@ -31,6 +41,15 @@ const getValueOfPropertyDescription = expr => {
 	}
 };
 
+/**
+ * The purpose of this function is to check whether an expression is a truthy literal or not. This is
+ * useful when parsing CommonJS exports, because CommonJS modules can export any value, including falsy
+ * values like `null` and `false`. However, exports should only be created if the exported value is truthy.
+ *
+ * @param {Expression} expr expression being checked
+ * @returns {boolean} true, when the expression is a truthy literal
+ *
+ */
 const isTruthyLiteral = expr => {
 	switch (expr.type) {
 		case "Literal":
@@ -41,6 +60,14 @@ const isTruthyLiteral = expr => {
 	return false;
 };
 
+/**
+ * The purpose of this function is to check whether an expression is a falsy literal or not. This is
+ * useful when parsing CommonJS exports, because CommonJS modules can export any value, including falsy
+ * values like `null` and `false`. However, exports should only be created if the exported value is truthy.
+ *
+ * @param {Expression} expr expression being checked
+ * @returns {boolean} true, when the expression is a falsy literal
+ */
 const isFalsyLiteral = expr => {
 	switch (expr.type) {
 		case "Literal":
@@ -97,6 +124,13 @@ class CommonJsExportsParserPlugin {
 		const enableStructuredExports = () => {
 			DynamicExports.enable(parser.state);
 		};
+
+		/**
+		 * @param {boolean} topLevel true, when the export is on top level
+		 * @param {string[]} members members of the export
+		 * @param {Expression} valueExpr expression for the value
+		 * @returns {void}
+		 */
 		const checkNamespace = (topLevel, members, valueExpr) => {
 			if (!DynamicExports.isEnabled(parser.state)) return;
 			if (members.length > 0 && members[0] === "__esModule") {
@@ -126,6 +160,13 @@ class CommonJsExportsParserPlugin {
 			.tap("CommonJsPlugin", evaluateToString("object"));
 
 		// exporting //
+
+		/**
+		 * @param {AssignmentExpression} expr expression
+		 * @param {CommonJSDependencyBaseKeywords} base commonjs base keywords
+		 * @param {string[]} members members of the export
+		 * @returns {boolean} true, when the expression was handled
+		 */
 		const handleAssignExport = (expr, base, members) => {
 			if (HarmonyExports.isEnabled(parser.state)) return;
 			// Handle reexporting
@@ -233,6 +274,14 @@ class CommonJsExportsParserPlugin {
 			});
 
 		// Self reference //
+
+		/**
+		 * @param { Expression | Super} expr expression
+		 * @param {CommonJSDependencyBaseKeywords} base commonjs base keywords
+		 * @param {string[]} members members of the export
+		 * @param {CallExpression} call call expression
+		 * @returns {boolean} true, when the expression was handled
+		 */
 		const handleAccessExport = (expr, base, members, call = undefined) => {
 			if (HarmonyExports.isEnabled(parser.state)) return;
 			if (members.length === 0) {
