feat(define-props-destructuring): add only-when-assigned option (#3009)

Co-authored-by: waynzh <waynzh19@gmail.com>
Co-authored-by: Flo Edelmann <git@flo-edelmann.de>

Author: 3 people

.changeset/shy-ends-help.md

@@ -0,0 +1,5 @@
+---
+'eslint-plugin-vue': minor
+---
+
+Added new `destructure: "only-when-assigned"` option to `vue/define-props-destructuring` and changed default value from `destructure: "always"` to `destructure: "only-when-assigned"`

docs/rules/define-props-destructuring.md

@@ -23,10 +23,12 @@ By default, the rule requires you to use destructuring syntax when using `define
   // ✓ GOOD
   const { foo } = defineProps(['foo'])
   const { bar = 'default' } = defineProps(['bar'])
+  defineProps(['bar'])
 
   // ✗ BAD
   const props = defineProps(['foo'])
   const propsWithDefaults = withDefaults(defineProps(['foo']), { foo: 'default' })
+  withDefaults(defineProps(['foo']), { foo: 'default' })
 
   // ✗ BAD
   const { baz } = withDefaults(defineProps(['baz']), { baz: 'default' })
@@ -44,10 +46,12 @@ The rule applies to both JavaScript and TypeScript props:
   // ✓ GOOD
   const { foo } = defineProps<{ foo?: string }>()
   const { bar = 'default' } = defineProps<{ bar?: string }>()
+  defineProps<{ bar?: string }>()
 
   // ✗ BAD
   const props = defineProps<{ foo?: string }>()
   const propsWithDefaults = withDefaults(defineProps<{ foo?: string }>(), { foo: 'default' })
+  withDefaults(defineProps<{ foo?: string }>(), { foo: 'default' })
 </script>
 ```
 
@@ -58,15 +62,39 @@ The rule applies to both JavaScript and TypeScript props:
 ```js
 {
   "vue/define-props-destructuring": ["error", {
-    "destructure": "always" | "never"
+    "destructure": "only-when-assigned" | "always" | "never"
   }]
 }
 ```
 
 - `destructure` - Sets the destructuring preference for props
-  - `"always"` (default) - Requires destructuring when using `defineProps` and warns against using `withDefaults` with destructuring
+  - `"only-when-assigned"` (default) - Requires destructuring when `defineProps` is assigned to a variable, and warns against using `withDefaults` with destructuring
+  - `"always"` - Requires destructuring when using `defineProps` and warns against using `withDefaults` with destructuring
   - `"never"` - Requires using a variable to store props and prohibits destructuring
 
+### `"destructure": "always"`
+
+<eslint-code-block :rules="{'vue/define-props-destructuring': ['error', { destructure: 'always' }]}">
+
+```vue
+<script setup>
+  // ✓ GOOD
+  const { foo } = defineProps(['foo'])
+  const { bar = 'default' } = defineProps(['bar'])
+
+  // ✗ BAD
+  const props = defineProps(['foo'])
+  const propsWithDefaults = withDefaults(defineProps(['foo']), { foo: 'default' })
+  defineProps(['bar'])
+  withDefaults(defineProps(['foo']), { foo: 'default' })
+
+  // ✗ BAD
+  const { baz } = withDefaults(defineProps(['baz']), { baz: 'default' })
+</script>
+```
+
+</eslint-code-block>
+
 ### `"destructure": "never"`
 
 <eslint-code-block :rules="{'vue/define-props-destructuring': ['error', { destructure: 'never' }]}">

lib/rules/define-props-destructuring.js

@@ -20,7 +20,7 @@ module.exports = {
         type: 'object',
         properties: {
           destructure: {
-            enum: ['always', 'never']
+            enum: ['only-when-assigned', 'always', 'never']
           }
         },
         additionalProperties: false
@@ -35,7 +35,7 @@ module.exports = {
   /** @param {RuleContext} context */
   create(context) {
     const options = context.options[0] || {}
-    const destructurePreference = options.destructure || 'always'
+    const destructurePreference = options.destructure || 'only-when-assigned'
 
     return utils.compositingVisitors(
       utils.defineScriptSetupVisitor(context, {
@@ -49,6 +49,7 @@ module.exports = {
 
           const hasDestructure = utils.isUsingPropsDestructure(node)
           const hasWithDefaults = utils.hasWithDefaults(node)
+          const hasAssigned = !!utils.getLeftOfDefineProps(node)
 
           if (destructurePreference === 'never') {
             if (hasDestructure) {
@@ -60,7 +61,10 @@ module.exports = {
             return
           }
 
-          if (!hasDestructure) {
+          if (
+            !hasDestructure &&
+            (destructurePreference === 'always' || hasAssigned)
+          ) {
             context.report({
               node,
               messageId: 'preferDestructuring'

lib/utils/index.js

@@ -1557,6 +1557,7 @@ module.exports = {
    * @returns { Record<string, {prop: AssignmentProperty , expression: Expression} | undefined> }
    */
   getDefaultPropExpressionsForPropsDestructure,
+  getLeftOfDefineProps,
   /**
    * Checks whether the given defineProps node is using Props Destructure.
    * @param {CallExpression} node The node of defineProps

tests/lib/rules/define-props-destructuring.js

@@ -123,6 +123,25 @@ tester.run('define-props-destructuring', rule, {
       languageOptions: {
         parserOptions: { parser: require.resolve('@typescript-eslint/parser') }
       }
+    },
+    {
+      filename: 'test.vue',
+      code: `
+      <script setup>
+      defineProps(['foo'])
+      </script>
+      `
+    },
+    {
+      filename: 'test.vue',
+      code: `
+      <script setup lang="ts">
+      defineProps<{ foo?: string }>()
+      </script>
+      `,
+      languageOptions: {
+        parserOptions: { parser: require.resolve('@typescript-eslint/parser') }
+      }
     }
   ],
   invalid: [
@@ -359,6 +378,121 @@ tester.run('define-props-destructuring', rule, {
           endColumn: 44
         }
       ]
+    },
+    {
+      filename: 'test.vue',
+      code: `
+      <script setup lang="ts">
+      withDefaults(defineProps(['foo']), { foo: 'default' })
+      </script>
+      `,
+      errors: [
+        {
+          messageId: 'avoidWithDefaults',
+          line: 3,
+          column: 7,
+          endLine: 3,
+          endColumn: 19
+        }
+      ]
+    },
+    {
+      filename: 'test.vue',
+      code: `
+      <script setup lang="ts">
+      withDefaults(defineProps<{ foo?: string }>(), { foo: 'default' })
+      </script>
+      `,
+      languageOptions: {
+        parserOptions: { parser: require.resolve('@typescript-eslint/parser') }
+      },
+      errors: [
+        {
+          messageId: 'avoidWithDefaults',
+          line: 3,
+          column: 7,
+          endLine: 3,
+          endColumn: 19
+        }
+      ]
+    },
+    {
+      filename: 'test.vue',
+      code: `
+      <script setup lang="ts">
+      withDefaults(defineProps(['foo']), { foo: 'default' })
+      </script>
+      `,
+      options: [{ destructure: 'always' }],
+      errors: [
+        {
+          messageId: 'preferDestructuring',
+          line: 3,
+          column: 20,
+          endLine: 3,
+          endColumn: 40
+        }
+      ]
+    },
+    {
+      filename: 'test.vue',
+      code: `
+      <script setup lang="ts">
+      withDefaults(defineProps<{ foo?: string }>(), { foo: 'default' })
+      </script>
+      `,
+      options: [{ destructure: 'always' }],
+      languageOptions: {
+        parserOptions: { parser: require.resolve('@typescript-eslint/parser') }
+      },
+      errors: [
+        {
+          messageId: 'preferDestructuring',
+          line: 3,
+          column: 20,
+          endLine: 3,
+          endColumn: 51
+        }
+      ]
+    },
+    {
+      filename: 'test.vue',
+      code: `
+      <script setup lang="ts">
+      defineProps(['foo'])
+      </script>
+      `,
+      options: [{ destructure: 'always' }],
+      errors: [
+        {
+          messageId: 'preferDestructuring',
+          line: 3,
+          column: 7,
+          endLine: 3,
+          endColumn: 27
+        }
+      ]
+    },
+    {
+      filename: 'test.vue',
+      code: `
+      <script setup lang="ts">
+      defineProps<{ foo?: string }>()
+      </script>
+      `,
+      options: [{ destructure: 'always' }],
+      languageOptions: {
+        parserOptions: { parser: require.resolve('@typescript-eslint/parser') }
+      },
+      errors: [
+        {
+          messageId: 'preferDestructuring',
+          line: 3,
+          column: 7,
+          endLine: 3,
+          endColumn: 38
+        }
+      ]
     }
   ]
 })