The proposal introduces a unified mechanism to access the global this
in any JavaScript environment. It sounds like a simple thing to polyfill, but it turns out it’s pretty hard to get right. I didn’t even think it was possible until Toon blew my mind with an unexpected, creative solution.
This write-up describes the difficulties with writing a proper globalThis
polyfill. Such a polyfill has the following requirements:
But first, a note on terminology. globalThis
provides the value of this
in the global scope. This is different from the global object in web browsers, for complicated reasons.
Note that in JavaScript modules, there is a module scope intervening between the global scope and your code. The module scope hides the global scope’s this
value, so the this
value you see at the top-level in modules is actually undefined
.
TL;DR globalThis
is not “the global object”; it’s simply the this
from the global scope. Thanks to Domenic for helping me understand this important nuance.
globalThis
alternativesIn a browser, globalThis
is equivalent to window
:
globalThis === window;
// → true
<a href="https://html.spec.whatwg.org/multipage/window-object.html#dom-frames" target="_blank">frames</a>
works too:
globalThis === frames;
// → true
However, window
and frames
are undefined
within worker contexts (such as web workers and service workers). Luckily, self
works in all browser contexts and is thus a more robust alternative:
globalThis === self;
// → true
Neither window
, frames
, nor self
are available within Node.js, though. Instead, global
can be used:
globalThis === global;
// → true
None of the above (window
, frames
, self
, global
) are available in stand-alone JavaScript engine shells, such as the ones installed by <a href="https://github.com/GoogleChromeLabs/jsvu" target="_blank">jsvu</a>
. There, you can access the global this
:
globalThis === this;
// → true
Furthermore, sloppy mode functions always have their this
set to the global this
, so even if you cannot run your code in the global scope, you could still get access to the global this
as follows in sloppy mode:
globalThis === (function() {
return this;
})();
// → true
However, the top-level this
value is undefined
in JavaScript modules, and this
is undefined
within strict mode functions, so this approach doesn’t work there.
Once you’re in a strict mode context, there’s only one way to temporarily break out of it: the Function
constructor, which generates sloppy functions!
globalThis === Function('return this')();
// → true
Well, there’s two ways, since indirect eval
has the same effect:
globalThis === (0, eval)('this');
// → true
In web browsers, use of the Function
constructor and eval
is often disallowed using Content Security Policy (CSP). Websites often opt-in so such a policy, but it’s also enforced within Chrome extensions, for example. Unfortunately, this means that a proper polyfill cannot rely on the Function
constructor or eval
.
Note: setTimeout('globalThis = this', 0)
is ruled out for the same reason. In addition to commonly being blocked by CSP, there are two other reasons against using setTimeout
for a polyfill. First, it’s not part of ECMAScript, and not available in all JavaScript environments. Second, it’s asynchronous, so even if setTimeout
would be supported everywhere, it’d be painful to use in a polyfill on which other code depends.
It seems like it should be possible to combine the above techniques into a single polyfill, like so:
// A naive globalThis shim. Don’t use this!
const getGlobal = () => {
if (typeof globalThis !== 'undefined') return globalThis;
if (typeof self !== 'undefined') return self;
if (typeof window !== 'undefined') return window;
if (typeof global !== 'undefined') return global;
if (typeof this !== 'undefined') return this;
throw new Error('Unable to locate global object');
};
// Note: `var` is used instead of `const` to ensure `globalThis`
// becomes a global variable (as opposed to a variable in the
// top-level lexical scope) when running in the global scope.
var globalThis = getGlobal();
But alas, this doesn’t work in strict mode functions or within JavaScript modules in non-browser environments (except those with globalThis
support). In addition, getGlobal
could return an incorrect result, since it relies on this
which is context-dependent and could be altered by a bundler/packer.
Is it even possible to write a robust globalThis
polyfill? Assume an environment where:
globalThis
, window
, self
, global
, or this
;Function
constructor or eval
;It turns out there is a solution, but it’s not pretty. Let’s think about this for a minute.
How do we get access to the global this
without knowing how to access it directly? If we could somehow install a function property on the globalThis
, and call it as a method on the globalThis
, then we could access the this
from that function:
globalThis.foo = function() {
return this;
};
var globalThisPolyfilled = globalThis.foo();
How can we do something like that without relying on globalThis
or any host-specific binding that refers to it? We can’t just do the following:
function foo() {
return this;
}
var globalThisPolyfilled = foo();
foo()
is now no longer called as a method, and so its this
is undefined
in strict mode or in JavaScript modules as discussed above. Strict mode functions have their this
set to undefined
. However, this is not the case for getters and setters!
Object.defineProperty(globalThis, '__magic__', {
get: function() {
return this;
},
configurable: true // This makes it possible to `delete` the getter later.
});
// Note: `var` is used instead of `const` to ensure `globalThis`
// becomes a global variable (as opposed to a variable in the
// top-level lexical scope) when run in the global scope.
var globalThisPolyfilled = __magic__;
delete globalThis.__magic__;
The above program installs a getter on the globalThis
, accesses the getter to get a reference to the globalThis
, and then cleans up by deleting the getter. This technique gives us access to the globalThis
in all the desired circumstances, but it still relies on a reference to the global this
on the first line (where it says globalThis
). Can we avoid this dependency? How can we install a globally accessible getter without accessing the globalThis
directly?
Instead of installing the getter on globalThis
, we install it on something the global this
object inherits from — Object.prototype
:
Object.defineProperty(Object.prototype, '__magic__', {
get: function() {
return this;
},
configurable: true // This makes it possible to `delete` the getter later.
});
// Note: `var` is used instead of `const` to ensure `globalThis`
// becomes a global variable (as opposed to a variable in the
// top-level lexical scope).
var globalThis = __magic__;
delete Object.prototype.__magic__;
Note: The ECMAScript spec doesn’t actually mandate that the global this
inherit from Object.prototype
, only that it must be an object. Object.create(null)
creates an object that doesn’t inherit from Object.prototype
. A JavaScript engine could use such an object as the global this
without violating the spec, in which case the above code snippet still wouldn’t work (and indeed, Internet Explorer 7 did something like that!). Luckily, more modern JavaScript engines all seem to agree that the global this
must have Object.prototype
in its prototype chain.
To avoid mutating Object.prototype
in modern environments where globalThis
is already available, we can change the polyfill as follows:
(function() {
if (typeof globalThis === 'object') return;
Object.defineProperty(Object.prototype, '__magic__', {
get: function() {
return this;
},
configurable: true // This makes it possible to `delete` the getter later.
});
__magic__.globalThis = __magic__; // lolwat
delete Object.prototype.__magic__;
}());
// Your code can use `globalThis` now.
console.log(globalThis);
Alternatively, we could use __defineGetter__
:
(function() {
if (typeof globalThis === 'object') return;
Object.prototype.__defineGetter__('__magic__', function() {
return this;
});
__magic__.globalThis = __magic__; // lolwat
delete Object.prototype.__magic__;
}());
// Your code can use `globalThis` now.
console.log(globalThis);
And there you have it: the most horrifying polyfill you’ve ever seen! It completely defies the prevalent best practice to not modify objects you don’t own. Mucking with built-in prototypes is generally a bad idea, as explained in JavaScript engine fundamentals: optimizing prototypes.
On the other hand, the only way this polyfill can break is if someone manages to alter Object
or Object.defineProperty
(or Object.prototype.__defineGetter__
) before the polyfill code runs. I can’t think of a more robust solution. Can you?
The polyfill is a good an interesting example of universal JavaScript: it’s pure JavaScript code that does not rely on any host-specific built-ins, and therefore runs in any environment that implements ECMAScript. This was one of the goals of the polyfill in the first place! Let’s confirm that it actually works.
Here’s an HTML demo page for the polyfill that logs globalThis
using both a classic script <a href="https://mathiasbynens.be/demo/globalthis.js" target="_blank">globalthis.js</a>
and a module <a href="https://mathiasbynens.be/demo/globalthis.mjs" target="_blank">globalthis.mjs</a>
(with identical source code). This demo can be used to verify the polyfill works in browsers. globalThis
is natively supported in V8 v7.1 / Chrome 71, Firefox 65, Safari 12.1, and iOS Safari 12.2. To test the interesting parts of the polyfill, open the demo page in an older browser.
Note: The polyfill does not work in Internet Explorer 10 and older. In those browsers, the line __magic__.globalThis = __magic__
somehow doesn’t make globalThis
globally available, despite __magic__
being a working reference to the global this
. It turns out __magic__ !== window
although both are [object Window]
, indicating that these browsers might be confused about the distinction between the global object and the global <a href="https://mathiasbynens.be/notes/globalthis#terminology" target="_blank">this</a>
. Amending the polyfill to fall back to one of the alternatives makes it work in IE 10 and IE 9. For IE 8 support, wrap the call to Object.defineProperty
in a try
-catch
, similarly falling back in the catch
block. (Doing so also avoids the IE 7 issue with the global this
not inheriting from Object.prototype
.) Try the demo with old IE support.
To test in Node.js and standalone JavaScript engine binaries, download the very same JavaScript files:
# Download the polyfill + demo code as a module.
curl https://mathiasbynens.be/demo/globalthis.mjs > globalthis.mjs
# Create a copy (well, symlink) of the file, to be used as a classic script.
ln -s globalthis.mjs globalthis.js
Now we can test in node
:
$ node --experimental-modules --no-warnings globalthis.mjs
Testing the polyfill in a module
[object global]
$ node globalthis.js
Testing the polyfill in a classic script
[object global]
To test in a stand-alone JavaScript engine shell, use <a href="https://github.com/GoogleChromeLabs/jsvu" target="_blank">jsvu</a>
to install any desired engine, and then run the scripts directly. For example, to test in V8 v7.0 (without globalThis
support) and v7.1 (with globalThis
support):
$ jsvu v8@7.0 # Install the `v8-7.0.276` binary.
$ v8-7.0.276 globalthis.mjs
Testing the polyfill in a module
[object global]
$ v8-7.0.276 globalthis.js
Testing the polyfill in a classic script
[object global]
$ jsvu v8@7.1 # Install the `v8-7.1.302` binary.
$ v8-7.1.302 globalthis.js
Testing the polyfill in a classic script
[object global]
$ v8-7.1.302 globalthis.mjs
Testing the polyfill in a module
[object global]
The same technique allows us to test in JavaScriptCore, SpiderMonkey, Chakra, and other JavaScript engines such as XS as well. Here’s an example using JavaScriptCore:
$ jsvu # Install the `javascriptcore` binary.
$ javascriptcore globalthis.mjs
Testing the polyfill in a module
[object global]
$ javascriptcore globalthis.js
Testing the polyfill in a classic script
[object global]
Writing universal JavaScript can be tricky, and often calls for creative solutions. The new globalThis
feature makes it easier to write universal JavaScript that needs access to the global this
value. Polyfilling globalThis
correctly is more challenging than it seems, but there is a working solution.
Only use this polyfill when you really need to. JavaScript modules make it easier than ever to import and export functionality without altering global state, and most modern JavaScript code doesn’t need access to the global this
anyway. globalThis
is only useful for libraries and polyfills that do.
globalThis
polyfills on npmSince publishing this article, the following npm packages started providing globalThis
polyfills that make use of this technique:
<a href="https://github.com/ungap/global-this" target="_blank">@ungap/global-this</a>
<a href="https://github.com/medikoo/es5-ext/blob/master/global.js" target="_blank">es5-ext</a>
Disclaimer: I’m not the author, nor am I the maintainer, of any of these packages.
#javascript