doc: document globalThis TC39 stage 3 proposal #27399
Conversation
Make the node-core/required-modules eslint rule smart enough to recognize that `import '../common/index.mjs'` in ESM files imports the mandatory 'common' module.
Document `globalThis` from the TC39 stage 3 proposal and doc-deprecate `global`. It's been available since V8 7.0 and Node.js v11.0.0. Float a one-line patch on top of eslint for the moment to teach it about the new global. I'll be opening an upstream pull request in tandem with this change. Refs: https://github.com/tc39/proposal-global
|
|
||
| <!-- type=global --> | ||
|
|
||
| > Stability: 0 - Deprecated: Use [`globalThis)`][] instead. |
There was a problem hiding this comment.
Has the project decided to deprecate global now that globalThis is available?
I think there are still cases global is useful - in particular I've seen it used when probing for an environment that is Node.js and not "universal JavaScript".
There was a problem hiding this comment.
I personally have never seen code that checks for the presence of global, it's always if (typeof process === 'object'), but doc-deprecating it won't break that.
The motivation for deprecation is that there should be One Way To Do It. globalThis seems strictly superior since it works in node and modern browsers.
There was a problem hiding this comment.
Definitely don’t deprecate global; it’s so heavily used that it isn’t web compatible to name globalThis global :-)
In other words, there are many millions of examples in GitHub code search alone of code that does this.
There was a problem hiding this comment.
I agree it’s not possible to runtime deprecate global at this point but this document only doc-deprecate it? We may come back revisiting it or it could just stay doc deprecated forever but this sends a message to developers that they should use globalThis instead in new code.
There was a problem hiding this comment.
I don’t think the message is needed. If they want to write universal code, they either can already rely on “every single bundler” handling global transparently for them, or they can use globalThis that works in both.
I just don’t think there’s any value or need to push people in a direction here.
|
|
||
| * {Object} The global namespace object. | ||
|
|
||
| ## globalThis |
There was a problem hiding this comment.
I'm not sure we should document this as it's a JavaScript global.
Everything else in globals.md is a Node.js specific global that is not available in "plain" JavaScript. That is - nothing else here is defined in the ECMAScript spec (we don't list Array, String etc here for example).
There was a problem hiding this comment.
well it's currently not in ecma262, it's still stage 3
There was a problem hiding this comment.
I would suggest holding off for the time being
| @@ -0,0 +1,11 @@ | |||
| 'use strict'; | |||
|
|
|||
| require('../common'); | |||
There was a problem hiding this comment.
I am also not sure why we need a test for this as we don't have tests for other JavaScript features.
There was a problem hiding this comment.
One reason is that it'll block this PR from accidentally getting back-ported to release branches that don't have globalThis. But really it's because I figured some extra sanity checks won't hurt.
|
|
||
| <!-- type=global --> | ||
|
|
||
| > Stability: 0 - Deprecated: Use [`globalThis)`][] instead. |
There was a problem hiding this comment.
This should also have a deprecation code filed in deprecations.md.
|
I'm unsure that deprecating cc @ljharb Who I think worked on the |
|
|
||
| <!-- type=global --> | ||
|
|
||
| > Stability: 0 - Deprecated: Use [`globalThis)`][] instead. |
There was a problem hiding this comment.
Definitely don’t deprecate global; it’s so heavily used that it isn’t web compatible to name globalThis global :-)
In other words, there are many millions of examples in GitHub code search alone of code that does this.
|
I'll close this. The point of this PR is to steer people towards the standard solution rather than the node-specific one. Doc-deprecating |
Document
globalThisfrom the TC39 stage 3 proposal and doc-deprecateglobal. It's been available since V8 7.0 and Node.js v11.0.0.Float a one-line patch on top of eslint for the moment to teach it about
the new global. I'll be opening an upstream pull request in tandem with
this change.
Refs: https://github.com/tc39/proposal-global