This release comes just a few months after the v3 release due to the much faster than expected turnaround on optional chaining by ESTree. Read on for more details!
Summary of Changes
- feat: support new ESTree optional chaining representation (#2308) (a4bd2a8)
- feat: consume new scope analysis package (#2039) (abb0617)
- feat(eslint-plugin): [ban-ts-comment] change default for
- feat(eslint-plugin): [typedef] remove all default options (#2352) (13bd4dd)
- fix: correct decorator traversal for AssignmentPattern (#2375) (5ab473c)
- feat(eslint-plugin): [no-unnecessary-condition][strict-boolean-expressions] add option to make the rules error on files without
strictNullChecksturned on (#2345) (ee5b194)
- feat(typescript-estree): switch to globby (#2418) (789c439)
- feat(eslint-plugin): add
consistent-type-importsrule (#2367) (ba9295b)
- feat: add
downlevel-dtsto all packages with type declarations (a257183)
- feat(eslint-plugin): add extension rule
- feat(eslint-plugin): add extension rule
Support official ESTree optional chaining syntax (#2204)
When TS 3.7 released with optional chaining in November 2019, the feature was still a Stage-3 TC39 spec. This meant that ESTree did not yet have an official AST representation defined, as they only officially support Stage-4 specs.
This meant that we either had to block on TS 3.7 support, unofficially support optional chaining, or find an interim representation to use. As we had no clear timeframe around which both optional chaining would move to Stage-4, and when the ESTree AST for it would be defined, we decided the first two options were sub-optimal, and instead chose to the existing
babel-eslint AST representation. This representation has been in the ecosystem for a while and was supported by a variety of plugins.
Recently, ESTree agreed upon and merged an AST for optional chaining, which is vastly different to
babel-eslint's representation. ESLint and their parser
espree have already implemented and released support for this new AST as of ESLint
In order to correct course to match the future of the ecosystem, we've update our AST to match the new, official representation.
This means a few things right now:
- The ESLint core rules will have complete support for optional chaining, without need for extension rules
- you will need to upgrade to at least ESLint 7.5.0 in order to have support in lint rules
- Users might have to wait for plugins outside this project to update their logic to support this new AST.
Going forward, we're trying to be a bit more conservative with our choice of AST representation to help prevent this migration pain, at the cost of not being able to write lint rules for new features.
 ESTree is the AST representation used in the ESLint ecosystem (amongst other things). It's collectively governed by a number of projects. https://github.com/estree/estree/
decorators from nodes that TS doesn't support decorators on (#2375)
Previously, our parser would parse decorators and include them in the AST for
InterfaceDeclarations. This was originally done because the TypeScript parser treats these as syntactically valid for various reasons (the TS parser is incredibly permissive in what it allows!).
However, it's semantically invalid to have decorators for these nodes, and TypeScript will throw a semantic compile-time error. Whilst you can ignore this error with an ignore comment, TypeScript will ignore the decorator completely in the compiled output.
Additionally, babel's TypeScript parser will throw a parser error in these cases.
With this version, the parser will no longer include the
decorators property for the mentioned nodes.
Note that the parser will not error - it will just silently ignore the invalid decorators.
AST_NODE_TYPES.Import removed (#2375)
This was a cleanup item that was missed in the 3.0.0 release (#1950).
The underlying type was removed back then, so it's unlikely that anyone was still using this member.
TypeScript Scope Analysis (#2039)
You can read the full backstory behind this change in #1856.
In a nutshell, Scope Analysis is what enables ESLint to find and track variables as it traverses the AST. This information is consumed by rules like
With this release, we've forked ESLint's
eslint-scope package, and rebuilt it from the ground up to support TypeScript's functionality and dual-scope system.
This should mean that rules that rely upon scope analysis should all work properly, with no more false positives!
This has been marked as a breaking change for the following reasons:
- there may be some config changes required for existing rules,
- there are some new extension rules that have been added to better support TS that users will need to switch to:
- there will be
eslint-disablecomments that are now unnecessary, and may block your CI if you use ESLint's
- there will likely be a number of new lint errors as affected rules will now functioning correctly,
- some users may need to configure the new
parserOptions.liboption to ensure the global types are correctly defined for rules like
- some rules outside this project may have been implicitly relying upon the scope analyser not understanding TS types - meaning they may need some adjustments.
parserOptions.project glob resolution performance (#2418)
For configuration simplicity, we allow you to specify globs to
Some users provide globs like
./**/tsconfig.json. This sort of glob will match
node_modules and any
tsconfigs located in there (many packages do not maintain proper exclusion lists when publishing, so they publish unnecessary files like that). This is a problem for two reasons:
- it will cause us to find and parse additional, useless
- it will cause the glob handler to waste time traversing
The first issue we fixed a while ago with the
parserOptions.projectFolderIgnoreList option, which defaulted to ignore
node_modules. At the time due to some weirdness with the
glob package, we implemented a manual filter after the globs were resolved.
We never really thought about the second issue. However in some cases (when there are a large number of dependencies in
node_modules... so in most cases!) this can cause a significant performance impact.
On a medium-large node_modules folder, it can take ~3-1000ms to scan the directory. For correctness and safety reasons we have to do this scan every time ESLint asks us to parse a file, which obviously adds up over a lint run.
To fix this, we've changed the underlying package we use for glob resolution. This should change the total time we spend parsing globs during a lint run from
n is the number of files in the workspace) to more or less
O(1). For more information you can see the PR.
The breaking change that comes with this is as follows:
parserOptions.projectFolderIgnoreList accepted an array of
RegExp objects or regex strings.
Now it only accepts an array of strings, which must be glob strings. You'll have to translate your regexes to globs for them to continue working.
ban-ts-comment - change default for
ts-expect-error was added in TS 3.9. It's like
ts-ignore, but it's slightly less dangerous because if it suppresses no errors, then the comment itself becomes a compiler error.
Whilst completely banning the comment is "best practice", in real world use cases, you might have some valid cases that requires the comment.
Previously this would require code like the following:
// some comment describing why it's disabled // eslint-disable-next-line @typescript-eslint/ban-ts-comment // ts-expect-error const x = 1 as string;
The problem is that there's no way to enforce that there is a description detailing why the suppression comment is required.
With the new default the following is considered valid code:
// ts-expect-error: some comment describing why it's disabled const x = 1 as string;
This change makes the rule a little more flexible for real-world scenarios by banning most cases, and enforcing best practice of documenting suppressions when they're required.
typedef - remove all rule defaults (#2352)
For a long time we have discouraged using the
typedef rule. The rule exists for essentially one purpose: gradually migrating a weakly typed codebase to be stricter with the goal of enabling the
strictPropertyInitialization compiler options.
Outside of that use-case, this rule can be harmful to your codebase: explicitly annotating every single thing is known to cause performance issues with TypeScript, and maintaining all of those annotations can be a large maintenance burden.
This rule also often causes conflicts with other rules like
no-inferrable-types, which causes headaches for some setups.
We have removed all defaults from the rule to force users to explicitly "opt-in" to all functionality.
strict-boolean-expressions - report an error if
strictNullChecks is not turned on (#2345)
Both of these rules are driven off of inspecting nullability. Because of this, both rules will not work correctly if your project does not use the
strictNullChecks compiler option.
strictNullChecks, TypeScript essentially erases
null from the types. This means when this rule inspects the types from a variable, it will not be able to tell that the variable might be
undefined, which essentially makes this rule a lot less useful.
If for some reason you cannot turn on
strictNullChecks, but still want to use one of these rules - you can use the new
allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing option to allow it.
Note that the behavior of this rule is undefined with the compiler option turned off. We will not accept bug reports if you are using this option.
TypeScript 3.8 introduced type-only imports. This is an important feature for transpilers (like babel), as it allows them to very easily determine when an import/export can be excluded from the output code.
With the new scope analyser we've introduced in this version, we've enable a number of powerful abilities that were previously difficult or impossible for us to do.
This rule is an example of a use-case that was previously nearly impossible to do that is now relatively simple. This rule can help you ensure that any imports that are only used in type locations are properly declared as a type-only import.
It also includes a powerful fixer to help automatically separate your imports for you.
downlevel-dts to all packages with type declarations (a257183)
This is a minor change to ensure that our type declarations remain backwards compatible with older versions as we start to leverage new TS features.
We were already using
downlevel-dts in a few packages, this just increases the coverage to 100%.