New: ESLint Class Replacing CLIEngine

[mysticatea]

• Rendered RFC
• Blocked by New: Drop supports for Node.js 8.x and 11.x #44. (merged)

Summary

This RFC changes the methods of CLIEngine class as returning Promise and adds CLIEngineSync class for soft-migration.

This RFC adds a new class LinterShell that provides asynchronous API and deprecates CLIEngine.

Related Issues

• Show results for each file as eslint is running eslint#1098 - Show results for each file as eslint is running
• Lint multiple files in parallel [$500] eslint#3565 - Lint multiple files in parallel
• Validate options passed to CLIEngine API eslint#10272 - Validate options passed to CLIEngine API
• Make CLIEngine and supporting functions async via Promises eslint#10606 - Make CLIEngine and supporting functions async via Promises
• ERR_REQUIRE_ESM when requiring .eslintrc.js eslint#12319 - ERR_REQUIRE_ESM when requiring .eslintrc.js
• New: added draft for async/parallel proposal #4 - New: added draft for async/parallel proposal
• New: Lint files in parallel #11 - New: Lint files in parallel
• feat: Lint files in parallel if many files exist #42 - New: Lint files in parallel if many files exist
• New: Drop supports for Node.js 8.x and 11.x #44 - New: Drop supports for Node.js 8.x and 11.x
• New: Formatter v2 #45 - New: Formatter v2

[ilyavolodin]

This would be a major breaking change, that will affect all integrations. I don't think it's justified at all. I think it would be better to do it the other way around. Introduce CLIEngineAsync with async properties, and keep existing CLIEngine synchronous. In that case, it will be a non-breaking change.

[mysticatea]

There is the reason I didn't write reverse.

• Dynamic loading of ES modules requires asynchronous API. Migrating to asynchronous API opens up doors to write plugins/configs with ES modules.
• Linting in parallel requires asynchronous API. We can improve linting logic to run it in parallel. And we can improve config loading logic and file enumeration logic to run it in parallel. (E.g., load extends list, traverse child directories.)

Multiple functionalities require async API and sync API looks closing doors for the future.

[ilyavolodin]

The opposite is also true:
Async APIs make tracing and debugging significantly harder, can lead to a lot more unforeseen errors and, in some cases, significantly raise complexity in submitting small fixes.
Sorry, I do not find your first bullet point compelling at all. Being able to write plugins/configs with ES modules is nice, but by no means critical from my perspective, especially given that ES modules in Node are still behind the flag, and require other concessions like using mjs file extensions.

[mysticatea]

In fact, don't you think you want to add the parallel linting feature? The parallel linting requires async API and your statement sounds to strongly oppose it.

[ilyavolodin]

No, you are misunderstanding me. I'm not against introduction of async API. I just don't think it should be default API that we expose, as it would be a huge breaking change, and I don't see enough justification for it. I'm perfectly fine with leaving default API as sync, and introducing a new async API as optional. Parallel linting doesn't require async API, it would make things a lot simple, but it can be achieved without async API.

[mysticatea]

Thank you for clarification.

How about adding a new class and deprecating CLIEngine?
Maybe the name of the new class is ESLint and it has async API.

I remember the name of CLIEngine causes large confusion to the community. People try Linter class at first, then they notice it doesn't work as expected. We have a lot of issues that say "please use CLIEngine instead."

Parallel linting doesn't require async API, it would make things a lot simple, but it can be achieved without async API.

Out of curiosity, how can we implement it? As far as I know, worker_threads module has the event-based API. I'm not sure how we use it in sync API.

[ilyavolodin]

I think deprecating CLIEngine is a better path forward. It would still be a breaking change, but as long as we keep CLIEngine around, it will not break existing integrations.
In terms of how to implement parallel linting, to clarify, you do need some functions to be converted to async, basically everything that comes before forking needs to be async, but everything inside the forks can stay sync. Also, just because it has to be async, doesn't mean we can't do it side-by-side with sync functions, and keep sync functions as default.

[mysticatea]

I got it. Thank you for your feedback. I'm rewriting this RFC.

[mysticatea]

I have updated this RFC.

[ilyavolodin]

I think this approach is much better direction then before. But I still wonder if alternative that you mention would be even easier approach?

[mysticatea]

I updated this RFC as changing getFormatter() to use streams.

[mysticatea]

I updated this RFC as reconsider some methods with Async Iteration.

• Now the executeOnFiles() method returns AsyncIterator<LintResult> instead of Promise<LintResult[]>. Therefore, in the future, we should be able to support formatters that print progress state without more breaking changes.
• The getFormatter() method returns a promise object that will be fulfilled with a formatter. Now the formatter type is (results: AsyncIterator<LintResult>) => AsyncIterator<string>. The adapter for the current formatter spec is this code. In the future, we should be able to support the formatter that does streaming output without more breaking changes, as updating the adapter.
• I have added more description, especially, what the API change gives us.

[platinumazure]

Looks pretty good so far. I'll continue to follow this discussion.

[mysticatea]

I updated this RFC.

• Now we can use the executeOnFiles() method along with both async expressions and for-await-of statements. It would be convenient in the cases that users want to get the lint results at once.
• Now the two methods executeOnFiles() and executeOnText() have the same return type. This inherits CLIEngine's manner.
• I added ESLint.compareResultsByFilePath() static method in order to sort the lint results in a stable order because I thought it's a common use-case.