Every single ECMAScript edition should have an "env" option

[ljharb]

es7/es2016 adds no new globals - that means that there's no "env" option for it.

This is confusing, because users don't know these details, and don't want to have to think about it - a user should be able to set their ecmaVersion and env to, say, "es2016" or "es2017" and have eslint do the Right Thing™.

If there are no new globals in a year, then great - es2016's globals are the same as es2015's - but that's not something the user writing the eslint config should have to care about.

(opening a new issue per #8453 (comment))

[not-an-aardvark]

Thanks for opening a new issue. This proposal seems reasonable to me. I'm a bit concerned that this could cause more confusion about the distinction between env and ecmaVersion, but that ship has probably sailed given that env: es6 already sets ecmaVersion: 6.

What would you expect to happen to the parser options if someone specifies multiple envs at once?

env:
  es2015: true
  es2017: true

[ljharb]

I would expect the same as if you currently set node and es6 to true - the union of both.

[not-an-aardvark]

I'm not sure the union of parserOptions: {ecmaVersion: 2015} and parserOptions: {ecmaVersion: 2017} is well-defined. I assume people would generally want that to mean parserOptions: {ecmaVersion: 2017}, but I think if we just added the additional envs and didn't do anything else, the behavior would end up being dependent on evaluation order.

[ljharb]

Ah, I misunderstood.

It should set the latest parserOptions available - or, combining multiple ES env values should be an error.

[MatthewHerbst]

In reverse, should setting a parserOption.ecmaVersion without setting an env for that (or a higher) version automatically set that env for you?

I'm a bit concerned that this could cause more confusion about the distinction between env and ecmaVersion, but that ship has probably sailed

I don't think it's too late to think about deprecating one of them. If the goal is to "do the Right Thing™" without making users worry about it, the two options aren't really needed, unless you think there is a legitimate case where the user would want the parser to recognize certain symbols, but not actually allow the linter to accept those symbols into its rule set.

[not-an-aardvark]

unless you think there is a legitimate case where the user would want the parser to recognize certain symbols, but not actually allow the linter to accept those symbols into its rule set.

I think it's important to distinguish between the "symbols" we're referring to here. parserOptions.ecmaVersion modifies allowed syntax (e.g. allowing async functions), whereas env modifies globals (e.g. Promise).

There are use cases for wanting one but not the other. For example, if a library is developed in ES2017 but is transpiled down to ES5 as a build step, its authors would want to allow ES2017 syntax because that syntax will be transpiled away. However, they would want to disallow ES6 globals, because those might not be present when the library is running.

Similarly, if an application uses a polyfill without transpiling, then its developers might want to allow ES6 globals (since those will be present from the polyfill), but disallow ES6 syntax (since that will cause a parsing error in ES5 environments).

[ljharb]

The conflict of "which parserOptions gets set" is already an issue if i'm using es2015 and es2017, because both have new globals and new syntax. I think it should be solved separately from this issue, which is only asking for "es2016" to exist (and future editions as well) even if they don't introduce new globals.

[not-an-aardvark]

The es2017 env doesn't exist yet, so it's not already a problem. I think the "which parserOptions gets set" question is a blocker for both issues.

[ljharb]

Gotcha.

In that case, since ES2017 was released in June, the problem is late being resolved by either 2 or 14 months, depending on the outcome of this issue :-/

I would not expect env to set parserOptions; i would expect parserOptions to set env; however I think it would be fine if neither set the other, and that might be the best approach here.

[not-an-aardvark]

This loosely relates to #8556. tl;dr: Part of the current behavior for overriding env is actually not working as originally designed, but it's internally consistent and a lot of people are now relying on it. Right now, I think explicitly setting parserOptions always overrides a value set by env, although we haven't had to deal with multiple envs setting conflicting parser options. (I'm not sure this affects the solution to the current issue, but I thought I'd bring it up.)

edit: There was also some discussion about this in #8291.

i would expect parserOptions to set env

I'm slightly averse to doing this because parser options are supposed to be parser-specific. For example, I think babel-eslint ignores ecmaVersion. Also, it seems like it could cause some breakage.

however I think it would be fine if neither set the other, and that might be the best approach here.

You may be right. Unfortunately, we probably can't ever remove the link between env: es6 and parserOptions, since too many configs are depending on it now. However, in theory we could avoid linking env: es7 and env: es8 to parserOptions.

It's worth noting that es6 is not the only env that affects parser options. The node and commonjs envs set parserOptions.ecmaFeatures.globalReturn to true (to allow return statements outside of functions).

[skylize]

The parserOptions setting should automatically assign a corresponding env' if env is not specified. The env setting should be essentially reserved for such special cases as described above, and env docs should state that most users should not need this setting. Average user should only need to define parserOptions and be done with it.

Edit: To clarify, my above comments are only referring to ecmaVersion-parserOptions and ecmascript-version-env settings, with no implications regarding other parserOptions or other env settings.

[not-an-aardvark]

Thanks for your thoughts @skylize. I have a few questions:

• What globals will be enabled if someone is using a custom parser that ignores the parserOptions.ecmaVersion setting? (I think babel-eslint does this.)
• What should happen to current users that are using parserOptions: { ecmaVersion: 6 } without any env? It seems like it would be a big breaking change to suddenly allow ES6 globals for that code, especially since people might not notice that anything stopped working until they find that their code is broken in ES5 environments.

[ljharb]

@not-an-aardvark in the next semver-major, it could be on by default; but for migration, it would be off by default?

[not-an-aardvark]

What do you mean by "off by default"? Isn't that the same thing as not implementing the feature until the next semver-major release? Or would there be another configuration flag to enable it?

[ljharb]

Ah, I'm still seeing this issue as for "there's an env for every edition" - I don't particularly care much what the implicit auto-opt-in behavior is :-)

[skylize]

@not-an-aardvark

What globals will be enabled if someone is using a custom parser that ignores the parserOptions.ecmaVersion setting? (I think babel-eslint does this.)

eslint generates list of ecmascript globals from env setting if it exists, else from parserOptions. I'll refer to this as es-globals. Parser is provided with es-globals and given chance to override with it's own globals. If parser fails to respond or responds with non-value, fall back to es-globals.

• What should happen to current users that are using parserOptions: { ecmaVersion: 6 } without any env?
  It seems like it would be a big breaking change to suddenly allow ES6 globals for that code, especially since people might not notice that anything stopped working until they find that their code is broken in ES5 environments.

What's the use for using specifying es6 parser to write es5 code? That seems counter-intuitive to me and likely to cause plenty of bugs even without this change. If there is valid reason to use such settings, then I guess we'll need an es5 option for env for this case, and a deprecation warning of some kind.

[not-an-aardvark]

Parser is provided with es-globals and given chance to override with it's own globals. If parser fails to respond or responds with non-value, fall back to es-globals.

This isn't really what parsers are for, and I don't think we should couple the two behaviors. Parsers just accept source text and output an AST -- they don't have anything to do with globals.

What's the use for using specifying es6 parser to write es5 code?

See #9109 (comment). It's fairly common for a library to write ES6 code and transpile it to ES5 with babel. Libraries like this can use ES6 syntax (since it will be transpiled anyway at build time), but they can't use ES5 globals (since they won't be available at runtime).

If there is valid reason to use such settings, then I guess we'll need an es5 option for env for this case

I don't think adding another env would help here. When multiple envs are enabled, all of the globals from both envs are applied.

and a deprecation warning of some kind.

What are we deprecating? It seems like this is just switching from one behavior to another behavior for a given configuration, so it doesn't seem like there is any configuration that would end up being deprecated.

[skylize]

@not-an-aardvark

This isn't really what parsers are for, and I don't think we should couple the two behaviors. Parsers just accept source text and output an AST -- they don't have anything to do with globals.

Okay, well that's fine. If the parser is not concerned with globals and ignores parserOptions.ecmaVersion then we can safely set it to anything without any parser side effects. For users with this case, they simply get to choose which setting to put.

Libraries like this can use ES6 syntax (since it will be transpiled anyway at build time), but they can't use ES5 globals (since they won't be available at runtime).
.> ..
I don't think adding another env would help here. When multiple envs are enabled, all of the globals from both envs are applied.

Okay, that usage makes sense. However it still seems pretty clear to me that ecmaVersion implies an environment of the same version. It should be up to the user who wants conflicting setings to say so, not up to the users who want settings that obviously go together. The default should not be the edge case.

An env.es5 option would allow people to explicitly request es5, freeing us to change the default behavior when no es env is specified because they can still get es5 only globals if needed. We can still fall back to es5 as a last resort if there is nothing in env or parserOptions to pull from.

What are we deprecating?

We're deprecating an implied setting, in favor of an explicit one.

"Setting globals to ES5 by not specifying an ES version in env is deprecated. If you need only ES5 globals you should specify "env": { "es5": true }."

We could introduce env.es5 as a non-breaking change with deprecation warning, setting up to change handling of 'unspecified es environment' in the next major release.

[not-an-aardvark]

However it still seems pretty clear to me that ecmaVersion implies an environment of the same version. It should be up to the user who wants conflicting settings to say so, not up to the users who want settings that obviously go together.

I'm unsure about this, especially given that ecmaVersion is under parserOptions. To me, that seems to imply that ecmaVersion is only used by the parser, and doesn't trigger special behavior relating to globals.

We could introduce env.es5 as a non-breaking change with deprecation warning, setting up to change handling of 'unspecified es environment' in the next major release.

I see what you mean, thanks for clarifying. So it would be less of a warning about a particular config behavior being deprecated, and more of a warning that the given config behavior will soon mean something else.

However, I'm unconvinced that this is actually better than just keeping parser options and globals completely separate. Conceptually, the options control two different things, so it seems reasonable to me that the two options should also be independent, rather than sometimes subtly depending on each other.

To throw another element into the mix: At some point in the future, we are probably going to enable parserOptions: { ecmaVersion: 6 } and env: es6 by default. When that happens, it won't be relevant that env: { es6: true } implicitly enables parserOptions: { ecmaVersion: 6 }, because both will be available by default anyway. If we want to decouple envs and parser options, we might be able to do it at that point.

[platinumazure]

Another possibility: Could we completely decouple envs and parser options, and instead create and publish shareable configs that will emulate those? (e.g., eslint-config-es6 would set parserOptions.ecmaVersion to 6 and enable the es6 globals)

Maybe envs are taking on too much responsibility and should be reimagined as global-sets, and we should use shareable configs as the convenience pieces.

[skylize]

@not-an-aardvark

I'm unsure about this, especially given that ecmaVersion is under parserOptions. To me, that seems to imply that ecmaVersion is only used by the parser, and doesn't trigger special behavior relating to globals.

I'm not saying that a setting called parserOptions.ecmaVersion set to 2017 seems on it's own to say anything about an env settings. What I am saying though, is that if you step back just a little and think about why someone would set parserOptions.ecmaVersion = 2017, it implies intent to write es2017 code, so we should provide defaults that fit with that implication, which can then be overwitten for the more complicated use cases..

However, I'm unconvinced that this is actually better than just keeping parser options and globals completely separate.

If we want to decouple envs and parser options, we might be able to do it at that point.

From your perspective, seeing these two things as clearly separate makes perfect sense because you understand the internal implemenation of eslint. Internally, parser has nothing to do with environment, so keep them separate. But I think you're failing to see what it looks like from the outside.

From an average user's perspective, it is "Why do I need to set es6 twice? )%&#_%()$&#)%)#!!!!!!!! put es2017 just like the docs, why won't it understand me?!?" Average joe has no idea how it works. He just writes up a settings file after scouring the docs, then feeds them into a magic box that spits out lints and expects it to work. The delineation between parser and environment has very little meaning until you try to look under the hood. They are just arbitrary names under which to apply some configs.

Underneath the hood, sure decouple them to your hearts content. I'm sure that makes things easier to understand and easier to maintain. This is basically just sugar for the most obvious cases.

[not-an-aardvark]

The delineation between parser and environment has very little meaning until you try to look under the hood. They are just arbitrary names under which to apply some configs.

I'm unconvinced about this. This is not just a concern about maintainability -- there are very common cases where users need to understand the difference between parser options and globals. (This applies when developing almost any library with Babel -- I don't think it's as much of an edge case as you're describing).

I like @platinumazure's solution of treating this like a config, since it allows new users to set a single flag without muddying the difference between parser options and envs. Rather than making them shareable, another option would be provide them as builtin configs like eslint:recommended (so you could use something like extends: 'eslint:es6' to enable globals and parsing for ES6, or you could use env: { es6: true } to just enable globals).

[skylize]

@not-an-aardvark

This is not just a concern about maintainability -- there are very common cases where users need to understand the difference between parser options and globals.

You're right, I'm probably overstating this by calling it an edge case. The solution I offered still leaves the decoupled nature of parserOptions and env in plain view when people move on to cases where they need to know the difference though. Specifically for babel as you point out, as soon as user sets an env, then ecmascript: 2017 becomes just a no-op. It's ignored for setting globals and ignored by parser.

like @platinumazure's solution of treating this like a config, since it allows new users to set a single flag without muddying the difference between parser options and envs.

I'm not a big fan of adding more places to put options here. We have enough options availiable already if we can just shift gears slightly to interpret them properly.

another option would be provide them as builtin configs like eslint:recommended (so you could use something like extends: 'eslint:es6' to enable globals and parsing for ES6,

I don't like this quite as well as the solution I suggested, but I think I could get behind it. This accomplishes the goal of reducing es version to a single setting for new users and simple cases, within an already existing namespace. 👍 I assume that explicitly setting env or parserOptions would override this without any problems?

[platinumazure]

I don't like this quite as well as the solution I suggested, but I think I could get behind it. This accomplishes the goal of reducing es version to a single setting for new users and simple cases, within an already existing namespace. 👍 I assume that explicitly setting env or parserOptions would override this without any problems?

Yes, that's part of the reason I recommended shareable configs (though I can get behind builtin configs as well). We also allow multiple inherited configs, as well. In fact, a config of "eslint:es6" (or whatever) would serve as the single setting that envs: { es6: true } currently supports, but with much less confusion.

[skylize]

@platinumazure

We also allow multiple inherited configs

Can you elaborate on what this means?

[platinumazure]

@skylize Basically, you can extend from multiple configurations:

{
    "extends": ["eslint:es6", "eslint-config-someconfig", "eslint-config-someotherconfig"],
    "parserOptions": {
        "ecmaVersion": 5
    }
}

Or your shared configs (eslint-config-someconfig, eslint-config-someotherconfig in the example above) could extend from "eslint:es6", given time to upgrade.

In the config above, parserOptions would be overwritten so you would be parsing ES5 code but having the ES6 globals available. (Not a common use case, I'm sure, but good for illustration.)

At the moment, I think there might be an issue where envs cannot actually be disabled by configs extending other configs-- but I think the reason was because of how some envs set parserOptions etc., so it wasn't always clear what should happen when an env was disabled. If an env is now just a set of globals and we use shareable or builtin configs to indicate ES6 parsing and globals simultaneously, we might be able to fix that too. Not 100% sure though.

[skylize]

@platinumazure Thanks for that description.

Is there any good reason besides legacy for having these coupled internally? Based on discussion so far, it seems to me these should definitely be fully decoupled under-the-hood. Any apparent coupling should be created later by an overlay of some kind to benefit specific use cases, whether that's configs, or sugar, or whatever.

[platinumazure]

@skylize I'm not 100% aware of the history but I think it's honestly just legacy. We took some of our original direction from JSHint which did all sorts of crazy crap like this, and shareable configurations were (compared to envs) a more recent innovation.

To be completely honest, I'm surprised nobody has thought to create configurations to replace the more tightly coupled envs before.

Maybe @not-an-aardvark and others will come up with a better way forward (especially if we can find a way to reduce pain of upgrading to our users). But I'm hoping that the upgrade pain will be outweighed by the significant reduction in confusion that I think this solution would promise.

[not-an-aardvark]

Yes, that's part of the reason I recommended shareable configs (though I can get behind builtin configs as well)

I suggested builtin configs because it seems like if we're worried about the UX impact of needing to set 2 config flags rather than 1, then needing to install a separate npm package would be a much bigger UX barrier.

---

I want to refocus the discussion for a second, with two questions:

1. Are we sure that decoupling env/parserOptions is needed to solve this problem?

   Based on Every single ECMAScript edition should have an "env" option #9109 (comment), the original problem was that the resulting parser options after using env: es6 and env: es8 would depend on the order of the env listing. But that would also be the case for something like extends: 'eslint:es6' or extends: 'eslint:es8'. On reconsideration, maybe it would be workable to just add an es8 option that also sets the parserOptions.

2. Should env/parserOptions should be decoupled in the long term?

   If we're ever going to decouple env and parserOptions, then I think we should do it when we enable ES6 parsing by default at some point in the future, because that will result in the smallest amount of problems for users. (For example, it won't matter that env: es6 no longer sets parserOptions: { ecmaVersion: 6 }, because parserOptions: { ecmaVersion: 6 } will be set by default anyway.)

The second question seems important for determining how to proceed with this issue. If we're planning to decouple env and parserOptions, then we should not tie env: es2017 to parserOptions: { ecmaVersion: 2017 }, because that would prevent us from easily switching over when we enable ES6 by default. On the other hand, if we're not planning to decouple env and parserOptions in the long term, then we probably should tie env: es2017 to parserOptions: { ecmaVersion: 2017 } for consistency with env: es6.

[skylize]

I feel like from this discussion and others I've skimmed across in the past, it's pretty clear that the coupling causes a lot of unnecessary pain, and the sooner we can be rid of it, the better for everybody. I think there are ways we could make the OP @ljharb happy without that decoupling, but it seems like just another band-aid on something that's due for surgery.

[ilyavolodin]

I'm not sure I understand the reason for wanting to decouple env / parserOptions. env controls the whole environment, that includes globals, language features, or let's say for example, browser specific features/variables. ecmaVersion controls only version of the language that needs to be parsed. Those two are decoupled under the hood. env just enabled ecmaVersion specified. Historically, we used to have environments even enable/disable rules at some point in the past.

I think the other point was already dropped earlier in the discussion, but I want to put my vote strongly against having ecmaFeatures enable specific env. You might want to be able to parse new language syntax, but not have all of the globals (for example, if you are using Babel, as far as I know, Proxies don't get transpiled all that well, so you might want to enable let and const, but not have Proxies). In my case, I'm forced to use a very outdated JS engine, that actually implements ES4, which means it has let and const but no ES6 global variables.

[MatthewHerbst]

@skylize for the record, I'm the original original OP 😄

Having followed the discussion for a while, I think a middle ground can be reached.

I agree with @not-an-aardvark that having the two decoupled can be extremely valuable to certain users. I also agree with @skylize that for most users, they just want to set the one thing and be done with it (i.e., they don't distinguish between using say es2018 globals and es6 syntax - usually because they have something like babel transpiring the syntax anyways).

I propose a middle ground solution:

I think part of the problem is that today, env is confusing. As @ilyavolodin notes above, env should control the entire environment. So, let's make that clear:

• env should be the single, well-document, Just Works^TM option that the average Joe/Mary user sets
  • Setting env to say, es2018 should allow both es2018 globals and es2018 syntax
• For power users:
  • The parserOptions should remain as is. Setting this value tells eslint to allow the syntax for that version, but says nothing about allowing globals from that version
  • A new option, globals, should be added. This will tell eslint to recognize the globals from a particular version
  • Setting both parserOptions and globals will cause env to be ignored
  • Setting only one of parserOptions or globals will cause the default for the other to be used
    • So, in the future case where we upgrade the defaults to es6, setting globals to es2018, but not setting parserOptions, will allow es2018 globals, but syntax will still be at es6
    • Similarly, setting parserOptions to es2018, but not setting globals, will allow es2018 syntax, will allow es2018 syntax, but globals will still be restricted to es6

I think this allows both the flexibility for power users that @not-an-aardvark desires, and the simplicity for average users that @skylize desires.

This does break the way env works in a big way, and it could be a bit painful in terms of reading docs (though no code other than configs should have to be changed) for users to upgrade to the new version. But I think the long-term durability and stability works for most stakeholders.

[not-an-aardvark]

Thanks for your thoughts @MatthewHerbst. To me, it seems like adding another option will just complicate things even more, because there will be more cases/defaults to deal with. My goal in discussing this is to make the options conceptually simpler, not to make them more flexible than they currently are. (Users can already control globals and parser options separately by using a combination of env and parserOptions -- I think the problem is that the mechanism to do this is confusing, because the options aren't fully independent of one another).

That's why I like extends as a solution that Just Works, since the semantics of extending shareable configs are already well-defined without needing to introduce a new type of behavior. However, if we're sure that we want to keep allowing env to define parser options, then I would rather just keep the status quo and introduce env: es2017 which also enables ES2017 parsing.

(For what it's worth, there is already a globals config option used for specifying individual globals, so if we went with your proposal we would probably need to pick a different name.)

[MatthewHerbst]

Ah, got it. I was under the impression that you were concerned the changes being proposed would make the existing options less flexible.

However, if we're sure that we want to keep allowing env to define parser options, then I would rather just keep the status quo and introduce env: es2017 which also enables ES2017 parsing.

I mean, having env: es2017 (and additional env values for all ES versions) is basically what my original original proposal asked for. I think that's a pretty reasonable and relatively easy solution to go with.

If we agree to go down that route, I'm more than happy to write that PR (I think two are needed, one for this lib, and one for the globals lib).

[skylize]

@MatthewHerbst Sorry for any confusion about who is OP. I am still not seeing your name on the opening post of this particular thread, but I'll take your word for it. ;😉

Ah, got it. I was under the impression that you were concerned the changes being proposed would make the existing options less flexible.

I think @not-an-aardvark's "What will happen in this case?" questions are mostly about ensuring we take all the implications of any changes into account when making a decision.

My goal in discussing this is to make the options conceptually simpler, not to make them more flexible than they currently are.

I agree with this strongly. Conceptual simplicity certainly improves maintainability, and it tends to provide flexibility as a natural byproduct.

[eslint-deprecated]

Unfortunately, it looks like there wasn't enough interest from the team
or community to implement this change. While we wish we'd be able to
accommodate everyone's requests, we do need to prioritize. We've found
that issues failing to reach accepted status after 21 days tend to
never be accepted, and as such, we close those issues.
This doesn't mean the idea isn't interesting or useful, just that it's
not something the team can commit to.

Thanks for contributing to ESLint and we appreciate your understanding.

[MatthewHerbst]

Can we re-open this? I think there is plenty of interest, but we're waiting on some upstream decision. For example, someone commenting on this PR in globals would be appreciated.

[ljharb]

Yes, let's please reopen this. It's very confusing to have a discontinuous set of editions.

[MatthewHerbst]

@ljharb any thoughts on the linked PR? RFC: Dynamically generate globals, drop 3rd party globals

[ljharb]

@MatthewHerbst not really, no; i don't use that package.

[MatthewHerbst]

ESLint uses that package. It's my understanding that ESLint is the primary consumer of that package. I think solving this issue greatly involves the globals package. cc @sindresorhus

[jsejcksn]

If it is decided to keep the association between env and parserOptions:

When env.es6 becomes the default environment, I propose to deprecate that attribute and replace it with env.ecmaVersion, which would be set to one of the same values as parserOptions.ecmaVersion.

It would set parserOptions.ecmaVersion to the matching value if one is not supplied.

For example, setting the version number:

{
  "env": {
    "ecmaVersion": 9
  }
}

would output

{
  "env": {
    "ecmaVersion": 9
  },
  "parserOptions": {
    "ecmaVersion": 9
  }
}

Using the year:

{
  "env": {
    "ecmaVersion": 2018
  }
}

would output

{
  "env": {
    "ecmaVersion": 2018
  },
  "parserOptions": {
    "ecmaVersion": 2018
  }
}