feat: support explicit resource management in core rules (#19828)

DMartens · web-flow · commit 1245000c5a81 · 2025-07-17T16:12:24.000+05:30
diff --git a/docs/src/rules/no-await-in-loop.md b/docs/src/rules/no-await-in-loop.md
@@ -111,6 +111,12 @@ async function foo(things) {
   }
   return results;
 }
+
+async function bar(things) {
+  for (const thing of things) {
+    await using resource = getAsyncResource(thing);
+  }
+}
 ```
 
 :::
diff --git a/docs/src/rules/no-unused-vars.md b/docs/src/rules/no-unused-vars.md
@@ -142,6 +142,7 @@ By default this rule is enabled with `all` option for caught errors and variable
             "args": "after-used",
             "caughtErrors": "all",
             "ignoreRestSiblings": false,
+            "ignoreUsingDeclarations": false,
             "reportUsedIgnorePattern": false
         }]
     }
@@ -461,6 +462,34 @@ class Foo {
 
 :::
 
+### ignoreUsingDeclarations
+
+The `ignoreUsingDeclarations` option is a boolean (default: `false`). Explicit resource management allows automatic teardown of disposables by calling `Symbol.dispose` or `Symbol.asyncDispose` method implicitly at the end of the variable's scope. When this option is set to `true`, this rule ignores variables declared with `using` or `await using`.
+
+Examples of **incorrect** code for the `{ "ignoreUsingDeclarations": true }` option:
+
+::: incorrect
+
+```js
+/*eslint no-unused-vars: ["error", { "ignoreUsingDeclarations": true }]*/
+const resource = getResource();
+```
+
+:::
+
+Examples of **correct** code for the `{ "ignoreUsingDeclarations": true }` option:
+
+::: correct
+
+```js
+/*eslint no-unused-vars: ["error", { "ignoreUsingDeclarations": true }]*/
+
+using syncResource = getSyncResource();
+await using asyncResource = getAsyncResource();
+```
+
+:::
+
 ### reportUsedIgnorePattern
 
 The `reportUsedIgnorePattern` option is a boolean (default: `false`).
diff --git a/docs/src/rules/require-await.md b/docs/src/rules/require-await.md
@@ -71,6 +71,11 @@ bar(() => {
     doSomething();
 });
 
+async function resourceManagement() {
+    await using resource = getAsyncResource();
+    resource.use();
+}
+
 // Allow empty functions.
 async function noop() {}
 ```
diff --git a/lib/rules/no-await-in-loop.js b/lib/rules/no-await-in-loop.js
@@ -41,7 +41,10 @@ function isLooped(node, parent) {
 
 		case "ForOfStatement":
 		case "ForInStatement":
-			return node === parent.body;
+			return (
+				node === parent.body ||
+				(node === parent.left && node.kind === "await using")
+			);
 
 		case "WhileStatement":
 		case "DoWhileStatement":
@@ -76,6 +79,13 @@ module.exports = {
 		 * @returns {void}
 		 */
 		function validate(awaitNode) {
+			if (
+				awaitNode.type === "VariableDeclaration" &&
+				awaitNode.kind !== "await using"
+			) {
+				return;
+			}
+
 			if (awaitNode.type === "ForOfStatement" && !awaitNode.await) {
 				return;
 			}
@@ -99,6 +109,7 @@ module.exports = {
 		return {
 			AwaitExpression: validate,
 			ForOfStatement: validate,
+			VariableDeclaration: validate,
 		};
 	},
 };
diff --git a/lib/rules/no-unused-vars.js b/lib/rules/no-unused-vars.js
@@ -88,6 +88,9 @@ module.exports = {
 							ignoreClassWithStaticInitBlock: {
 								type: "boolean",
 							},
+							ignoreUsingDeclarations: {
+								type: "boolean",
+							},
 							reportUsedIgnorePattern: {
 								type: "boolean",
 							},
@@ -119,6 +122,7 @@ module.exports = {
 			ignoreRestSiblings: false,
 			caughtErrors: "all",
 			ignoreClassWithStaticInitBlock: false,
+			ignoreUsingDeclarations: false,
 			reportUsedIgnorePattern: false,
 		};
 
@@ -137,6 +141,9 @@ module.exports = {
 				config.ignoreClassWithStaticInitBlock =
 					firstOption.ignoreClassWithStaticInitBlock ||
 					config.ignoreClassWithStaticInitBlock;
+				config.ignoreUsingDeclarations =
+					firstOption.ignoreUsingDeclarations ||
+					config.ignoreUsingDeclarations;
 				config.reportUsedIgnorePattern =
 					firstOption.reportUsedIgnorePattern ||
 					config.reportUsedIgnorePattern;
@@ -357,6 +364,22 @@ module.exports = {
 			return false;
 		}
 
+		/**
+		 * Determines if a given variable uses the explicit resource management protocol.
+		 * @param {Variable} variable eslint-scope variable object.
+		 * @returns {boolean} True if the variable is declared with "using" or "await using"
+		 * @private
+		 */
+		function usesExplicitResourceManagement(variable) {
+			const [definition] = variable.defs;
+
+			return (
+				definition?.type === "Variable" &&
+				(definition.parent.kind === "using" ||
+					definition.parent.kind === "await using")
+			);
+		}
+
 		/**
 		 * Checks whether a node is a sibling of the rest property or not.
 		 * @param {ASTNode} node a node to check
@@ -922,6 +945,10 @@ module.exports = {
 					if (
 						!isUsedVariable(variable) &&
 						!isExported(variable) &&
+						!(
+							config.ignoreUsingDeclarations &&
+							usesExplicitResourceManagement(variable)
+						) &&
 						!hasRestSpreadSibling(variable)
 					) {
 						unusedVars.push(variable);
diff --git a/lib/rules/prefer-destructuring.js b/lib/rules/prefer-destructuring.js
@@ -293,6 +293,14 @@ module.exports = {
 				return;
 			}
 
+			// Variable declarations using explicit resource management cannot use destructuring (parse error)
+			if (
+				node.parent.kind === "using" ||
+				node.parent.kind === "await using"
+			) {
+				return;
+			}
+
 			// We only care about member expressions past this point
 			if (node.init.type !== "MemberExpression") {
 				return;
diff --git a/lib/rules/require-await.js b/lib/rules/require-await.js
@@ -170,6 +170,15 @@ module.exports = {
 					scopeInfo.hasAwait = true;
 				}
 			},
+			VariableDeclaration(node) {
+				if (!scopeInfo) {
+					return;
+				}
+
+				if (node.kind === "await using") {
+					scopeInfo.hasAwait = true;
+				}
+			},
 		};
 	},
 };
diff --git a/lib/rules/utils/ast-utils.js b/lib/rules/utils/ast-utils.js
@@ -47,6 +47,12 @@ const STATEMENT_LIST_PARENTS = new Set([
 	"StaticBlock",
 	"SwitchCase",
 ]);
+const LEXICAL_DECLARATION_KINDS = new Set([
+	"let",
+	"const",
+	"using",
+	"await using",
+]);
 
 const DECIMAL_INTEGER_PATTERN = /^(?:0|0[0-7]*[89]\d*|[1-9](?:_?\d)*)$/u;
 
@@ -2589,16 +2595,14 @@ module.exports = {
 	 */
 	areBracesNecessary(node, sourceCode) {
 		/**
-		 * Determines if the given node is a lexical declaration (let, const, function, or class)
+		 * Determines if the given node is a lexical declaration (let, const, using, await using, function, or class)
 		 * @param {ASTNode} nodeToCheck The node to check
 		 * @returns {boolean} True if the node is a lexical declaration
 		 * @private
 		 */
 		function isLexicalDeclaration(nodeToCheck) {
 			if (nodeToCheck.type === "VariableDeclaration") {
-				return (
-					nodeToCheck.kind === "const" || nodeToCheck.kind === "let"
-				);
+				return LEXICAL_DECLARATION_KINDS.has(nodeToCheck.kind);
 			}
 
 			return (
diff --git a/lib/types/rules.d.ts b/lib/types/rules.d.ts
@@ -4078,6 +4078,10 @@ export interface ESLintRules extends Linter.RulesRecord {
 					 * @default false
 					 */
 					ignoreClassWithStaticInitBlock: boolean;
+					/**
+					 * @default false
+					 */
+					ignoreUsingDeclarations: boolean;
 					/**
 					 * @default false
 					 */
diff --git a/tests/lib/rules/curly.js b/tests/lib/rules/curly.js
@@ -174,6 +174,22 @@ ruleTester.run("curly", rule, {
 			options: ["multi"],
 			languageOptions: { ecmaVersion: 6 },
 		},
+		{
+			code: "if (foo) { using bar = 'baz'; }",
+			options: ["multi"],
+			languageOptions: {
+				sourceType: "module",
+				ecmaVersion: 2026,
+			},
+		},
+		{
+			code: "if (foo) { await using bar = 'baz'; }",
+			options: ["multi"],
+			languageOptions: {
+				sourceType: "module",
+				ecmaVersion: 2026,
+			},
+		},
 		{
 			code: "while (foo) { let bar = 'baz'; }",
 			options: ["multi"],
diff --git a/tests/lib/rules/no-await-in-loop.js b/tests/lib/rules/no-await-in-loop.js
@@ -50,6 +50,39 @@ ruleTester.run("no-await-in-loop", rule, {
 
 		// Asynchronous iteration intentionally
 		"async function foo() { for await (var x of xs) { await f(x) } }",
+
+		// Explicit Resource Management
+		"while (true) { const value = 0; }",
+		"while (true) { let value = 0; }",
+		"while (true) { var value = 0; }",
+		{
+			code: "await using resource = getResource();",
+			languageOptions: {
+				sourceType: "module",
+				ecmaVersion: 2026,
+			},
+		},
+		{
+			code: "while (true) { using resource = getResource(); }",
+			languageOptions: {
+				sourceType: "module",
+				ecmaVersion: 2026,
+			},
+		},
+		{
+			code: "async function foo() { while (true) { async function foo() { await using resource = getResource(); } } }",
+			languageOptions: {
+				sourceType: "module",
+				ecmaVersion: 2026,
+			},
+		},
+		{
+			code: "for (await using resource = getResource(); ;) {}",
+			languageOptions: {
+				sourceType: "module",
+				ecmaVersion: 2026,
+			},
+		},
 	],
 	invalid: [
 		// While loops
@@ -123,5 +156,31 @@ ruleTester.run("no-await-in-loop", rule, {
 			code: "async function foo() { for await (var x of xs) { while (1) await f(x) } }",
 			errors: [error],
 		},
+
+		// Explicit Resource Management
+		{
+			code: "while (true) { await using resource = getResource(); }",
+			languageOptions: {
+				sourceType: "module",
+				ecmaVersion: 2026,
+			},
+			errors: [{ ...error, type: "VariableDeclaration" }],
+		},
+		{
+			code: "for (;;) { await using resource = getResource(); }",
+			languageOptions: {
+				sourceType: "module",
+				ecmaVersion: 2026,
+			},
+			errors: [{ ...error, type: "VariableDeclaration" }],
+		},
+		{
+			code: "for (await using resource of resources) {}",
+			languageOptions: {
+				sourceType: "module",
+				ecmaVersion: 2026,
+			},
+			errors: [{ ...error, type: "VariableDeclaration" }],
+		},
 	],
 });
diff --git a/tests/lib/rules/no-inner-declarations.js b/tests/lib/rules/no-inner-declarations.js
@@ -52,6 +52,22 @@ ruleTester.run("no-inner-declarations", rule, {
 			options: ["both"],
 			languageOptions: { ecmaVersion: 6 },
 		},
+		{
+			code: "if (test) { using x = 1; }",
+			options: ["both"],
+			languageOptions: {
+				ecmaVersion: 2026,
+				sourceType: "module",
+			},
+		},
+		{
+			code: "if (test) { await using x = 1; }",
+			options: ["both"],
+			languageOptions: {
+				ecmaVersion: 2026,
+				sourceType: "module",
+			},
+		},
 		"function doSomething() { while (test) { var foo; } }",
 		{ code: "var foo;", options: ["both"] },
 		{ code: "var foo = 42;", options: ["both"] },
diff --git a/tests/lib/rules/no-undef-init.js b/tests/lib/rules/no-undef-init.js
@@ -37,6 +37,13 @@ ruleTester.run("no-undef-init", rule, {
 			code: "class C { field = undefined; }",
 			languageOptions: { ecmaVersion: 2022 },
 		},
+		{
+			code: "using a = condition ? getDisposableResource() : undefined;",
+			languageOptions: {
+				ecmaVersion: 2026,
+				sourceType: "module",
+			},
+		},
 	],
 	invalid: [
 		{
diff --git a/tests/lib/rules/no-unused-vars.js b/tests/lib/rules/no-unused-vars.js
diff --git a/tests/lib/rules/no-var.js b/tests/lib/rules/no-var.js
diff --git a/tests/lib/rules/prefer-const.js b/tests/lib/rules/prefer-const.js
diff --git a/tests/lib/rules/prefer-destructuring.js b/tests/lib/rules/prefer-destructuring.js
diff --git a/tests/lib/rules/require-await.js b/tests/lib/rules/require-await.js

Original file line number	Diff line number	Diff line change
`@@ -111,6 +111,12 @@ async function foo(things) {`
`111`	`111`	`}`
`112`	`112`	`return results;`
`113`	`113`	`}`
	`114`	`+`
	`115`	`+async function bar(things) {`
	`116`	`+ for (const thing of things) {`
	`117`	`+ await using resource = getAsyncResource(thing);`
	`118`	`+ }`
	`119`	`+}`
`114`	`120`	```
`115`	`121`
`116`	`122`	`:::`