Skip to content

Commit 1558cbe

Browse files
axetroysindresorhusfregantefisker
authored
Add prefer-global-this rule (#2410)
Co-authored-by: Sindre Sorhus <[email protected]> Co-authored-by: Federico Brigante <[email protected]> Co-authored-by: fisker <[email protected]>
1 parent a5d5562 commit 1558cbe

7 files changed

+1710
-0
lines changed

‎docs/rules/prefer-global-this.md

+76
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Prefer `globalThis` over `window`, `self`, and `global`
2+
3+
💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/sindresorhus/eslint-plugin-unicorn#preset-configs-eslintconfigjs).
4+
5+
🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
6+
7+
<!-- end auto-generated rule header -->
8+
<!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
9+
10+
This rule will enforce the use of `globalThis` over `window`, `self`, and `global`.
11+
12+
However, there are several exceptions that remain permitted:
13+
14+
1. Certain window/WebWorker-specific APIs, such as `window.innerHeight` and `self.postMessage`
15+
2. Window-specific events, such as `window.addEventListener('resize')`
16+
17+
The complete list of permitted APIs can be found in the rule's [source code](../../rules/prefer-global-this.js).
18+
19+
## Examples
20+
21+
```js
22+
window; // ❌
23+
globalThis; // ✅
24+
```
25+
26+
```js
27+
window.foo; // ❌
28+
globalThis.foo; // ✅
29+
```
30+
31+
```js
32+
window[foo]; // ❌
33+
globalThis[foo]; // ✅
34+
```
35+
36+
```js
37+
global; // ❌
38+
globalThis; // ✅
39+
```
40+
41+
```js
42+
global.foo; // ❌
43+
globalThis.foo; // ✅
44+
```
45+
46+
```js
47+
const {foo} = window; // ❌
48+
const {foo} = globalThis; // ✅
49+
```
50+
51+
```js
52+
window.location; // ❌
53+
globalThis.location; // ✅
54+
55+
window.innerWidth; // ✅ (Window specific API)
56+
window.innerHeight; // ✅ (Window specific API)
57+
```
58+
59+
```js
60+
window.navigator; // ❌
61+
globalThis.navigator; // ✅
62+
```
63+
64+
```js
65+
self.postMessage('Hello'); // ✅ (Web Worker specific API)
66+
self.onmessage = () => {}; // ✅ (Web Worker specific API)
67+
```
68+
69+
```js
70+
window.addEventListener('click', () => {}); // ❌
71+
globalThis.addEventListener('click', () => {}); // ✅
72+
73+
window.addEventListener('resize', () => {}); // ✅ (Window specific event)
74+
window.addEventListener('load', () => {}); // ✅ (Window specific event)
75+
window.addEventListener('unload', () => {}); // ✅ (Window specific event)
76+
```

‎readme.md

+1
Original file line numberDiff line numberDiff line change
@@ -190,6 +190,7 @@ If you don't use the preset, ensure you use the same `env` and `parserOptions` c
190190
| [prefer-dom-node-text-content](docs/rules/prefer-dom-node-text-content.md) | Prefer `.textContent` over `.innerText`. | ✅ | | 💡 |
191191
| [prefer-event-target](docs/rules/prefer-event-target.md) | Prefer `EventTarget` over `EventEmitter`. | ✅ | | |
192192
| [prefer-export-from](docs/rules/prefer-export-from.md) | Prefer `export…from` when re-exporting. | ✅ | 🔧 | 💡 |
193+
| [prefer-global-this](docs/rules/prefer-global-this.md) | Prefer `globalThis` over `window`, `self`, and `global`. | ✅ | 🔧 | |
193194
| [prefer-includes](docs/rules/prefer-includes.md) | Prefer `.includes()` over `.indexOf()`, `.lastIndexOf()`, and `Array#some()` when checking for existence or non-existence. | ✅ | 🔧 | 💡 |
194195
| [prefer-json-parse-buffer](docs/rules/prefer-json-parse-buffer.md) | Prefer reading a JSON file as a buffer. | | 🔧 | |
195196
| [prefer-keyboard-event-key](docs/rules/prefer-keyboard-event-key.md) | Prefer `KeyboardEvent#key` over `KeyboardEvent#keyCode`. | ✅ | 🔧 | |

‎rules/prefer-global-this.js

+210
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
'use strict';
2+
3+
const MESSAGE_ID_ERROR = 'prefer-global-this/error';
4+
const messages = {
5+
[MESSAGE_ID_ERROR]: 'Prefer `globalThis` over `{{value}}`.',
6+
};
7+
8+
const globalIdentifier = new Set(['window', 'self', 'global']);
9+
10+
const windowSpecificEvents = new Set([
11+
'resize',
12+
'blur',
13+
'focus',
14+
'load',
15+
'scroll',
16+
'scrollend',
17+
'wheel',
18+
'beforeunload', // Browsers might have specific behaviors on exactly `window.onbeforeunload =`
19+
'message',
20+
'messageerror',
21+
'pagehide',
22+
'pagereveal',
23+
'pageshow',
24+
'pageswap',
25+
'unload',
26+
]);
27+
28+
/**
29+
Note: What kind of API should be a windows-specific interface?
30+
31+
1. It's directly related to window (✅ window.close())
32+
2. It does NOT work well as globalThis.x or x (✅ window.frames, window.top)
33+
34+
Some constructors are occasionally related to window (like Element !== iframe.contentWindow.Element), but they don't need to mention window anyway.
35+
36+
Please use these criteria to decide whether an API should be added here. Context: https://github.com/sindresorhus/eslint-plugin-unicorn/pull/2410#discussion_r1695312427
37+
*/
38+
const windowSpecificAPIs = new Set([
39+
// Properties and methods
40+
// https://html.spec.whatwg.org/multipage/nav-history-apis.html#the-window-object
41+
'name',
42+
'locationbar',
43+
'menubar',
44+
'personalbar',
45+
'scrollbars',
46+
'statusbar',
47+
'toolbar',
48+
'status',
49+
'close',
50+
'closed',
51+
'stop',
52+
'focus',
53+
'blur',
54+
'frames',
55+
'length',
56+
'top',
57+
'opener',
58+
'parent',
59+
'frameElement',
60+
'open',
61+
'originAgentCluster',
62+
'postMessage',
63+
64+
// Events commonly associated with "window"
65+
...[...windowSpecificEvents].map(event => `on${event}`),
66+
67+
// To add/remove/dispatch events that are commonly associated with "window"
68+
// https://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-flow
69+
'addEventListener',
70+
'removeEventListener',
71+
'dispatchEvent',
72+
73+
// https://dom.spec.whatwg.org/#idl-index
74+
'event', // Deprecated and quirky, best left untouched
75+
76+
// https://drafts.csswg.org/cssom-view/#idl-index
77+
'screen',
78+
'visualViewport',
79+
'moveTo',
80+
'moveBy',
81+
'resizeTo',
82+
'resizeBy',
83+
'innerWidth',
84+
'innerHeight',
85+
'scrollX',
86+
'pageXOffset',
87+
'scrollY',
88+
'pageYOffset',
89+
'scroll',
90+
'scrollTo',
91+
'scrollBy',
92+
'screenX',
93+
'screenLeft',
94+
'screenY',
95+
'screenTop',
96+
'screenWidth',
97+
'screenHeight',
98+
'devicePixelRatio',
99+
]);
100+
101+
const webWorkerSpecificAPIs = new Set([
102+
// https://html.spec.whatwg.org/multipage/workers.html#the-workerglobalscope-common-interface
103+
'addEventListener',
104+
'removeEventListener',
105+
'dispatchEvent',
106+
107+
'self',
108+
'location',
109+
'navigator',
110+
'onerror',
111+
'onlanguagechange',
112+
'onoffline',
113+
'ononline',
114+
'onrejectionhandled',
115+
'onunhandledrejection',
116+
117+
// https://html.spec.whatwg.org/multipage/workers.html#dedicated-workers-and-the-dedicatedworkerglobalscope-interface
118+
'name',
119+
'postMessage',
120+
'onconnect',
121+
]);
122+
123+
/**
124+
Check if the node is a window-specific API.
125+
126+
@param {import('estree').MemberExpression} node
127+
@returns {boolean}
128+
*/
129+
const isWindowSpecificAPI = node => {
130+
if (node.type !== 'MemberExpression') {
131+
return false;
132+
}
133+
134+
if (node.object.name !== 'window' || node.property.type !== 'Identifier') {
135+
return false;
136+
}
137+
138+
if (windowSpecificAPIs.has(node.property.name)) {
139+
if (['addEventListener', 'removeEventListener', 'dispatchEvent'].includes(node.property.name) && node.parent.type === 'CallExpression' && node.parent.callee === node) {
140+
const argument = node.parent.arguments[0];
141+
return argument && argument.type === 'Literal' && windowSpecificEvents.has(argument.value);
142+
}
143+
144+
return true;
145+
}
146+
147+
return false;
148+
};
149+
150+
/**
151+
@param {import('estree').Identifier} identifier
152+
@returns {boolean}
153+
*/
154+
function isComputedMemberExpressionObject(identifier) {
155+
return identifier.parent.type === 'MemberExpression' && identifier.parent.computed && identifier.parent.object === identifier;
156+
}
157+
158+
/**
159+
Check if the node is a web worker specific API.
160+
161+
@param {import('estree').MemberExpression} node
162+
@returns {boolean}
163+
*/
164+
const isWebWorkerSpecificAPI = node => node.type === 'MemberExpression' && node.object.name === 'self' && node.property.type === 'Identifier' && webWorkerSpecificAPIs.has(node.property.name);
165+
166+
/** @param {import('eslint').Rule.RuleContext} context */
167+
const create = context => ({
168+
* Program(program) {
169+
const scope = context.sourceCode.getScope(program);
170+
171+
const references = [
172+
// Variables declared at globals options
173+
...scope.variables.flatMap(variable => globalIdentifier.has(variable.name) ? variable.references : []),
174+
// Variables not declared at globals options
175+
...scope.through.filter(reference => globalIdentifier.has(reference.identifier.name)),
176+
];
177+
178+
for (const {identifier} of references) {
179+
if (
180+
isComputedMemberExpressionObject(identifier)
181+
|| isWindowSpecificAPI(identifier.parent)
182+
|| isWebWorkerSpecificAPI(identifier.parent)
183+
) {
184+
continue;
185+
}
186+
187+
yield {
188+
node: identifier,
189+
messageId: MESSAGE_ID_ERROR,
190+
data: {value: identifier.name},
191+
fix: fixer => fixer.replaceText(identifier, 'globalThis'),
192+
};
193+
}
194+
},
195+
});
196+
197+
/** @type {import('eslint').Rule.RuleModule} */
198+
module.exports = {
199+
create,
200+
meta: {
201+
type: 'suggestion',
202+
docs: {
203+
description: 'Prefer `globalThis` over `window`, `self`, and `global`.',
204+
recommended: true,
205+
},
206+
fixable: 'code',
207+
hasSuggestions: false,
208+
messages,
209+
},
210+
};

‎test/package.mjs

+1
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ const RULES_WITHOUT_PASS_FAIL_SECTIONS = new Set([
3232
'prefer-modern-math-apis',
3333
'prefer-math-min-max',
3434
'consistent-existence-index-check',
35+
'prefer-global-this',
3536
]);
3637

3738
test('Every rule is defined in index file in alphabetical order', t => {

0 commit comments

Comments
 (0)