Convert JSEP to ES6 class, while maintaining backward compatibility #140

6utt3rfly · 2021-04-24T23:38:32Z

Follow-up from #123, and related to #137 and #130

Converts JSEP to use ES6 classes (but roll-up builds ESM, IIFE, and CJS):

class Constants - just the string/numerical constants
class JsepConfig - all the current functions on jsep
class Jsep - the parser. Constructed with expr and parsed with parse()

Maintained backward compatibility by exporting a default function that uses those classes. Tests are unchanged to ensure consistency.

Performance comparison:

Before PR: 4303.82 op/s +/- 2.09% [5.74% slower]
This PR: 4566 ops/s +/- 2.99%
(from jsbench.me with both versions in the setup. Ran all of the current test cases in both versions)

Size comparison:

+----------------------+-----------+---------+
| FILE                 | Before PR | this PR |
+----------------------+-----------+---------+
| jsep.cjs.js          |   19972   |  23780  |
| jsep.cjs.js.map      |   41299   |  49294  |
| jsep.cjs.min.js      |   5102    |  9376   |
| jsep.cjs.min.js.map  |   31041   |  38040  |
| jsep.iife.js         |   20720   |  24672  |
| jsep.iife.js.map     |   41307   |  49302  |
| jsep.iife.min.js     |   5102    |  9382   |
| jsep.iife.min.js.map |   31107   |  38038  |
| jsep.js              |   19853   |  23616  |
| jsep.min.js          |   5029    |  9296   |
| jsep.min.js.map      |   31036   |  38035  |
+----------------------+-----------+---------+

Hopefully OK that I took a stab at this, @LeaVerou ? I'm happy to change it or whatever :-)

EricSmekens · 2021-04-26T07:28:34Z

Had a quick look through, thank you for this work on it!
I'll wait so LeaVerou can review this as well.

LeaVerou · 2021-04-26T13:29:28Z

Hey, so sorry for being absent lately, I was extremely busy with moving. Now settling in slowly, and should be able to take a look in the next couple of days.

LeaVerou · 2021-04-26T14:28:46Z

From a very cursory look, a lot of this looks like what I had in mind, but I'm not sure about the added complexity of having three classes, I was envisioning it as a single Jsep class. I can sort of see the point of JsepConfig (interesting idea to have multiple different parsers simultaneously, though not sure if there are enough use cases to justify the complexity), but not the one of Constants. However, I could very well be missing something, since I haven't personally done the work that this PR is introducing. @6utt3rfly could you elaborate a bit on this design decision?

6utt3rfly · 2021-04-26T15:51:49Z

When I was trying to write some plugins with the existing code, there were some constants that I had to duplicate because they were not accessible to the plugins in other files. I think it would be useful to have access to them from plugins, but I agree they could be an Object, or placed directly onto the class. I debated freezing it, but then thought it might be useful to allow to add to it (or possibly redefine, but I don't know a use-case for that).

For having separate config/parsing classes, I was mostly just thinking of separation of responsibilities. The parsing class makes sense to construct and destroy with each parsing request (similar to existing behavior). It would also allow passing that class instance into plugins. I don't know if there are cases where different configurations of parsing might be useful to run concurrently, but it also seemed like an easy thing to support with that separation. To me, it felt wrong to have methods to add/remove operators that would affect static variables on the class (or hidden variables in the file that plugins would then not have access to) -- and I didn't want to have to copy them or do extra work in the constructor of every parser.

Just my humble opinions though :-)

LeaVerou · 2021-04-27T11:52:56Z

Agreed that constants need to be available to plugins, and also agreed that the object shouldn't be frozen, so it can be extended.
It's just that if we take built-in JS APIs as examples, their constants tend to be static properties on the class itself, not separate classes (e.g. Node.ELEMENT_NODE), so a separate class for that seems unusual and a bit overkill.

Your reasoning about the config class makes sense. I think I like the idea.

6utt3rfly · 2021-04-27T16:33:34Z

Sounds good - do you prefer static getters, or assigning the constants as properties after declaring the class?

LeaVerou · 2021-04-27T16:59:01Z

I think simple properties are fine.

src/jsep.js

LeaVerou · 2021-04-27T17:49:39Z

src/jsep.js

+		this.expr = expr;
+		this.config = config;
+		this.index = 0;
+		this.length = expr.length;


Maybe this should be a getter? Though that might hinder performance.

I just ran a performance benchmark and there doesn't seem to be any performance difference between saving that local variable versus using this.expr.length. A getter is about 60% slower though. Mostly I just kept it to try not to change the existing code too much

6utt3rfly · 2021-04-28T04:52:11Z

@LeaVerou - I pushed my changes to switch to a single class with static methods and fields. I also added a getter for getCharAt and getCharCodeAt (there's also a getChar and getCharCode with default index = this.index which does the same thing ... could remove the default or just use that method)?

Revised sizes:

+----------------------+-----------+---------+
| FILE                 | Before PR | this PR |
+----------------------+-----------+---------+
| jsep.cjs.js          |   19972   |  23181  |
| jsep.cjs.js.map      |   41299   |  47737  |
| jsep.cjs.min.js      |   5102    |  9023   |
| jsep.cjs.min.js.map  |   31041   |  36733  |
| jsep.iife.js         |   20720   |  24059  |
| jsep.iife.js.map     |   41307   |  47745  |
| jsep.iife.min.js     |   5102    |  9041   |
| jsep.iife.min.js.map |   31107   |  36730  |
| jsep.js              |   19853   |  23058  |
| jsep.min.js          |   5029    |  8953   |
| jsep.min.js.map      |   31036   |  36728  |
+----------------------+-----------+---------+

LeaVerou · 2021-04-28T13:31:51Z

I thought we'd still use a separate class for the config? Anyway, I'm fine either way, probably a good idea to start simple and take it from there.
I do think that this.char and this.code (or this.charCode) might be more readable but if you have strong opinions on the current naming, I'm fine with that.

LeaVerou · 2021-04-28T13:32:51Z

src/jsep.js

+	 * @returns {Jsep}
+	 */
+	static addIdentifierChar(char) {
+		Jsep.additional_identifier_chars.add(char);


Does this function only exist for backwards compat? Because if additional_identifier_chars is exposed, people can just add characters to it directly.

Yeah, although it was only just added recently, so could possibly be removed with minimal impact?

LeaVerou · 2021-04-28T13:35:47Z

src/jsep.js

+	 */
+	static addBinaryOp(op_name, precedence) {
+		Jsep.max_binop_len = Math.max(op_name.length, Jsep.max_binop_len);
+		Jsep.binary_ops[op_name] = precedence;


This is not for this PR, but I think eventually we may want to move towards a data structure that just works, vs having to use special-purpose mutation methods. E.g. we could make binary_ops an instance of a BinaryOpMap which would inherit from Map but intercept its methods to update the max length accordingly. Then people can just modify it like a regular map. What do you think?

Yeah I agree. It makes sense to encapsulate and would allow reuse with the unaryOp.

LeaVerou · 2021-04-28T13:43:36Z

src/jsep.js

+	 * @param {string} message
+	 */
+	throwError(message, index = this.index) {
+		Jsep.throwError(message, index);


I looked through the code and did not find a single usage of throwError() with an index other than this.index. Should we have this parameter at all? Also, is there a reason to have both a static and an instance method to throw errors? The static method does not appear to be used anywhere except internally. Is it used in plugins perhaps?

In general, I think it's good practice to start with a smaller API and grow as needed, than a larger one because certain needs are anticipated that may never arise. But that might be a philosophical difference.

src/jsep.js

LeaVerou · 2021-04-28T13:45:18Z

src/jsep.js

+	 * @returns {boolean}
+	 */
+	isIdentifierPart(ch) {
+		return this.isIdentifierStart(ch) || Jsep.isDecimalDigit(ch);


This should be a static method, it does not depend on this in any way.

LeaVerou · 2021-04-28T13:48:38Z

src/jsep.js

+	 * @returns {number}
+	 */
+	charCodeAt(index = this.index) {
+		return this.expr.charCodeAt(index);


Honestly, adding methods that just wrap the same function calls on this.expr seems like overabstraction. Especially since we already have convenience getters when what we want is this.expr.charCodeAt(this.index) so this is literally just a wrapper for the function call.
Same applies to the charAt() wrapper above.

agree - changed

LeaVerou · 2021-04-28T13:49:53Z

src/jsep.js

-	// top-level parser (but can be reused within as well)
-	let gobbleExpressions = function(untilICode) {
+	/**
+	 * Top-level method to parse all expressions and returns compound or singl


Comment seems truncated?

LeaVerou · 2021-04-28T13:53:07Z

src/jsep.js

+	 * @param {jsep.Expression} right
+	 * @returns {jsep.BinaryExpression}
+	 */
+	static createBinaryExpression(operator, left, right) {


I think this would be fine inlined and would make the code more clear. It's only used twice and the function doesn't do much.

- make methods static where possible - throwError no longer static - inline createBinaryExpression method - rename currentChar/code to just char/code. Remove method, leave just getters for current index

6utt3rfly · 2021-04-28T14:47:46Z

src/jsep.js

+	 */
+	static addBinaryOp(op_name, precedence) {
+		Jsep.max_binop_len = Math.max(op_name.length, Jsep.max_binop_len);
+		Jsep.binary_ops[op_name] = precedence;


Yeah I agree. It makes sense to encapsulate and would allow reuse with the unaryOp.

6utt3rfly · 2021-04-28T14:49:28Z

src/jsep.js

+	 * @returns {Jsep}
+	 */
+	static addIdentifierChar(char) {
+		Jsep.additional_identifier_chars.add(char);


Yeah, although it was only just added recently, so could possibly be removed with minimal impact?

6utt3rfly · 2021-04-28T14:50:46Z

src/jsep.js

+	 * @param {jsep.Expression} right
+	 * @returns {jsep.BinaryExpression}
+	 */
+	static createBinaryExpression(operator, left, right) {


6utt3rfly · 2021-04-28T14:50:58Z

src/jsep.js

+	 * @returns {number}
+	 */
+	charCodeAt(index = this.index) {
+		return this.expr.charCodeAt(index);


agree - changed

6utt3rfly · 2021-04-28T14:51:43Z

src/jsep.js

+	 * @param {string} message
+	 */
+	throwError(message, index = this.index) {
+		Jsep.throwError(message, index);


6utt3rfly · 2021-04-28T15:19:42Z

src/jsep.js

+}
+
+// Backward Compatibility (before adding the static fields):
+const jsep = expr => (new Jsep(expr)).parse();


I figure this can be Jsep.parse or expr => (new Jsep(expr)).parse()?

If it's Jsep.parse then the functions we're adding to it afterwards would be added to Jsep.parse as well.

It could however be expr => Jsep.parse(expr)

LeaVerou · 2021-04-28T15:54:33Z

src/jsep.js

+	// Node Types
+	// ----------
+	// This is the full set of types that any JSEP node can be.
+	// Store them here to save space when minified


I just noticed this comment. If the only purpose of these constants is to "save space when minified", then we should get rid of them, per #131. What do you think?

I'm only referring to the expression type constants. The character code ones are obviously useful.
Not sure e.g. MEMBER_EXP is easier to remember than "MemberExpression". The only benefit I see is that perhaps we can change the type without having to change it everywhere in the code, but are we ever going to do that? 🤔

I'm indifferent... there are some of the defines that are used multiple times, and others only once. For consistency it's kind of nice to have them here. And I think it's nicer to use a constant/enum rather than needing the exact string in several places.

LeaVerou · 2021-04-28T15:56:08Z

src/jsep.js

+const jsep = Jsep.parse;
+const staticMethods = Object.getOwnPropertyNames(Jsep);
+staticMethods
+	.slice(staticMethods.indexOf('version'), staticMethods.indexOf('removeAllLiterals') + 1)


Which properties are we trying to avoid here?

The full list it returns:

0: "length" 1: "prototype" 2: "version" 3: "toString" 4: "addUnaryOp" 5: "addBinaryOp" 6: "addIdentifierChar" 7: "addLiteral" 8: "removeUnaryOp" 9: "removeAllUnaryOps" 10: "removeIdentifierChar" 11: "removeBinaryOp" 12: "removeAllBinaryOps" 13: "removeLiteral" 14: "removeAllLiterals" 15: "parse" 16: "getMaxKeyLen" 17: "isDecimalDigit" 18: "binaryPrecedence" 19: "isIdentifierStart" 20: "isIdentifierPart" 21: "name"

(and would add all the subsequent ones too if I moved this to the end of the file)

LeaVerou

Looks good to me! See 2 minor comments (more like questions).

LeaVerou · 2021-04-28T19:29:35Z

Merged! Thanks again!

@EricSmekens can we add @6utt3rfly as a collaborator? I think it's very well deserved.

EricSmekens · 2021-04-29T06:56:43Z

Yes, I fully agree! Will do that in a few minutes!

Convert JSEP to ES6 class, while maintaining backward compatibility

17a7845

6utt3rfly mentioned this pull request Apr 24, 2021

Basic Arrow function support + array methods #123

Closed

EricSmekens approved these changes Apr 26, 2021

View reviewed changes

LeaVerou reviewed Apr 27, 2021

View reviewed changes

src/jsep.js Outdated Show resolved Hide resolved

LeaVerou reviewed Apr 27, 2021

View reviewed changes

src/jsep.js Outdated Show resolved Hide resolved

LeaVerou reviewed Apr 27, 2021

View reviewed changes

Revised to use a single class, and getCurrentChar

2a2cedb

LeaVerou reviewed Apr 28, 2021

View reviewed changes

PR Review Changes:

b1e5307

- make methods static where possible - throwError no longer static - inline createBinaryExpression method - rename currentChar/code to just char/code. Remove method, leave just getters for current index

6utt3rfly commented Apr 28, 2021

View reviewed changes

LeaVerou reviewed Apr 28, 2021

View reviewed changes

LeaVerou approved these changes Apr 28, 2021

View reviewed changes

Go back to function for backward compatibility rather than Jsep.parse

1c36036

LeaVerou merged commit 25fcb53 into EricSmekens:master Apr 28, 2021

6utt3rfly deleted the es6-class branch April 29, 2021 04:02

6utt3rfly mentioned this pull request Jul 25, 2021

Cleaning up plugin-system #153

Closed

6utt3rfly mentioned this pull request Feb 28, 2022

Multiple instances of jsep with different operators #211

Open

Convert JSEP to ES6 class, while maintaining backward compatibility #140

Convert JSEP to ES6 class, while maintaining backward compatibility #140

Conversation

6utt3rfly commented Apr 24, 2021

Performance comparison:

Size comparison:

EricSmekens commented Apr 26, 2021

LeaVerou commented Apr 26, 2021

LeaVerou commented Apr 26, 2021

6utt3rfly commented Apr 26, 2021

LeaVerou commented Apr 27, 2021

6utt3rfly commented Apr 27, 2021

LeaVerou commented Apr 27, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

6utt3rfly commented Apr 28, 2021

LeaVerou commented Apr 28, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LeaVerou left a comment

Choose a reason for hiding this comment

LeaVerou commented Apr 28, 2021

EricSmekens commented Apr 29, 2021