Oct 11, 2023 · Jun 10, 2023 · Jun 12, 2023 · Jun 12, 2023 · Jun 12, 2023 · Jun 12, 2023
diff --git a/packages/eslint-plugin/docs/rules/prefer-destructuring.md b/packages/eslint-plugin/docs/rules/prefer-destructuring.md
 ---
 description: 'Require destructuring from arrays and/or objects.'
 ---

 > 🛑 This file is source code, not the primary documentation location! 🛑
 >
 > See **https://typescript-eslint.io/rules/prefer-destructuring** for documentation.

 ## Examples

 This rule extends the base [`eslint/prefer-destructuring`](https://eslint.org/docs/latest/rules/prefer-destructuring) rule.
 It adds support for TypeScript's type annotations in variable declarations.

 <!-- tabs -->

 ### `eslint/prefer-destructuring`

 ```ts
 const x: string = obj.x; // This is incorrect and the auto fixer provides following untyped fix.
 // const { x } = obj;
 ```

 ### `@typescript-eslint/prefer-destructuring`

 ```ts
 const x: string = obj.x; // This is correct by default. You can also forbid this by an option.
 ```

 <!-- /tabs -->

 And it infers binding patterns more accurately thanks to the type checker.

 <!-- tabs -->

 ### ❌ Incorrect

 ```ts
 const x = ['a'];
 const y = x[0];
 ```

 ### ✅ Correct

 ```ts
 const x = { 0: 'a' };
 const y = x[0];
 ```

 It is correct when `enforceForRenamedProperties` is not true.
 Valid destructuring syntax is renamed style like `{ 0: y } = x` rather than `[y] = x` because `x` is not iterable.

 ## Options

 This rule adds the following options:

 ```ts
 type Options = [
  BasePreferDestructuringOptions[0],
  BasePreferDestructuringOptions[1] & {
    enforceForDeclarationWithTypeAnnotation?: boolean;
  },
 ];

 const defaultOptions: Options = [
  basePreferDestructuringDefaultOptions[0],
  {
    ...basePreferDestructuringDefaultOptions[1],
    enforceForDeclarationWithTypeAnnotation: false,
  },
 ];
 ```

 ### `enforceForDeclarationWithTypeAnnotation`

 When set to `true`, type annotated variable declarations are enforced to use destructuring assignment.

 Examples with `{ enforceForDeclarationWithTypeAnnotation: true }`:

 <!--tabs-->

 ### ❌ Incorrect

 ```ts
 const x: string = obj.x;
 ```

 ### ✅ Correct

 ```ts
 const { x }: { x: string } = obj;
 ```
diff --git a/packages/eslint-plugin/src/configs/all.ts b/packages/eslint-plugin/src/configs/all.ts
    '@typescript-eslint/parameter-properties': 'error',
    '@typescript-eslint/prefer-as-const': 'error',
    '@typescript-eslint/prefer-enum-initializers': 'error',
    'prefer-destructuring': 'off',
    '@typescript-eslint/prefer-destructuring': 'error',
    '@typescript-eslint/prefer-for-of': 'error',
    '@typescript-eslint/prefer-function-type': 'error',
    '@typescript-eslint/prefer-includes': 'error',
diff --git a/packages/eslint-plugin/src/rules/index.ts b/packages/eslint-plugin/src/rules/index.ts
 import paddingLineBetweenStatements from './padding-line-between-statements';
 import parameterProperties from './parameter-properties';
 import preferAsConst from './prefer-as-const';
 import preferDestructuring from './prefer-destructuring';
 import preferEnumInitializers from './prefer-enum-initializers';
 import preferForOf from './prefer-for-of';
 import preferFunctionType from './prefer-function-type';
  'padding-line-between-statements': paddingLineBetweenStatements,
  'parameter-properties': parameterProperties,
  'prefer-as-const': preferAsConst,
  'prefer-destructuring': preferDestructuring,
  'prefer-enum-initializers': preferEnumInitializers,
  'prefer-for-of': preferForOf,
  'prefer-function-type': preferFunctionType,
diff --git a/packages/eslint-plugin/src/rules/prefer-destructuring.ts b/packages/eslint-plugin/src/rules/prefer-destructuring.ts
 import type { TSESLint, TSESTree } from '@typescript-eslint/utils';
 import { AST_NODE_TYPES } from '@typescript-eslint/utils';
 import type { JSONSchema4 } from '@typescript-eslint/utils/json-schema';
 import * as tsutils from 'ts-api-utils';
 import type * as ts from 'typescript';

 import type {
  InferMessageIdsTypeFromRule,
  InferOptionsTypeFromRule,
 } from '../util';
 import { createRule, getParserServices, isTypeAnyType } from '../util';
 import { getESLintCoreRule } from '../util/getESLintCoreRule';

 const baseRule = getESLintCoreRule('prefer-destructuring');

 type BaseOptions = InferOptionsTypeFromRule<typeof baseRule>;
 type EnforcementOptions = BaseOptions[1] & {
  enforceForDeclarationWithTypeAnnotation?: boolean;
 };
 type Options = [BaseOptions[0], EnforcementOptions];

 type MessageIds = InferMessageIdsTypeFromRule<typeof baseRule>;

 const destructuringTypeConfig: JSONSchema4 = {
  type: 'object',
  properties: {
    array: {
      type: 'boolean',
    },
    object: {
      type: 'boolean',
    },
  },
  additionalProperties: false,
 };

 const schema: readonly JSONSchema4[] = [
  {
    oneOf: [
      {
        type: 'object',
        properties: {
          VariableDeclarator: destructuringTypeConfig,
          AssignmentExpression: destructuringTypeConfig,
        },
        additionalProperties: false,
      },
      destructuringTypeConfig,
    ],
  },
  {
    type: 'object',
    properties: {
      enforceForRenamedProperties: {
        type: 'boolean',
      },
      enforceForDeclarationWithTypeAnnotation: {
        type: 'boolean',
      },
    },
  },
 ];

 export default createRule<Options, MessageIds>({
  name: 'prefer-destructuring',
  meta: {
    type: 'suggestion',
    docs: {
      description: 'Require destructuring from arrays and/or objects',
      extendsBaseRule: true,
      requiresTypeChecking: true,
    },
    schema,
    fixable: baseRule.meta.fixable,
    hasSuggestions: baseRule.meta.hasSuggestions,
    messages: baseRule.meta.messages,
  },
  defaultOptions: [
    {
      VariableDeclarator: {
        array: true,
        object: true,
      },
      AssignmentExpression: {
        array: true,
        object: true,
      },
    },
    {},
  ],
  create(context, [enabledTypes, options]) {
    const {
      enforceForRenamedProperties = false,
      enforceForDeclarationWithTypeAnnotation = false,
    } = options;
    const { program, esTreeNodeToTSNodeMap } = getParserServices(context);
    const typeChecker = program.getTypeChecker();
    const baseRules = baseRule.create(context);
    let baseRulesWithoutFixCache: typeof baseRules | null = null;

    return {
      VariableDeclarator(node): void {
        performCheck(node.id, node.init, node);
      },
      AssignmentExpression(node): void {
        if (node.operator !== '=') {
          return;
        }
        performCheck(node.left, node.right, node);
      },
    };

    function performCheck(
      leftNode: TSESTree.BindingName | TSESTree.Expression,
      rightNode: TSESTree.Expression | null,
      reportNode: TSESTree.VariableDeclarator | TSESTree.AssignmentExpression,
    ): void {
      const rules =
        leftNode.type === AST_NODE_TYPES.Identifier &&
        leftNode.typeAnnotation === undefined
          ? baseRules
          : baseRulesWithoutFix();
      if (
        'typeAnnotation' in leftNode &&
        leftNode.typeAnnotation !== undefined &&
        !enforceForDeclarationWithTypeAnnotation
      ) {
        return;
      }

      if (
        rightNode != null &&
        isArrayLiteralIntegerIndexAccess(rightNode) &&
        rightNode.object.type !== AST_NODE_TYPES.Super
      ) {
        const tsObj = esTreeNodeToTSNodeMap.get(rightNode.object);
        const objType = typeChecker.getTypeAtLocation(tsObj);
        if (!isTypeAnyOrIterableType(objType, typeChecker)) {
          if (
            !enforceForRenamedProperties ||
            !getNormalizedEnabledType(reportNode.type, 'object')
          ) {
            return;
          }
          context.report({
            node: reportNode,
            messageId: 'preferDestructuring',
            data: { type: 'object' },
          });
          return;
        }
      }

      if (reportNode.type === AST_NODE_TYPES.AssignmentExpression) {
        rules.AssignmentExpression(reportNode);
      } else {
        rules.VariableDeclarator(reportNode);
      }
    }

    function getNormalizedEnabledType(
      nodeType:
        | AST_NODE_TYPES.VariableDeclarator
        | AST_NODE_TYPES.AssignmentExpression,
      destructuringType: 'array' | 'object',
    ): boolean | undefined {
      if ('object' in enabledTypes || 'array' in enabledTypes) {
        return enabledTypes[destructuringType];
      }
      return enabledTypes[nodeType as keyof typeof enabledTypes][
        destructuringType as keyof (typeof enabledTypes)[keyof typeof enabledTypes]
      ];
    }

    function baseRulesWithoutFix(): ReturnType<typeof baseRule.create> {
      baseRulesWithoutFixCache ??= baseRule.create(noFixContext(context));
      return baseRulesWithoutFixCache;
    }
  },
 });

 type Context = TSESLint.RuleContext<MessageIds, Options>;

 function noFixContext(context: Context): Context {
  const customContext: {
    report: Context['report'];
  } = {
    report: (descriptor): void => {
      context.report({
        ...descriptor,
        fix: undefined,
      });
    },
  };

  // we can't directly proxy `context` because its `report` property is non-configurable
  // and non-writable. So we proxy `customContext` and redirect all
  // property access to the original context except for `report`
  return new Proxy<Context>(customContext as typeof context, {
    get(target, path, receiver): unknown {
      if (path !== 'report') {
        return Reflect.get(context, path, receiver);
      }
      return Reflect.get(target, path, receiver);
    },
  });
 }

 function isTypeAnyOrIterableType(
  type: ts.Type,
  typeChecker: ts.TypeChecker,
 ): boolean {
  if (isTypeAnyType(type)) {
    return true;
  }
  if (!type.isUnion()) {
    const iterator = tsutils.getWellKnownSymbolPropertyOfType(
      type,
      'iterator',
      typeChecker,
    );
    return iterator !== undefined;
  }
  return type.types.every(t => isTypeAnyOrIterableType(t, typeChecker));
 }

 function isArrayLiteralIntegerIndexAccess(
  node: TSESTree.Expression,
 ): node is TSESTree.MemberExpression {
  if (node.type !== AST_NODE_TYPES.MemberExpression) {
    return false;
  }
  if (node.property.type !== AST_NODE_TYPES.Literal) {
    return false;
  }
  return Number.isInteger(node.property.value);
 }
diff --git a/packages/eslint-plugin/src/util/getESLintCoreRule.ts b/packages/eslint-plugin/src/util/getESLintCoreRule.ts
  'no-restricted-globals': typeof import('eslint/lib/rules/no-restricted-globals');
  'object-curly-spacing': typeof import('eslint/lib/rules/object-curly-spacing');
  'prefer-const': typeof import('eslint/lib/rules/prefer-const');
  'prefer-destructuring': typeof import('eslint/lib/rules/prefer-destructuring');
  quotes: typeof import('eslint/lib/rules/quotes');
  semi: typeof import('eslint/lib/rules/semi');
  'space-before-blocks': typeof import('eslint/lib/rules/space-before-blocks');
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,91 @@
		---
		description: 'Require destructuring from arrays and/or objects.'
		---

		> 🛑 This file is source code, not the primary documentation location! 🛑
		>
		> See https://typescript-eslint.io/rules/prefer-destructuring for documentation.

		## Examples

		This rule extends the base [`eslint/prefer-destructuring`](https://eslint.org/docs/latest/rules/prefer-destructuring) rule.
		It adds support for TypeScript's type annotations in variable declarations.

		<!-- tabs -->

		### `eslint/prefer-destructuring`

		```ts
		const x: string = obj.x; // This is incorrect and the auto fixer provides following untyped fix.
		// const { x } = obj;
		```

		### `@typescript-eslint/prefer-destructuring`

		```ts
		const x: string = obj.x; // This is correct by default. You can also forbid this by an option.
		```

		<!-- /tabs -->

		And it infers binding patterns more accurately thanks to the type checker.

		<!-- tabs -->

		### ❌ Incorrect

		```ts
		const x = ['a'];
		const y = x[0];
		```

		### ✅ Correct

		```ts
		const x = { 0: 'a' };
		const y = x[0];
		```

		It is correct when `enforceForRenamedProperties` is not true.
		Valid destructuring syntax is renamed style like `{ 0: y } = x` rather than `[y] = x` because `x` is not iterable.

		## Options

		This rule adds the following options:

		```ts
		type Options = [
		BasePreferDestructuringOptions[0],
		BasePreferDestructuringOptions[1] & {
		enforceForDeclarationWithTypeAnnotation?: boolean;
		},
		];

		const defaultOptions: Options = [
		basePreferDestructuringDefaultOptions[0],
		{
		...basePreferDestructuringDefaultOptions[1],
		enforceForDeclarationWithTypeAnnotation: false,
		},
		];
		```

		### `enforceForDeclarationWithTypeAnnotation`

		When set to `true`, type annotated variable declarations are enforced to use destructuring assignment.

		Examples with `{ enforceForDeclarationWithTypeAnnotation: true }`:

		<!--tabs-->

		### ❌ Incorrect

		```ts
		const x: string = obj.x;
		```

		### ✅ Correct

		```ts
		const { x }: { x: string } = obj;
		```
Original file line number	Diff line number	Diff line change
Expand Up		@@ -141,6 +141,8 @@ export = {
		'@typescript-eslint/parameter-properties': 'error',
		'@typescript-eslint/prefer-as-const': 'error',
		'@typescript-eslint/prefer-enum-initializers': 'error',
		'prefer-destructuring': 'off',
		'@typescript-eslint/prefer-destructuring': 'error',
		'@typescript-eslint/prefer-for-of': 'error',
		'@typescript-eslint/prefer-function-type': 'error',
		'@typescript-eslint/prefer-includes': 'error',
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -97,6 +97,7 @@ import objectCurlySpacing from './object-curly-spacing';
		import paddingLineBetweenStatements from './padding-line-between-statements';
		import parameterProperties from './parameter-properties';
		import preferAsConst from './prefer-as-const';
		import preferDestructuring from './prefer-destructuring';
		import preferEnumInitializers from './prefer-enum-initializers';
		import preferForOf from './prefer-for-of';
		import preferFunctionType from './prefer-function-type';
Expand DownExpand Up		@@ -232,6 +233,7 @@ export default {
		'padding-line-between-statements': paddingLineBetweenStatements,
		'parameter-properties': parameterProperties,
		'prefer-as-const': preferAsConst,
		'prefer-destructuring': preferDestructuring,
		'prefer-enum-initializers': preferEnumInitializers,
		'prefer-for-of': preferForOf,
		'prefer-function-type': preferFunctionType,
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,237 @@
		import type { TSESLint, TSESTree } from '@typescript-eslint/utils';
		import { AST_NODE_TYPES } from '@typescript-eslint/utils';
		import type { JSONSchema4 } from '@typescript-eslint/utils/json-schema';
		import * as tsutils from 'ts-api-utils';
		import type * as ts from 'typescript';

		import type {
		InferMessageIdsTypeFromRule,
		InferOptionsTypeFromRule,
		} from '../util';
		import { createRule, getParserServices, isTypeAnyType } from '../util';
		import { getESLintCoreRule } from '../util/getESLintCoreRule';

		const baseRule = getESLintCoreRule('prefer-destructuring');

		type BaseOptions = InferOptionsTypeFromRule<typeof baseRule>;
		type EnforcementOptions = BaseOptions[1] & {
		enforceForDeclarationWithTypeAnnotation?: boolean;
		};
		type Options = [BaseOptions[0], EnforcementOptions];

		type MessageIds = InferMessageIdsTypeFromRule<typeof baseRule>;

		const destructuringTypeConfig: JSONSchema4 = {
		type: 'object',
		properties: {
		array: {
		type: 'boolean',
		},
		object: {
		type: 'boolean',
		},
		},
		additionalProperties: false,
		};

		const schema: readonly JSONSchema4[] = [
		{
		oneOf: [
		{
		type: 'object',
		properties: {
		VariableDeclarator: destructuringTypeConfig,
		AssignmentExpression: destructuringTypeConfig,
		},
		additionalProperties: false,
		},
		destructuringTypeConfig,
		],
		},
		{
		type: 'object',
		properties: {
		enforceForRenamedProperties: {
		type: 'boolean',
		},
		enforceForDeclarationWithTypeAnnotation: {
		type: 'boolean',
		},
		},
		},
		];

		export default createRule<Options, MessageIds>({
		name: 'prefer-destructuring',
		meta: {
		type: 'suggestion',
		docs: {
		description: 'Require destructuring from arrays and/or objects',
		extendsBaseRule: true,
		requiresTypeChecking: true,
		},
		schema,
		fixable: baseRule.meta.fixable,
		hasSuggestions: baseRule.meta.hasSuggestions,
		messages: baseRule.meta.messages,
		},
		defaultOptions: [
		{
		VariableDeclarator: {
		array: true,
		object: true,
		},
		AssignmentExpression: {
		array: true,
		object: true,
		},
		},
		{},
		],
		create(context, [enabledTypes, options]) {
		const {
		enforceForRenamedProperties = false,
		enforceForDeclarationWithTypeAnnotation = false,
		} = options;
		const { program, esTreeNodeToTSNodeMap } = getParserServices(context);
		const typeChecker = program.getTypeChecker();
		const baseRules = baseRule.create(context);
		let baseRulesWithoutFixCache: typeof baseRules \| null = null;

		return {
		VariableDeclarator(node): void {
		performCheck(node.id, node.init, node);
		},
		AssignmentExpression(node): void {
		if (node.operator !== '=') {
		return;
		}
		performCheck(node.left, node.right, node);
		},
		};

		function performCheck(
		leftNode: TSESTree.BindingName \| TSESTree.Expression,
		rightNode: TSESTree.Expression \| null,
		reportNode: TSESTree.VariableDeclarator \| TSESTree.AssignmentExpression,
		): void {
		const rules =
		leftNode.type === AST_NODE_TYPES.Identifier &&
		leftNode.typeAnnotation === undefined
		? baseRules
		: baseRulesWithoutFix();
		if (
		'typeAnnotation' in leftNode &&
		leftNode.typeAnnotation !== undefined &&
		!enforceForDeclarationWithTypeAnnotation
		) {
		return;
		}

		if (
		rightNode != null &&
		isArrayLiteralIntegerIndexAccess(rightNode) &&
		rightNode.object.type !== AST_NODE_TYPES.Super
		) {
		const tsObj = esTreeNodeToTSNodeMap.get(rightNode.object);
		const objType = typeChecker.getTypeAtLocation(tsObj);
		if (!isTypeAnyOrIterableType(objType, typeChecker)) {
		if (
		!enforceForRenamedProperties \|\|
		!getNormalizedEnabledType(reportNode.type, 'object')
		) {
		return;
		}
		context.report({
		node: reportNode,
		messageId: 'preferDestructuring',
		data: { type: 'object' },
		});
		return;
		}
		}

		if (reportNode.type === AST_NODE_TYPES.AssignmentExpression) {
		rules.AssignmentExpression(reportNode);
		} else {
		rules.VariableDeclarator(reportNode);
		}
		}

		function getNormalizedEnabledType(
		nodeType:
		\| AST_NODE_TYPES.VariableDeclarator
		\| AST_NODE_TYPES.AssignmentExpression,
		destructuringType: 'array' \| 'object',
		): boolean \| undefined {
		if ('object' in enabledTypes \|\| 'array' in enabledTypes) {
		return enabledTypes[destructuringType];
		}
		return enabledTypes[nodeType as keyof typeof enabledTypes][
		destructuringType as keyof (typeof enabledTypes)[keyof typeof enabledTypes]
		];
		}

		function baseRulesWithoutFix(): ReturnType<typeof baseRule.create> {
		baseRulesWithoutFixCache ??= baseRule.create(noFixContext(context));
		return baseRulesWithoutFixCache;
		}
		},
		});

		type Context = TSESLint.RuleContext<MessageIds, Options>;

		function noFixContext(context: Context): Context {
		const customContext: {
		report: Context['report'];
		} = {
		report: (descriptor): void => {
		context.report({
		...descriptor,
		fix: undefined,
		});
		},
		};

		// we can't directly proxy `context` because its `report` property is non-configurable
		// and non-writable. So we proxy `customContext` and redirect all
		// property access to the original context except for `report`
		return new Proxy<Context>(customContext as typeof context, {
		get(target, path, receiver): unknown {
		if (path !== 'report') {
		return Reflect.get(context, path, receiver);
		}
		return Reflect.get(target, path, receiver);
		},
		});
		}

		function isTypeAnyOrIterableType(
		type: ts.Type,
		typeChecker: ts.TypeChecker,
		): boolean {
		if (isTypeAnyType(type)) {
		return true;
JoshuaKGoldberg marked this conversation as resolved. Show resolvedHide resolved
		}
		if (!type.isUnion()) {
JoshuaKGoldberg marked this conversation as resolved. Show resolvedHide resolved
		const iterator = tsutils.getWellKnownSymbolPropertyOfType(
		type,
		'iterator',
		typeChecker,
		);
		return iterator !== undefined;
		}
		return type.types.every(t => isTypeAnyOrIterableType(t, typeChecker));
		}

		function isArrayLiteralIntegerIndexAccess(
		node: TSESTree.Expression,
		): node is TSESTree.MemberExpression {
		if (node.type !== AST_NODE_TYPES.MemberExpression) {
		return false;
		}
		if (node.property.type !== AST_NODE_TYPES.Literal) {
		return false;
		}
		return Number.isInteger(node.property.value);
JoshuaKGoldberg marked this conversation as resolved. Show resolvedHide resolved
		}
Original file line number	Diff line number	Diff line change
Expand Up		@@ -34,6 +34,7 @@ interface RuleMap {
		'no-restricted-globals': typeof import('eslint/lib/rules/no-restricted-globals');
		'object-curly-spacing': typeof import('eslint/lib/rules/object-curly-spacing');
		'prefer-const': typeof import('eslint/lib/rules/prefer-const');
		'prefer-destructuring': typeof import('eslint/lib/rules/prefer-destructuring');
		quotes: typeof import('eslint/lib/rules/quotes');
		semi: typeof import('eslint/lib/rules/semi');
		'space-before-blocks': typeof import('eslint/lib/rules/space-before-blocks');
Expand Down