Merge pull request #17096 from webpack/thelarkinn/types-bee

refactor(types): Increase type coverage & docs for BasicEvaluatedExpression

lib/dependencies/HarmonyImportDependencyParserPlugin.js

@@ -159,6 +159,7 @@ module.exports = class HarmonyImportDependencyParserPlugin {
 
 				const rootInfo = rightPart.rootInfo;
 				if (
+					typeof rootInfo === "string" ||
 					!rootInfo ||
 					!rootInfo.tagInfo ||
 					rootInfo.tagInfo.tag !== harmonySpecifierTag

lib/javascript/BasicEvaluatedExpression.js

@@ -60,10 +60,11 @@ class BasicEvaluatedExpression {
 		this.prefix = undefined;
 		/** @type {BasicEvaluatedExpression | undefined} */
 		this.postfix = undefined;
+		/** @type {BasicEvaluatedExpression[]} */
 		this.wrappedInnerExpressions = undefined;
 		/** @type {string | VariableInfoInterface | undefined} */
 		this.identifier = undefined;
-		/** @type {VariableInfoInterface} */
+		/** @type {string | VariableInfoInterface} */
 		this.rootInfo = undefined;
 		/** @type {() => string[]} */
 		this.getMembers = undefined;
@@ -275,6 +276,10 @@ class BasicEvaluatedExpression {
 		return undefined;
 	}
 
+	/**
+	 * Creates a string representation of this evaluated expression.
+	 * @returns {string | undefined} the string representation or undefined if not possible
+	 */
 	asString() {
 		if (this.isBoolean()) return `${this.bool}`;
 		if (this.isNull()) return "null";
@@ -324,34 +329,63 @@ class BasicEvaluatedExpression {
 		return this;
 	}
 
+	/**
+	 * Set's the value of this expression to a number
+	 * @param {number} number number to set
+	 * @returns {this} this
+	 */
 	setNumber(number) {
 		this.type = TypeNumber;
 		this.number = number;
 		this.sideEffects = false;
 		return this;
 	}
 
+	/**
+	 * Set's the value of this expression to a BigInt
+	 * @param {bigint} bigint bigint to set
+	 * @returns {this} this
+	 */
 	setBigInt(bigint) {
 		this.type = TypeBigInt;
 		this.bigint = bigint;
 		this.sideEffects = false;
 		return this;
 	}
 
+	/**
+	 * Set's the value of this expression to a boolean
+	 * @param {boolean} bool boolean to set
+	 * @returns {this} this
+	 */
 	setBoolean(bool) {
 		this.type = TypeBoolean;
 		this.bool = bool;
 		this.sideEffects = false;
 		return this;
 	}
 
+	/**
+	 * Set's the value of this expression to a regular expression
+	 * @param {RegExp} regExp regular expression to set
+	 * @returns {this} this
+	 */
 	setRegExp(regExp) {
 		this.type = TypeRegExp;
 		this.regExp = regExp;
 		this.sideEffects = false;
 		return this;
 	}
 
+	/**
+	 * Set's the value of this expression to a particular identifier and its members.
+	 *
+	 * @param {string | VariableInfoInterface} identifier identifier to set
+	 * @param {string | VariableInfoInterface} rootInfo root info
+	 * @param {() => string[]} getMembers members
+	 * @param {() => boolean[]=} getMembersOptionals optional members
+	 * @returns {this} this
+	 */
 	setIdentifier(identifier, rootInfo, getMembers, getMembersOptionals) {
 		this.type = TypeIdentifier;
 		this.identifier = identifier;
@@ -362,6 +396,14 @@ class BasicEvaluatedExpression {
 		return this;
 	}
 
+	/**
+	 * Wraps an array of expressions with a prefix and postfix expression.
+	 *
+	 * @param {BasicEvaluatedExpression | null} prefix Expression to be added before the innerExpressions
+	 * @param {BasicEvaluatedExpression} postfix Expression to be added after the innerExpressions
+	 * @param {BasicEvaluatedExpression[]} innerExpressions Expressions to be wrapped
+	 * @returns {this} this
+	 */
 	setWrapped(prefix, postfix, innerExpressions) {
 		this.type = TypeWrapped;
 		this.prefix = prefix;
@@ -371,13 +413,25 @@ class BasicEvaluatedExpression {
 		return this;
 	}
 
+	/**
+	 * Stores the options of a conditional expression.
+	 *
+	 * @param {BasicEvaluatedExpression[]} options optional (consequent/alternate) expressions to be set
+	 * @returns {this} this
+	 */
 	setOptions(options) {
 		this.type = TypeConditional;
 		this.options = options;
 		this.sideEffects = true;
 		return this;
 	}
 
+	/**
+	 * Adds options to a conditional expression.
+	 *
+	 * @param {BasicEvaluatedExpression[]} options optional (consequent/alternate) expressions to be added
+	 * @returns {this} this
+	 */
 	addOptions(options) {
 		if (!this.options) {
 			this.type = TypeConditional;
@@ -390,20 +444,41 @@ class BasicEvaluatedExpression {
 		return this;
 	}
 
+	/**
+	 * Set's the value of this expression to an array of expressions.
+	 *
+	 * @param {BasicEvaluatedExpression[]} items expressions to set
+	 * @returns {this} this
+	 */
 	setItems(items) {
 		this.type = TypeArray;
 		this.items = items;
 		this.sideEffects = items.some(i => i.couldHaveSideEffects());
 		return this;
 	}
 
+	/**
+	 * Set's the value of this expression to an array of strings.
+	 *
+	 * @param {string[]} array array to set
+	 * @returns {this} this
+	 */
 	setArray(array) {
 		this.type = TypeConstArray;
 		this.array = array;
 		this.sideEffects = false;
 		return this;
 	}
 
+	/**
+	 * Set's the value of this expression to a processed/unprocessed template string. Used
+	 * for evaluating TemplateLiteral expressions in the JavaScript Parser.
+	 *
+	 * @param {BasicEvaluatedExpression[]} quasis template string quasis
+	 * @param {BasicEvaluatedExpression[]} parts template string parts
+	 * @param {"cooked" | "raw"} kind template string kind
+	 * @returns {this} this
+	 */
 	setTemplateString(quasis, parts, kind) {
 		this.type = TypeTemplateString;
 		this.quasis = quasis;
@@ -426,6 +501,12 @@ class BasicEvaluatedExpression {
 		return this;
 	}
 
+	/**
+	 * Set's the value of the expression to nullish.
+	 *
+	 * @param {boolean} value true, if the expression is nullish
+	 * @returns {this} this
+	 */
 	setNullish(value) {
 		this.nullish = value;
 
@@ -434,16 +515,34 @@ class BasicEvaluatedExpression {
 		return this;
 	}
 
+	/**
+	 * Set's the range for the expression.
+	 *
+	 * @param {[number, number]} range range to set
+	 * @returns {this} this
+	 */
 	setRange(range) {
 		this.range = range;
 		return this;
 	}
 
+	/**
+	 * Set whether or not the expression has side effects.
+	 *
+	 * @param {boolean} sideEffects true, if the expression has side effects
+	 * @returns {this} this
+	 */
 	setSideEffects(sideEffects = true) {
 		this.sideEffects = sideEffects;
 		return this;
 	}
 
+	/**
+	 * Set the expression node for the expression.
+	 *
+	 * @param {EsTreeNode} expression expression
+	 * @returns {this} this
+	 */
 	setExpression(expression) {
 		this.expression = expression;
 		return this;

lib/javascript/JavascriptParser.js

@@ -1380,10 +1380,10 @@ class JavascriptParser extends Parser {
 						: "" + argExpr.number;
 
 					const newString = value + (stringSuffix ? stringSuffix.string : "");
-					const newRange = [
+					const newRange = /** @type {[number, number]} */ ([
 						argExpr.range[0],
 						(stringSuffix || argExpr).range[1]
-					];
+					]);
 					stringSuffix = new BasicEvaluatedExpression()
 						.setString(newString)
 						.setSideEffects(

types.d.ts

@@ -482,9 +482,9 @@ declare abstract class BasicEvaluatedExpression {
 	options?: BasicEvaluatedExpression[];
 	prefix?: BasicEvaluatedExpression;
 	postfix?: BasicEvaluatedExpression;
-	wrappedInnerExpressions: any;
+	wrappedInnerExpressions: BasicEvaluatedExpression[];
 	identifier?: string | VariableInfoInterface;
-	rootInfo: VariableInfoInterface;
+	rootInfo: string | VariableInfoInterface;
 	getMembers: () => string[];
 	getMembersOptionals: () => boolean[];
 	expression: NodeEstreeIndex;
@@ -535,41 +535,106 @@ declare abstract class BasicEvaluatedExpression {
 	 * Creates a nullish coalescing representation of this evaluated expression.
 	 */
 	asNullish(): undefined | boolean;
-	asString(): any;
+
+	/**
+	 * Creates a string representation of this evaluated expression.
+	 */
+	asString(): undefined | string;
 	setString(string?: any): BasicEvaluatedExpression;
 	setUndefined(): BasicEvaluatedExpression;
 	setNull(): BasicEvaluatedExpression;
-	setNumber(number?: any): BasicEvaluatedExpression;
-	setBigInt(bigint?: any): BasicEvaluatedExpression;
-	setBoolean(bool?: any): BasicEvaluatedExpression;
-	setRegExp(regExp?: any): BasicEvaluatedExpression;
+
+	/**
+	 * Set's the value of this expression to a number
+	 */
+	setNumber(number: number): BasicEvaluatedExpression;
+
+	/**
+	 * Set's the value of this expression to a BigInt
+	 */
+	setBigInt(bigint: bigint): BasicEvaluatedExpression;
+
+	/**
+	 * Set's the value of this expression to a boolean
+	 */
+	setBoolean(bool: boolean): BasicEvaluatedExpression;
+
+	/**
+	 * Set's the value of this expression to a regular expression
+	 */
+	setRegExp(regExp: RegExp): BasicEvaluatedExpression;
+
+	/**
+	 * Set's the value of this expression to a particular identifier and its members.
+	 */
 	setIdentifier(
-		identifier?: any,
-		rootInfo?: any,
-		getMembers?: any,
-		getMembersOptionals?: any
+		identifier: string | VariableInfoInterface,
+		rootInfo: string | VariableInfoInterface,
+		getMembers: () => string[],
+		getMembersOptionals?: () => boolean[]
 	): BasicEvaluatedExpression;
+
+	/**
+	 * Wraps an array of expressions with a prefix and postfix expression.
+	 */
 	setWrapped(
-		prefix?: any,
-		postfix?: any,
-		innerExpressions?: any
+		prefix: null | BasicEvaluatedExpression,
+		postfix: BasicEvaluatedExpression,
+		innerExpressions: BasicEvaluatedExpression[]
 	): BasicEvaluatedExpression;
-	setOptions(options?: any): BasicEvaluatedExpression;
-	addOptions(options?: any): BasicEvaluatedExpression;
-	setItems(items?: any): BasicEvaluatedExpression;
-	setArray(array?: any): BasicEvaluatedExpression;
+
+	/**
+	 * Stores the options of a conditional expression.
+	 */
+	setOptions(options: BasicEvaluatedExpression[]): BasicEvaluatedExpression;
+
+	/**
+	 * Adds options to a conditional expression.
+	 */
+	addOptions(options: BasicEvaluatedExpression[]): BasicEvaluatedExpression;
+
+	/**
+	 * Set's the value of this expression to an array of expressions.
+	 */
+	setItems(items: BasicEvaluatedExpression[]): BasicEvaluatedExpression;
+
+	/**
+	 * Set's the value of this expression to an array of strings.
+	 */
+	setArray(array: string[]): BasicEvaluatedExpression;
+
+	/**
+	 * Set's the value of this expression to a processed/unprocessed template string. Used
+	 * for evaluating TemplateLiteral expressions in the JavaScript Parser.
+	 */
 	setTemplateString(
-		quasis?: any,
-		parts?: any,
-		kind?: any
+		quasis: BasicEvaluatedExpression[],
+		parts: BasicEvaluatedExpression[],
+		kind: "raw" | "cooked"
 	): BasicEvaluatedExpression;
-	templateStringKind: any;
+	templateStringKind?: "raw" | "cooked";
 	setTruthy(): BasicEvaluatedExpression;
 	setFalsy(): BasicEvaluatedExpression;
-	setNullish(value?: any): BasicEvaluatedExpression;
-	setRange(range?: any): BasicEvaluatedExpression;
+
+	/**
+	 * Set's the value of the expression to nullish.
+	 */
+	setNullish(value: boolean): BasicEvaluatedExpression;
+
+	/**
+	 * Set's the range for the expression.
+	 */
+	setRange(range: [number, number]): BasicEvaluatedExpression;
+
+	/**
+	 * Set whether or not the expression has side effects.
+	 */
 	setSideEffects(sideEffects?: boolean): BasicEvaluatedExpression;
-	setExpression(expression?: any): BasicEvaluatedExpression;
+
+	/**
+	 * Set the expression node for the expression.
+	 */
+	setExpression(expression: NodeEstreeIndex): BasicEvaluatedExpression;
 }
 type BuildMeta = KnownBuildMeta & Record<string, any>;
 declare abstract class ByTypeGenerator extends Generator {