Skip to content

Commit 1558cbe

Browse files
axetroysindresorhusfregantefisker
authoredSep 29, 2024··
Add prefer-global-this rule (#2410)
Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com> Co-authored-by: Federico Brigante <me@fregante.com> Co-authored-by: fisker <lionkay@gmail.com>
·
v58.0.0v56.0.0
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 => {

‎test/prefer-global-this.mjs

+186
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
import {getTester} from './utils/test.mjs';
2+
import outdent from 'outdent';
3+
4+
const {test} = getTester(import.meta);
5+
6+
test.snapshot({
7+
valid: [
8+
'globalThis',
9+
'globalThis.foo',
10+
'globalThis[foo]',
11+
'globalThis.foo()',
12+
'const { foo } = globalThis',
13+
'function foo (window) {}',
14+
'function foo (global) {}',
15+
'var foo = function foo (window) {}',
16+
'var foo = function foo (global) {}',
17+
'var window = {}',
18+
'let global = {}',
19+
'const global = {}',
20+
outdent`
21+
function foo (window) {
22+
window.foo();
23+
}
24+
`,
25+
outdent`
26+
var window = {};
27+
function foo () {
28+
window.foo();
29+
}
30+
`,
31+
'foo.window',
32+
'foo.global',
33+
'import window from "xxx"',
34+
'import * as window from "xxx"',
35+
'import window, {foo} from "xxx"',
36+
'export { window } from "xxx"',
37+
'export * as window from "xxx";',
38+
outdent`
39+
try {
40+
41+
} catch (window) {}
42+
`,
43+
44+
// Use window specific APIs
45+
'window.name = "foo"',
46+
'window.addEventListener',
47+
'window.innerWidth',
48+
'window.innerHeight',
49+
'self.location',
50+
'self.navigator',
51+
'window.addEventListener("resize", () => {})',
52+
'window.onresize = function () {}',
53+
outdent`
54+
const {window} = jsdom()
55+
window.jQuery = jQuery;
56+
`,
57+
'({ foo: window.name } = {})',
58+
'[window.name] = []',
59+
'window[foo]',
60+
'window[title]',
61+
'window["foo"]',
62+
],
63+
invalid: [
64+
'global',
65+
'self',
66+
'window',
67+
'window.foo',
68+
'window.foo()',
69+
'window > 10',
70+
'10 > window',
71+
'window ?? 10',
72+
'10 ?? window',
73+
'window.foo = 123',
74+
'window = 123',
75+
'obj.a = window',
76+
outdent`
77+
function* gen() {
78+
yield window
79+
}
80+
`,
81+
outdent`
82+
async function gen() {
83+
await window
84+
}
85+
`,
86+
'window ? foo : bar',
87+
'foo ? window : bar',
88+
'foo ? bar : window',
89+
outdent`
90+
function foo() {
91+
return window
92+
}
93+
`,
94+
'new window()',
95+
outdent`
96+
const obj = {
97+
foo: window.foo,
98+
bar: window.bar,
99+
window: window
100+
}
101+
`,
102+
outdent`
103+
function sequenceTest() {
104+
let x, y;
105+
x = (y = 10, y + 5, window);
106+
console.log(x, y);
107+
}
108+
`,
109+
'window`Hello ${42} World`', // eslint-disable-line no-template-curly-in-string
110+
'tag`Hello ${window.foo} World`', // eslint-disable-line no-template-curly-in-string
111+
'var str = `hello ${window.foo} world!`', // eslint-disable-line no-template-curly-in-string
112+
'delete window.foo',
113+
'++window',
114+
'++window.foo',
115+
outdent`
116+
for (var attr in window) {
117+
118+
}
119+
`,
120+
outdent`
121+
for (window.foo = 0; i < 10; window.foo++) {
122+
123+
}
124+
`,
125+
outdent`
126+
for (const item of window.foo) {
127+
}
128+
`,
129+
outdent`
130+
for (const item of window) {
131+
}
132+
`,
133+
outdent`
134+
switch (window) {}
135+
`,
136+
outdent`
137+
switch (true) {
138+
case window:
139+
break;
140+
}
141+
`,
142+
outdent`
143+
switch (true) {
144+
case window.foo:
145+
break;
146+
}
147+
`,
148+
outdent`
149+
while (window) {
150+
}
151+
`,
152+
'do {} while (window) {}',
153+
'if (window) {}',
154+
'throw window',
155+
'var foo = window',
156+
outdent`
157+
function foo (name = window) {
158+
159+
}
160+
`,
161+
'self.innerWidth',
162+
'self.innerHeight',
163+
'window.crypto',
164+
'window.addEventListener("play", () => {})',
165+
'window.onplay = function () {}',
166+
'function greet({ name = window.foo }) {}',
167+
'({ foo: window.foo } = {})',
168+
'[window.foo] = []',
169+
'foo[window]',
170+
'foo[window.foo]',
171+
],
172+
});
173+
174+
test.snapshot({
175+
testerOptions: {
176+
languageOptions: {
177+
globals: {global: 'off', window: 'off', self: 'off'},
178+
},
179+
},
180+
valid: [],
181+
invalid: [
182+
'global.global_did_not_declare_in_language_options',
183+
'window.window_did_not_declare_in_language_options',
184+
'self.self_did_not_declare_in_language_options',
185+
],
186+
});

‎test/snapshots/prefer-global-this.mjs.md

+1,236
Large diffs are not rendered by default.

‎test/snapshots/prefer-global-this.mjs.snap

2.59 KB
Binary file not shown.

0 commit comments

Comments
 (0)
Please sign in to comment.