no-unused-properties: Support inline TypeScript object type literals (#3204)

sindresorhus · web-flow · commit ec77d4e0aaff · 2026-06-13T22:11:22.000+02:00
diff --git a/docs/rules/no-unused-properties.md b/docs/rules/no-unused-properties.md
@@ -13,7 +13,7 @@ This rule is primarily useful when you use objects to group constants or model e
 
 ## Example use cases
 
-When using [React](https://reactjs.org)'s inline styles or one of [many CSS-in-JS](https://michelebertoli.github.io/css-in-js/) like [glamor](https://github.com/threepointone/glamor), one might find it helpful to group component styles into a constant object. Later you might remove one of the styles, but forget to remove its definition, especially if the component grew in complexity by that time. If these were defined as separate constants, ESLint's builtin `no-unused-vars` rule would have helped, but they are not. That's when the `no-unused-properties` rules becomes useful.
+When using [React](https://reactjs.org)'s inline styles or one of [many CSS-in-JS](https://michelebertoli.github.io/css-in-js/) libraries like [glamor](https://github.com/threepointone/glamor), one might find it helpful to group component styles into a constant object. Later you might remove one of the styles, but forget to remove its definition, especially if the component grew in complexity by that time. If these were defined as separate constants, ESLint's built-in `no-unused-vars` rule would have helped, but they are not. That's when the `no-unused-properties` rule becomes useful.
 
 ```js
 const styles = {
@@ -48,6 +48,22 @@ console.log(myEnum.used);
 const {used} = myEnum;
 ```
 
+This rule also checks inline TypeScript object type literals attached directly to initialized variables and parameters.
+
+```ts
+// ❌
+function foo(args: {used: number; unused: number}) {
+	return args.used;
+}
+```
+
+```ts
+// ✅
+function foo(args: {used: number}) {
+	return args.used;
+}
+```
+
 ```js
 // ✅
 const myEnum = {
@@ -85,7 +101,7 @@ const foo = {
 
 This rule tries hard not to report potentially used properties as unused. Basically, all supported use cases are enum-like as shown above, more complex cases are ignored. Detailed list of limitations follows.
 
-- Does not predict dynamic property access. That is, `object[keys]` says that all properties of an object are potentially used. This is as unpredictable for this rule as `eval(...)` is for the `no-unused-vars` rule.
+- Does not predict dynamic property access. That is, `object[key]` says that all properties of an object are potentially used. This is as unpredictable for this rule as `eval(...)` is for the `no-unused-vars` rule.
 - Same goes for computed property keys in object definitions, like `{[key]: value}`.
 - If a variable is unused, it is not checked. This is done to play nicely with the `no-unused-vars` rule, which everybody should have enabled at all times.
 - Does not check objects used as an argument. If you call `f(object)`, it behaves like you used all of its properties, since it's hard to predict what a function would do with the object.
@@ -94,5 +110,6 @@ This rule tries hard not to report potentially used properties as unused. Basica
 - Classes are not checked.
 - Prototypes are not checked. Only own properties are.
 - Does not follow objects across files. If you export an object, it's like if you used all of its properties.
+- TypeScript support is limited to inline object type literals attached directly to initialized variables and parameters. Named type aliases, interfaces, and destructured typed bindings are not followed.
 
 If you want to lift some of these limitations, you should try tools like [Flow](https://flow.org) or [TypeScript](https://www.typescriptlang.org).
diff --git a/rules/no-unused-properties.js b/rules/no-unused-properties.js
@@ -1,13 +1,47 @@
+import {isTypeScriptExpressionWrapper, unwrapTypeScriptExpression} from './utils/index.js';
 import getScopes from './utils/get-scopes.js';
 
 const MESSAGE_ID = 'no-unused-properties';
 const messages = {
 	[MESSAGE_ID]: 'Property `{{name}}` is defined but never used.',
 };
 
-const getDeclaratorOrPropertyValue = declaratorOrProperty =>
-	declaratorOrProperty.init
-	|| declaratorOrProperty.value;
+const getTypeAnnotation = node => node?.typeAnnotation?.typeAnnotation;
+
+const getIdentifierTypeAnnotation = node => {
+	if (
+		node.type === 'VariableDeclarator'
+		&& !node.init
+	) {
+		return;
+	}
+
+	return getTypeAnnotation(node.id);
+};
+
+const getPropertyContainer = node => {
+	const value = unwrapTypeScriptExpression(node.init || node.value);
+	if (value?.type === 'ObjectExpression') {
+		return value;
+	}
+
+	const typeAnnotation = getTypeAnnotation(node) || getIdentifierTypeAnnotation(node);
+	if (typeAnnotation?.type === 'TSTypeLiteral') {
+		return typeAnnotation;
+	}
+};
+
+const getProperties = value => {
+	if (value.type === 'ObjectExpression') {
+		return value.properties;
+	}
+
+	if (value.type === 'TSTypeLiteral') {
+		return value.members.filter(member => member.type === 'TSPropertySignature');
+	}
+
+	return [];
+};
 
 const isMemberExpressionCall = memberExpression =>
 	memberExpression.parent.type === 'CallExpression'
@@ -20,6 +54,17 @@ const isMemberExpressionComputedBeyondPrediction = memberExpression =>
 	memberExpression.computed
 	&& memberExpression.property.type !== 'Literal';
 
+const getReferenceParent = referenceNode => {
+	while (
+		isTypeScriptExpressionWrapper(referenceNode.parent)
+		&& referenceNode.parent.expression === referenceNode
+	) {
+		referenceNode = referenceNode.parent;
+	}
+
+	return referenceNode.parent;
+};
+
 const specialProtoPropertyKey = {
 	type: 'Identifier',
 	name: '__proto__',
@@ -40,6 +85,11 @@ const propertyKeysEqual = (keyA, keyB) => {
 	return keyNameA !== undefined && keyNameA === getPropertyKeyName(keyB);
 };
 
+const getDefinitionNode = definition =>
+	definition.type === 'Parameter' && definition.name?.typeAnnotation
+		? definition.name
+		: definition.node;
+
 const objectPatternMatchesObjectExprPropertyKey = (pattern, key) =>
 	pattern.properties.some(property => {
 		if (property.type === 'RestElement') {
@@ -49,20 +99,6 @@ const objectPatternMatchesObjectExprPropertyKey = (pattern, key) =>
 		return propertyKeysEqual(property.key, key);
 	});
 
-const isLeafDeclaratorOrProperty = declaratorOrProperty => {
-	const value = getDeclaratorOrPropertyValue(declaratorOrProperty);
-
-	if (!value) {
-		return true;
-	}
-
-	if (value.type !== 'ObjectExpression') {
-		return true;
-	}
-
-	return false;
-};
-
 const isUnusedVariable = variable => {
 	const hasReadReference = variable.references.some(reference => reference.isRead());
 	return !hasReadReference;
@@ -83,7 +119,7 @@ const create = context => {
 		return sourceCode.getText(property.key);
 	};
 
-	const reportProperty = (property, references, path) => {
+	const reportProperty = (property, references) => {
 		if (references.length === 0) {
 			context.report({
 				node: property,
@@ -95,11 +131,11 @@ const create = context => {
 			return;
 		}
 
-		reportObject(property, references, path);
+		reportObject(property, references);
 	};
 
-	const reportProperties = (objectExpression, references, path = []) => {
-		for (const property of objectExpression.properties) {
+	const reportProperties = (objectLike, references) => {
+		for (const property of getProperties(objectLike)) {
 			const {key} = property;
 
 			if (!key) {
@@ -110,11 +146,9 @@ const create = context => {
 				continue;
 			}
 
-			const nextPath = [...path, key];
-
 			const nextReferences = references
 				.map(reference => {
-					const {parent} = reference.identifier;
+					const parent = getReferenceParent(reference.identifier);
 
 					if (reference.init) {
 						if (
@@ -170,18 +204,17 @@ const create = context => {
 				})
 				.filter(Boolean);
 
-			reportProperty(property, nextReferences, nextPath);
+			reportProperty(property, nextReferences);
 		}
 	};
 
-	const reportObject = (declaratorOrProperty, references, path) => {
-		if (isLeafDeclaratorOrProperty(declaratorOrProperty)) {
+	const reportObject = (node, references) => {
+		const propertyContainer = getPropertyContainer(node);
+		if (!propertyContainer) {
 			return;
 		}
 
-		const value = getDeclaratorOrPropertyValue(declaratorOrProperty);
-
-		reportProperties(value, references, path);
+		reportProperties(propertyContainer, references);
 	};
 
 	const reportVariable = variable => {
@@ -195,7 +228,7 @@ const create = context => {
 
 		const [definition] = variable.defs;
 
-		reportObject(definition.node, variable.references);
+		reportObject(getDefinitionNode(definition), variable.references);
 	};
 
 	const reportVariables = scope => {
diff --git a/test/no-unused-properties.js b/test/no-unused-properties.js
@@ -7,6 +7,11 @@ const error = {
 	messageId: 'no-unused-properties',
 };
 
+const errorWithPropertyName = name => ({
+	...error,
+	data: {name},
+});
+
 test({
 	valid: [
 		outdent`
@@ -464,8 +469,165 @@ test.typescript({
 
 			console.log(userDebounce);
 		`,
+		outdent`
+			function foo(args: {x: number; y: number}) {
+				return args.x + args.y;
+			}
+		`,
+		outdent`
+			function foo(args: {x: number; y: number}) {
+				console.log(args);
+			}
+		`,
+		outdent`
+			function foo(args: {x: number; y: number}, key: 'x' | 'y') {
+				return args[key];
+			}
+		`,
+		outdent`
+			function foo(args: {x: number; y: number}) {
+				args.x = 1;
+			}
+		`,
+		outdent`
+			function foo(args: {x: () => void; y: number}) {
+				args.x();
+			}
+		`,
+		outdent`
+			type Arguments = {
+				x: number;
+				y: number;
+			};
+
+			function foo(args: Arguments) {
+				return args.x;
+			}
+		`,
+		outdent`
+			interface Arguments {
+				x: number;
+				y: number;
+			}
+
+			function foo(args: Arguments) {
+				return args.x;
+			}
+		`,
+		outdent`
+			function foo({x}: {x: number; y: number}) {
+				return x;
+			}
+		`,
+		outdent`
+			const {x}: {x: number; y: number} = args;
+			console.log(x);
+		`,
+		outdent`
+			declare const args: {x: number; y: number};
+			console.log(args.x);
+		`,
+		outdent`
+			let args: {x: number; y: number};
+			console.log(args.x);
+		`,
+		outdent`
+			function foo(args: {x: number; y(): void}) {
+				return args.x;
+			}
+		`,
+		outdent`
+			function foo(args: {x: number; [key: string]: unknown}) {
+				return args.x;
+			}
+		`,
+		outdent`
+			function foo(args: {x: number; (value: string): void}) {
+				return args.x;
+			}
+		`,
+	],
+	invalid: [
+		{
+			code: outdent`
+				function foo(args: {x: number; y: number}) {
+					return args.x * 2;
+				}
+			`,
+			errors: [errorWithPropertyName('y')],
+		},
+		{
+			code: outdent`
+				const args: {x: number; y: number} = getArgs();
+				console.log(args.x);
+			`,
+			errors: [errorWithPropertyName('y')],
+		},
+		{
+			code: outdent`
+				function foo(args: {options: {enabled: boolean; unused: boolean}; label: string}) {
+					return args.options.enabled && args.label.length > 0;
+				}
+			`,
+			errors: [errorWithPropertyName('unused')],
+		},
+		{
+			code: outdent`
+				function foo(args: {'x': number; 'y': number}) {
+					return args['x'];
+				}
+			`,
+			errors: [errorWithPropertyName('y')],
+		},
+		{
+			code: outdent`
+				type Arguments = {
+					x: number;
+					unused: number;
+				};
+
+				const args: Arguments = {x: 1, unused: 2};
+				console.log(args.x);
+			`,
+			errors: [errorWithPropertyName('unused')],
+		},
+		{
+			code: outdent`
+				function foo(args: {x: {a: number; b: number}; y: number}) {
+					return args.x!.a;
+				}
+			`,
+			errors: [
+				errorWithPropertyName('b'),
+				errorWithPropertyName('y'),
+			],
+		},
+		{
+			code: outdent`
+				function foo(args: {x: {a: number; b: number}; y: number}) {
+					return (args.x as {a: number; b: number}).a;
+				}
+			`,
+			errors: [
+				errorWithPropertyName('b'),
+				errorWithPropertyName('y'),
+			],
+		},
+		{
+			code: outdent`
+				const args = {x: 1, y: 2} as const;
+				console.log(args.x);
+			`,
+			errors: [errorWithPropertyName('y')],
+		},
+		{
+			code: outdent`
+				const args = {x: 1, y: 2} satisfies {x: number; y: number};
+				console.log(args.x);
+			`,
+			errors: [errorWithPropertyName('y')],
+		},
 	],
-	invalid: [],
 });
 
 test.snapshot({
