Perfectionist
Rulessort-decorators

sort-decorators

Enforce sorted decorators.

Sorting decorators provides a clear and predictable structure to the codebase. This rule detects instances where decorators are not sorted and raises linting errors, encouraging developers to arrange elements in the desired order.

Consistently sorted decorators enhance the overall clarity and organization of your code.

Try it out

Options

This rule accepts an options object with the following properties:

type

default: 'alphabetical'

Specifies the sorting method.

  • 'alphabetical' — Sort items alphabetically (e.g., “a” < “b” < “c”) using localeCompare.
  • 'natural' — Sort items in a natural order (e.g., “item2” < “item10”).
  • 'line-length' — Sort items by the length of the code line (shorter lines first).
  • 'custom' — Sort items using the alphabet entered in the alphabet option.

order

default: 'asc'

Determines whether the sorted items should be in ascending or descending order.

  • 'asc' — Sort items in ascending order (A to Z, 1 to 9).
  • 'desc' — Sort items in descending order (Z to A, 9 to 1).

alphabet

default: ''

Only used when the type option is set to 'custom'. Specifies the custom alphabet to use when sorting.

Use the Alphabet utility class from eslint-plugin-perfectionist/alphabet to quickly generate a custom alphabet.

Example: 0123456789abcdef...

ignoreCase

default: true

Controls whether sorting should be case-sensitive or not.

  • true — Ignore case when sorting alphabetically or naturally (e.g., “A” and “a” are the same).
  • false — Consider case when sorting (e.g., “a” comes before “A”).

sortOnClasses

default: true

Controls whether sorting should be enabled for class decorators.

sortOnMethods

default: true

Controls whether sorting should be enabled for class method decorators.

sortOnProperties

default: true

Controls whether sorting should be enabled for class property decorators.

sortOnAccessors

default: true

Controls whether sorting should be enabled for class auto-accessor decorators.

sortOnParameters

default: true

Controls whether sorting should be enabled for method parameter decorators.

specialCharacters

default: keep

Controls whether special characters should be trimmed, removed or kept before sorting.

  • 'keep' — Keep special characters when sorting (e.g., “_a” comes before “a”).
  • 'trim' — Trim special characters when sorting alphabetically or naturally (e.g., “_a” and “a” are the same).
  • 'remove' — Remove special characters when sorting (e.g., “/a/b” and “ab” are the same).

locales

default: 'en-US'

Specifies the sorting locales. See String.prototype.localeCompare() - locales.

  • string — A BCP 47 language tag (e.g. 'en', 'en-US', 'zh-CN').
  • string[] — An array of BCP 47 language tags.

partitionByComment

default: false

Allows you to use comments to separate class decorators into logical groups.

  • true — All comments will be treated as delimiters, creating partitions.
  • false — Comments will not be used as delimiters.
  • string — A regexp pattern to specify which comments should act as delimiters.
  • string[] — An array of regexp patterns to specify which comments should act as delimiters.

groups

type: Array<string | string[]>

default: []

Allows you to specify a list of decorator groups for sorting.

Predefined groups:

  • 'unknown' — Decorators that don’t fit into any group specified in the groups option.

If the unknown group is not specified in the groups option, it will automatically be added to the end of the list.

Each decorator will be assigned a single group specified in the groups option (or the unknown group if no match is found). The order of items in the groups option determines how groups are ordered.

Within a given group, members will be sorted according to the type, order, ignoreCase, etc. options.

Individual groups can be combined together by placing them in an array. The order of groups in that array does not matter. All members of the groups in the array will be sorted together as if they were part of a single group.

customGroups

type: { [groupName: string]: string | string[] }

default: {}

You can define your own groups and use regex to match specific decorators.

Each key of customGroups represents a group name which you can then use in the groups option. The value for each key can either be of type:

  • string — A decorator’s name matching the value will be marked as part of the group referenced by the key.
  • string[] — A decorator’s name matching any of the values of the array will be marked as part of the group referenced by the key. The order of values in the array does not matter.

Custom group matching takes precedence over predefined group matching.

Example for class decorators (same for the rest of the elements):


Put all error-related decorators at the bottom:

```ts
@Component()
@Validated()
@AtLeastOneAttributeError()
@NoPublicAttributeError()
class MyClass {
}

groups and customGroups configuration:

 {
   groups: [
     'unknown',
     'error'
   ],
+  customGroups: {    
+    error: '.*Error'
+  }                  
 }

Usage

Version

This rule was introduced in v4.0.0.

Resources

Table of Contents