feat(sort-objects): add numeric keys detection option

Author: hugop95

docs/content/rules/sort-objects.mdx

@@ -310,6 +310,7 @@ Specifies whether this rule should be applied to styled-components like librarie
     declarationMatchesPattern?: string | string[] | { pattern: string; flags: string } | { pattern: string; flags: string }[]
     declarationCommentMatchesPattern?: string | string[] | { pattern: string; flags: string } | { pattern: string; flags: string }[]
     objectType?: 'destructured' | 'non-destructured'
+    hasNumericKeysOnly?: boolean
   }
   ```
 </sub>
@@ -433,6 +434,29 @@ Example configuration:
 }
 ```
 
+- `hasNumericKeysOnly` — If `true`, matches only objects that have exclusively numeric keys.
+
+This option only detects unquoted numeric literal keys (e.g., `1`, `42`).
+Quoted strings like `"1"`, array-wrapped keys like `[1]`, or computed expressions are not detected as numeric keys.
+
+Example configuration:
+```ts
+{
+  'perfectionist/sort-objects': [
+    'error',
+    {
+      type: 'natural', // Sort numeric keys naturally (by numeric value)
+      useConfigurationIf: {
+        hasNumericKeysOnly: true,
+      },
+    },
+    {
+      type: 'alphabetical' // Fallback configuration
+    }
+  ],
+}
+```
+
 ### groups
 
 <sub>

rules/sort-object-types.ts

@@ -20,6 +20,12 @@ import {
   groupsJsonSchema,
   regexJsonSchema,
 } from '../utils/common-json-schemas'
+import {
+  singleCustomGroupJsonSchema,
+  sortByJsonSchema,
+  allModifiers,
+  allSelectors,
+} from './sort-object-types/types'
 import {
   MISSED_SPACING_ERROR,
   EXTRA_SPACING_ERROR,
@@ -28,11 +34,6 @@ import {
 } from '../utils/report-errors'
 import { validateNewlinesAndPartitionConfiguration } from '../utils/validate-newlines-and-partition-configuration'
 import { filterOptionsByDeclarationCommentMatches } from '../utils/filter-options-by-declaration-comment-matches'
-import {
-  singleCustomGroupJsonSchema,
-  allModifiers,
-  allSelectors,
-} from './sort-object-types/types'
 import { validateGeneratedGroupsConfiguration } from '../utils/validate-generated-groups-configuration'
 import { getCustomGroupsCompareOptions } from './sort-object-types/get-custom-groups-compare-options'
 import { validateCustomSortConfiguration } from '../utils/validate-custom-sort-configuration'
@@ -45,7 +46,6 @@ import { doesCustomGroupMatch } from '../utils/does-custom-group-match'
 import { isNodeFunctionType } from '../utils/is-node-function-type'
 import { sortNodesByGroups } from '../utils/sort-nodes-by-groups'
 import { createEslintRule } from '../utils/create-eslint-rule'
-import { sortByJsonSchema } from './sort-object-types/types'
 import { reportAllErrors } from '../utils/report-all-errors'
 import { shouldPartition } from '../utils/should-partition'
 import { computeGroup } from '../utils/compute-group'

rules/sort-objects.ts

@@ -1,5 +1,6 @@
 import type { TSESLint } from '@typescript-eslint/utils'
 
+import { AST_NODE_TYPES } from '@typescript-eslint/utils'
 import { TSESTree } from '@typescript-eslint/types'
 
 import type { SortingNodeWithDependencies } from '../utils/sort-nodes-by-dependencies'
@@ -393,6 +394,11 @@ export default createEslintRule<Options, MessageId>({
                 enum: ['destructured', 'non-destructured'],
                 type: 'string',
               },
+              hasNumericKeysOnly: {
+                description:
+                  'Specifies whether to only match objects that have exclusively numeric keys.',
+                type: 'boolean',
+              },
               declarationCommentMatchesPattern: regexJsonSchema,
               callingFunctionNamePattern: regexJsonSchema,
               declarationMatchesPattern: regexJsonSchema,
@@ -528,6 +534,13 @@ function computeMatchedContextOptions({
       }
     }
 
+    if (
+      options.useConfigurationIf.hasNumericKeysOnly &&
+      !hasNumericKeysOnly(nodeObject)
+    ) {
+      return false
+    }
+
     return true
   })
 }
@@ -637,6 +650,25 @@ function isStyledComponents(styledNode: TSESTree.Node): boolean {
   )
 }
 
+function hasNumericKeysOnly(
+  object: TSESTree.ObjectExpression | TSESTree.ObjectPattern,
+): boolean {
+  switch (object.type) {
+    case AST_NODE_TYPES.ObjectExpression:
+      return object.properties.every(
+        property =>
+          property.type === AST_NODE_TYPES.Property &&
+          property.key.type === 'Literal' &&
+          typeof property.key.value === 'number',
+      )
+    case AST_NODE_TYPES.ObjectPattern:
+      return false
+    /* v8 ignore next 2 */
+    default:
+      throw new UnreachableCaseError(object)
+  }
+}
+
 function getNodeName({
   sourceCode,
   property,

rules/sort-objects/types.ts

@@ -59,6 +59,12 @@ export type Options = Partial<
        * rule is only applied when all property names match this pattern.
        */
       allNamesMatchPattern?: RegexOption
+
+      /**
+       * Specifies whether to only match objects that have exclusively numeric
+       * keys.
+       */
+      hasNumericKeysOnly?: boolean
     }
 
     /**

test/rules/sort-objects.test.ts

@@ -2534,6 +2534,97 @@ describe('sort-objects', () => {
       })
     })
 
+    it('applies configuration when object only has numeric keys', async () => {
+      await valid({
+        options: [
+          {
+            useConfigurationIf: {
+              hasNumericKeysOnly: true,
+            },
+            type: 'unsorted',
+          },
+        ],
+        code: dedent`
+          const obj = {
+            5: 'five',
+            2: {},
+            3: 'three',
+            8: 'eight',
+          }
+        `,
+      })
+
+      await invalid({
+        options: [
+          {
+            useConfigurationIf: {
+              hasNumericKeysOnly: true,
+            },
+            type: 'unsorted',
+          },
+          options,
+        ],
+        errors: [
+          {
+            data: {
+              right: '1',
+              left: '2',
+            },
+            messageId: 'unexpectedObjectsOrder',
+          },
+        ],
+        output: dedent`
+          let obj = {
+            '1': 1,
+            2: 2,
+          }
+        `,
+        code: dedent`
+          let obj = {
+            2: 2,
+            '1': 1,
+          }
+        `,
+      })
+
+      await invalid({
+        options: [
+          {
+            useConfigurationIf: {
+              hasNumericKeysOnly: true,
+            },
+            type: 'unsorted',
+          },
+          options,
+        ],
+        errors: [
+          {
+            data: {
+              right: 'a',
+              left: 'b',
+            },
+            messageId: 'unexpectedObjectsOrder',
+          },
+        ],
+        output: dedent`
+          let Func = ({
+            a,
+            b,
+          }) => {
+            // ...
+          }
+        `,
+        code: dedent`
+          let Func = ({
+            b,
+            a,
+          }) => {
+            // ...
+          }
+        `,
+      })
+    })
+
     it('skips object declarations when objectType is "destructured"', async () => {
       await valid({
         options: [