Adopt ES6 class syntax #979

le0tan · 2020-01-14T10:45:09Z

What is the purpose of this pull request? (put "X" next to an item, remove the rest)

• [X] Enhancement to an existing feature

What is the rationale for this request?

ES6 class syntax is more beginner-friendly, and clearer to read.

What changes did you make? (Give an overview)

Refactor Site.js, Page.js and parser.js with class keyword.
Extract out utility functions into separate files for better consistency.
Re-structure some part of the class for better data encapsulation.

Provide some example code that this change will affect:

na

Is there anything you'd like reviewers to focus on?

na

Testing instructions:

npm run test

Proposed commit message: (wrap lines at 72 characters)

Adopt ES6 class syntax for Site, Page and Parser

Refactor Site.js, Page.js and parser.js with class keyword.
Extract out utility functions into separate files for better
consistency.
Re-structure some part of the class for better data encapsulation.

le0tan · 2020-01-14T10:47:25Z

@yamgent help wanted: could you please explain a bit on what delay does and why can't we use setTimeout instead? I added TODOs in Site.js to indicate places where I removed delay to stop ESLint from complaining.

acjh · 2020-01-14T12:22:40Z

could you please explain a bit on what delay does and why can't we use setTimeout instead?

From the jsdoc of delay:

/**
* Creates a function that delays invoking `func` until after `wait` milliseconds have elapsed
* and the running `func` has resolved/rejected.

What delay does, which differs from setTimeout and debounce:

if func is not running, it accumulates the arguments of multiple calls of func into a single call that will be triggered wait milliseconds after the first call, and
if func is running, it accumulates the arguments of subsequent calls of func and queues a single call that will be triggered after the running call.

I find that quite powerful; it solves #155.

The original PR MarkBind/markbind-cli#31 contains the initial discussion.

I removed delay to stop ESLint from complaining.

What was ESLint complaining about?

le0tan · 2020-01-14T12:44:59Z

Thanks for the explanation! That makes a lot of sense now.

What was ESLint complaining about?

If I write like rebuildAffectedSourceFiles = delay(this._rebuildAffectedSourceFiles, 1000);, ESLint will show

ESLint: Parsing error: Unexpected token =

as it expects the method to be a function.

ang-zeyu · 2020-01-14T13:56:21Z

If I write like rebuildAffectedSourceFiles = delay(this._rebuildAffectedSourceFiles, 1000);, ESLint will show
ESLint: Parsing error: Unexpected token =

If this line was directly within the Site class, you could wrap it around, something like this

rebuildAffectedSourceFiles(arg) {
  const delayedFunc = delay(this._rebuildAffectedSourceFiles, 1000);

  return delayedFunc(arg);
}

ES6 classes don't allow 'assignments' inside the class template, I think

openorclose · 2020-01-14T14:35:58Z

If I write like rebuildAffectedSourceFiles = delay(this._rebuildAffectedSourceFiles, 1000);, ESLint will show
ESLint: Parsing error: Unexpected token =
If this line was directly within the Site class, you could wrap it around, something like this
rebuildAffectedSourceFiles(arg) {
  const delayedFunc = delay(this._rebuildAffectedSourceFiles, 1000);

  return delayedFunc(arg);
}
ES6 classes don't allow 'assignments' inside the class template, I think

Well this is quite different as a new delayedFunc is created at each call of rebuildAffectedSourceFiles which is not we want.

Just retain the original

Site.prototype.rebuildAffectedSourceFiles	
  = delay(Site.prototype._rebuildAffectedSourceFiles, 1000);

after the class declaration for now?

Some time after this proposal is merged https://github.com/tc39/proposal-class-fields we can revisit this.

ang-zeyu · 2020-01-14T15:21:01Z

Well this is quite different as a new delayedFunc is created at each call of rebuildAffectedSourceFiles which is not we want.

Just retain the original
Site.prototype.rebuildAffectedSourceFiles	
  = delay(Site.prototype._rebuildAffectedSourceFiles, 1000);
after the class declaration for now?

Some time after this proposal is merged https://github.com/tc39/proposal-class-fields we can revisit this.

My bad 😅 , good catch

Sounds good

le0tan · 2020-01-14T16:06:16Z

It's also possible to use this solution, but it may complicate things, so I might as well stick to the prototype version for delay related functions?

openorclose · 2020-01-15T00:36:09Z

Nah, that's not a solution since we're targeting ES6 which does not allow class properties.

Class properties aren't in any ES specification yet, so even though it works on node 12 it's possible that they take it out in a future version.

le0tan · 2020-01-15T06:15:37Z

If there's no rejection on adopting the ES6 class syntax I'll start working on refactoring other classes then =)

yamgent · 2020-01-15T10:57:22Z

If there's no rejection on adopting the ES6 class syntax I'll start working on refactoring other classes then =)

Ok please go ahead. 👍

Extracted out utility functions into pageUtil.js for better consistency

yamgent

These comments applies to all the files:

src/lib/markbind/src/parser.js

add them as static methods in respective classes

openorclose

Looks mostly okay, just minor syntax changes to ES6 classes and not much code changes.

src/Page.js

src/Site.js

- adopt ES6 syntax for unique(array) - remove redundant Site method

yamgent

I do realize that the blank lines are being removed as well. Were all the blank lines removed, or was it manually done to clean up unnecessary blank lines? Just wondering as functions in MarkBind are quite long, so those blank lines may aid in easier reading of the code.

yamgent · 2020-01-18T02:53:38Z

src/lib/markbind/src/parser.js

 const Promise = require('bluebird');
 const url = require('url');
+const pathIsInside = require('path-is-inside');


The imports should be in alphabetical order.

yamgent · 2020-01-18T02:54:00Z

src/lib/markbind/src/parser.js

  IMPORTED_VARIABLE_PREFIX,
+  BOILERPLATE_FOLDER_NAME,


Ideal to have the constants in alphabetical order too.

le0tan · 2020-01-18T05:04:06Z

I do realize that the blank lines are being removed as well. Were all the blank lines removed, or was it manually done to clean up unnecessary blank lines? Just wondering as functions in MarkBind are quite long, so those blank lines may aid in easier reading of the code.

ESLint will complain if there are more blank lines:

ESLint: More than 2 blank lines not allowed.(no-multiple-empty-lines)

I will try to document all functions for better readability in a future PR.

to alphabetical order

yamgent · 2020-01-18T06:32:52Z

Btw GitHub is complaining about conflicting files, you will have to resolve it.

You can also squash the commits for this PR, we won't need the separate commits for now.

le0tan · 2020-01-21T09:14:46Z

@openorclose I reverted the global variables in parser.js. Can you take a look? I tested live reloading and it should work now.

# Conflicts: # src/Page.js # src/Site.js

le0tan · 2020-01-22T09:47:56Z

Btw GitHub is complaining about conflicting files, you will have to resolve it.

@ang-zeyu @yamgent I made my best effort to resolve the merge conflicts mostly introduced by #974, can you take a look if I broke anything? Thanks!

ang-zeyu · 2020-01-22T13:23:56Z

@ang-zeyu @yamgent I made my best effort to resolve the merge conflicts mostly introduced by #974, can you take a look if I broke anything? Thanks!

LGTM, it shouldn't cause any issues with plugin live reloading if live reload already works. There's a few pumls at the bottom of the test site you can try editing to test plugin live reloading though

On another note I noticed you made quite a few style changes to existing method calls ( newlines between chained method calls ). Was this due to a conflict with an eslint rule from using classes? It might be better to make such changes in a seperate PR to make the diff easier to compare otherwise!

yamgent · 2020-01-28T02:15:08Z

Sorry there's another merge conflict due to a recent merge of the big feature #944. Would need you to rebase again.

Once your PR is rebased and in order, I will prioritize your PR to be merged next.

le0tan · 2020-01-28T03:54:21Z

Sorry there's another merge conflict due to a recent merge of the big feature #944. Would need you to rebase again.

Once your PR is rebased and in order, I will prioritize your PR to be merged next.

@yamgent I (again) tried my best effort to merge this conflict... can @crphang do some quality assurance on this merge?

crphang

Very good work on the migration 🎉. LGTM in general, don't see any issues with resolution of merge conflicts.

crphang · 2020-01-29T13:19:45Z

src/lib/markbind/src/parser.js

-  const filePath = element.attribs[ATTRIB_INCLUDE_PATH];
-  const fileBase = calculateNewBaseUrls(filePath, config.rootPath, config.baseUrlMap);
-  if (!fileBase.relative) {
-    return pa


Don't think it should be resolved in this PR, but can this be declared in the constructor?

What do you think @yamgent?

It will probably take a bit of work to move it to the constructor, since it is likely that the original author intentionally makes it globally scoped.

So yes let's leave it to another PR.

ang-zeyu

A little late, but, I noticed there are quite a few strange newlines-after calls to $(...) that makes the code harder to read. Subjective in some cases, but rather awkward in others.

Should we keep to a minimum of three method calls before indenting with newlines? a().b().c()

ang-zeyu · 2020-01-30T17:19:22Z

src/Page.js

+    this.keywords = {};
+    // Collect headings and keywords
+    this.collectHeadingsAndKeywordsInContent($(`#${CONTENT_WRAPPER_ID}`)
+      .html(), null, false, []);


ang-zeyu · 2020-01-30T17:19:46Z

src/Page.js

+      $('modal')
+        .remove();
+      $('panel')
+        .remove();


ang-zeyu · 2020-01-30T17:20:16Z

src/Page.js

+   */
+  linkKeywordToHeading($, keyword, heading) {
+    const headingId = $(heading)
+      .attr('id');


ang-zeyu · 2020-01-30T17:20:20Z

src/Page.js

+      this.keywords[headingId] = [];
+    }
+    this.keywords[headingId].push($(keyword)
+      .text());


le0tan · 2020-01-30T17:32:29Z

I believe this is mostly due to WebStorm’s auto formatting. (It turns out to be a bit unreliable sometimes, but I think it’s well justified as I was doing such extensive refactoring. Will try to avoid that in the future.). That being said, I will create another PR to fix the JSDoc issues and formatting issues. Thanks!

On Fri, 31 Jan 2020 at 1:23 AM, Ang Ze Yu ***@***.***> wrote: ***@***.**** commented on this pull request. A little late, but, I noticed there are quite a few strange newlines-after calls to $(...) that makes the code harder to read. Subjective in some cases, but rather awkward in others. Should we keep to a minimum of three method calls before indenting with newlines? a().b().c() ------------------------------ In src/Page.js <#979 (comment)>: > -Page.prototype.collectNavigableHeadings = function (content) { - const { pageNav } = this.frontMatter; - const elementSelector = this.generateElementSelectorForPageNav(pageNav); - if (elementSelector === undefined) { - return; + /** + * Records headings and keywords inside rendered page into this.headings and this.keywords respectively + */ + collectHeadingsAndKeywords() { + const $ = cheerio.load(fs.readFileSync(this.resultPath)); + // Re-initialise objects in the event of Site.regenerateAffectedPages + this.headings = {}; + this.keywords = {}; + // Collect headings and keywords + this.collectHeadingsAndKeywordsInContent($(`#${CONTENT_WRAPPER_ID}`) + .html(), null, false, []); . ------------------------------ In src/Page.js <#979 (comment)>: > }); - } - $('.keyword').each((i, keyword) => { - let closestHeading = getClosestHeading($, headingsSelector, keyword); - if (excludeHeadings || !closestHeading) { - if (!lastHeading) { - logger.warn(`Missing heading for keyword: ${$(keyword).text()}`); - return; - } - closestHeading = lastHeading; + $ = cheerio.load(content); + if (this.headingIndexingLevel > 0) { + $('modal') + .remove(); + $('panel') + .remove(); . ------------------------------ In src/Page.js <#979 (comment)>: > - * @param keyword to link - * @param heading to link - */ -Page.prototype.linkKeywordToHeading = function ($, keyword, heading) { - const headingId = $(heading).attr('id'); - if (!(headingId in this.keywords)) { - this.keywords[headingId] = []; + /** + * Links a keyword to a heading + * @param $ a Cheerio object + * @param keyword to link + * @param heading to link + */ + linkKeywordToHeading($, keyword, heading) { + const headingId = $(heading) + .attr('id'); . ------------------------------ In src/Page.js <#979 (comment)>: > - if (!(headingId in this.keywords)) { - this.keywords[headingId] = []; + /** + * Links a keyword to a heading + * @param $ a Cheerio object + * @param keyword to link + * @param heading to link + */ + linkKeywordToHeading($, keyword, heading) { + const headingId = $(heading) + .attr('id'); + if (!(headingId in this.keywords)) { + this.keywords[headingId] = []; + } + this.keywords[headingId].push($(keyword) + .text()); . — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#979?email_source=notifications&email_token=AG5DZVXWBBLDCGEN5WD7PT3RAMEHRA5CNFSM4KGQ2LYKYY3PNVWWK3TUL52HS4DFWFIHK3DMKJSXC5LFON2FEZLWNFSXPKTDN5WW2ZLOORPWSZGOCTV5TTY#pullrequestreview-351001039>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AG5DZVRGVWFTVOUMNKJPIHDRAMEHRANCNFSM4KGQ2LYA> .

-- Regards, Tan Yuanhong

Refactor Site class to follow ES6 conventions on JS classes.

a3b1781

le0tan added 4 commits January 16, 2020 01:45

Use old syntax to adopt delay function

b889b97

Refactor Page.js to ES6 class

2571d35

Extracted out utility functions into pageUtil.js for better consistency

Extract parser util functions

252b07f

Adopt ES6 class syntax for Parser class

577c3c7

le0tan changed the title ~~[WIP] Adopt ES6 class syntax~~ Adopt ES6 class syntax Jan 16, 2020

le0tan requested review from openorclose and yamgent January 16, 2020 10:27

yamgent reviewed Jan 16, 2020

View reviewed changes

src/lib/markbind/src/parser.js Outdated Show resolved Hide resolved

src/lib/markbind/src/parser.js Outdated Show resolved Hide resolved

src/lib/markbind/src/parser.js Outdated Show resolved Hide resolved

src/lib/markbind/src/parser.js Show resolved Hide resolved

le0tan added 3 commits January 16, 2020 22:05

Remove unnecessary eslint disables

ddfc4bd

Remove commented out code

84420bd

Remove extracted util files

9af0485

add them as static methods in respective classes

le0tan requested a review from yamgent January 16, 2020 14:20

openorclose reviewed Jan 16, 2020

View reviewed changes

src/Page.js Outdated Show resolved Hide resolved

src/Site.js Outdated Show resolved Hide resolved

Minor changes

ed7e03b

- adopt ES6 syntax for unique(array) - remove redundant Site method

yamgent reviewed Jan 18, 2020

View reviewed changes

le0tan added 2 commits January 18, 2020 13:10

Reorder imports

fe5267d

to alphabetical order

Fix linebreak styles

4c6ea87

Revert global variables in parser.js

1826d06

Merge remote-tracking branch 'upstream/master' into es6-site-class

c2afa74

# Conflicts: # src/Page.js # src/Site.js

le0tan requested a review from yamgent January 22, 2020 09:48

Merge branch 'master' into es6-site-class

5c2c76e

crphang reviewed Jan 29, 2020

View reviewed changes

yamgent force-pushed the es6-site-class branch 3 times, most recently from eb5d71e to ab17775 Compare January 30, 2020 02:29

Merge branch 'master' into es6-site-class

1d544b8

yamgent force-pushed the es6-site-class branch from ab17775 to 1d544b8 Compare January 30, 2020 02:30

yamgent approved these changes Jan 30, 2020

View reviewed changes

yamgent added this to the v2.10.0 milestone Jan 30, 2020

yamgent merged commit af47ed0 into MarkBind:master Jan 30, 2020

ang-zeyu reviewed Jan 30, 2020

View reviewed changes

nbriannl pushed a commit to nbriannl/markbind that referenced this pull request Feb 9, 2020

Adopt ES6 class syntax (MarkBind#979)

a1cbfb7

nbriannl pushed a commit to nbriannl/markbind that referenced this pull request Feb 9, 2020

Adopt ES6 class syntax (MarkBind#979)

b1f76a8

This was referenced Apr 4, 2020

Convert all code to ES6 (classes, async/await, etc.) #809

Closed

Standardise code style and remove eslint disables #1180

Merged

This was referenced Apr 12, 2023

Migrate Site/index.js to TypeScript #2270

Merged

Refactor methods implemented using Site.prototype #2280

Closed

jmestxr mentioned this pull request Aug 17, 2023

Implement Site.Prototype methods in ES6 syntax #2280 #2356

Merged

11 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adopt ES6 class syntax #979

Adopt ES6 class syntax #979

le0tan commented Jan 14, 2020 •

edited

le0tan commented Jan 14, 2020

acjh commented Jan 14, 2020

le0tan commented Jan 14, 2020

ang-zeyu commented Jan 14, 2020

openorclose commented Jan 14, 2020

ang-zeyu commented Jan 14, 2020

le0tan commented Jan 14, 2020

openorclose commented Jan 15, 2020

le0tan commented Jan 15, 2020

yamgent commented Jan 15, 2020

yamgent left a comment

openorclose left a comment

yamgent left a comment

yamgent Jan 18, 2020

yamgent Jan 18, 2020

le0tan commented Jan 18, 2020

yamgent commented Jan 18, 2020

le0tan commented Jan 21, 2020

le0tan commented Jan 22, 2020 •

edited

ang-zeyu commented Jan 22, 2020

yamgent commented Jan 28, 2020

le0tan commented Jan 28, 2020

crphang left a comment

crphang Jan 29, 2020

yamgent Jan 30, 2020

yamgent Jan 30, 2020

ang-zeyu left a comment

ang-zeyu Jan 30, 2020

ang-zeyu Jan 30, 2020

ang-zeyu Jan 30, 2020

ang-zeyu Jan 30, 2020

le0tan commented Jan 30, 2020 via email

Adopt ES6 class syntax #979

Adopt ES6 class syntax #979

Conversation

le0tan commented Jan 14, 2020 • edited

le0tan commented Jan 14, 2020

acjh commented Jan 14, 2020

le0tan commented Jan 14, 2020

ang-zeyu commented Jan 14, 2020

openorclose commented Jan 14, 2020

ang-zeyu commented Jan 14, 2020

le0tan commented Jan 14, 2020

openorclose commented Jan 15, 2020

le0tan commented Jan 15, 2020

yamgent commented Jan 15, 2020

yamgent left a comment

Choose a reason for hiding this comment

openorclose left a comment

Choose a reason for hiding this comment

yamgent left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

le0tan commented Jan 18, 2020

yamgent commented Jan 18, 2020

le0tan commented Jan 21, 2020

le0tan commented Jan 22, 2020 • edited

ang-zeyu commented Jan 22, 2020

yamgent commented Jan 28, 2020

le0tan commented Jan 28, 2020

crphang left a 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

ang-zeyu left a 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

le0tan commented Jan 30, 2020 via email

le0tan commented Jan 14, 2020 •

edited

le0tan commented Jan 22, 2020 •

edited