From f3389577effd3c37180021252383f5ac82e70021 Mon Sep 17 00:00:00 2001 From: Sean Larkin Date: Fri, 28 Apr 2023 19:21:02 +0000 Subject: [PATCH] refactor(types): Increase type coverage & docs for B.E.E --- .../HarmonyImportDependencyParserPlugin.js | 1 + lib/javascript/BasicEvaluatedExpression.js | 101 ++++++++++++++- lib/javascript/JavascriptParser.js | 4 +- types.d.ts | 115 ++++++++++++++---- 4 files changed, 193 insertions(+), 28 deletions(-) diff --git a/lib/dependencies/HarmonyImportDependencyParserPlugin.js b/lib/dependencies/HarmonyImportDependencyParserPlugin.js index ba74c9bbcd6..8aa1a57a46e 100644 --- a/lib/dependencies/HarmonyImportDependencyParserPlugin.js +++ b/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 diff --git a/lib/javascript/BasicEvaluatedExpression.js b/lib/javascript/BasicEvaluatedExpression.js index 3ad8b3b1cc2..2a5258daec8 100644 --- a/lib/javascript/BasicEvaluatedExpression.js +++ b/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,6 +329,11 @@ 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; @@ -331,6 +341,11 @@ class BasicEvaluatedExpression { 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; @@ -338,6 +353,11 @@ class BasicEvaluatedExpression { 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; @@ -345,6 +365,11 @@ class BasicEvaluatedExpression { 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; @@ -352,6 +377,15 @@ class BasicEvaluatedExpression { 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,6 +413,12 @@ 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; @@ -378,6 +426,12 @@ class BasicEvaluatedExpression { 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,6 +444,12 @@ 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; @@ -397,6 +457,12 @@ class BasicEvaluatedExpression { 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; @@ -404,6 +470,15 @@ class BasicEvaluatedExpression { 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; diff --git a/lib/javascript/JavascriptParser.js b/lib/javascript/JavascriptParser.js index 84af43333a1..d02cb75d4f7 100644 --- a/lib/javascript/JavascriptParser.js +++ b/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( diff --git a/types.d.ts b/types.d.ts index 6c051f7eb0a..3a308365557 100644 --- a/types.d.ts +++ b/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; declare abstract class ByTypeGenerator extends Generator {