# sort-interfaces Enforce sorted TypeScript interface properties. Sorting interface properties in TypeScript provides a clear and predictable structure to the codebase. This rule helps developers locate various properties defined within an interface more easily, promoting consistency and enabling efficient maintenance and collaboration. Additionally, it ensures that property comments are sorted along with the properties themselves, preserving documentation clarity. > **Important** > > If you use the > [`adjacent-overload-signatures`](https://typescript-eslint.io/rules/adjacent-overload-signatures) > rule from the > [`@typescript-eslint/eslint-plugin`](https://typescript-eslint.io) plugin, it > is highly recommended to [disable > it](https://eslint.org/docs/latest/use/configure/rules#using-configuration-files-1) > to avoid conflicts. It's **safe**. If you document interface properties line by line, property comments will also be sorted. ## Try it out **Initial** ```tsx interface Address { street: string city: string country: string postalCode: string apartmentNumber?: string } interface User { firstName: string email: string roles: string[] login: string phoneNumber?: string address: Address id: string } interface Project { startDate: Date budget: number description: string id: string projectTeamMembers: User[] name: string status: string } ``` **Sorted alphabetically** ```tsx interface Address { apartmentNumber?: string city: string country: string postalCode: string street: string } interface User { address: Address email: string firstName: string id: string login: string phoneNumber?: string roles: string[] } interface Project { budget: number description: string id: string name: string projectTeamMembers: User[] startDate: Date status: string } ``` **Sorted by line length** ```tsx interface Address { apartmentNumber?: string postalCode: string country: string street: string city: string } interface User { phoneNumber?: string firstName: string address: Address roles: string[] email: string login: string id: string } interface Project { projectTeamMembers: User[] description: string startDate: Date budget: number status: string name: string id: string } ``` ## 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare). - `'natural'` — Sort items in a [natural](https://github.com/yobacca/natural-orderby) order (e.g., “item2” \< “item10”). - `'line-length'` — Sort items by code line length (shorter lines first). - `'custom'` — Sort items using the alphabet specified in the [`alphabet`](#alphabet) option. - `'unsorted'` — Do not sort items. [`grouping`](#groups) and [`newlines behavior`](#newlinesbetween) are still enforced. ### order default: `'asc'` Specifies whether to sort items 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). ### fallbackSort type: ```ts { type: | 'alphabetical' | 'natural' | 'line-length' | 'custom' | 'subgroup-order' | 'unsorted' order?: 'asc' | 'desc' sortBy?: 'name' | 'value' } ``` default: `{ type: 'unsorted' }` Specifies fallback sort options for elements that are equal according to the primary sort [`type`](#type). You can also sort by subgroup order (nested groups in the [`groups`](#groups) option) using `subgroup-order`. Example: enforce alphabetical sort between two elements with the same length. ```ts { type: 'line-length', order: 'desc', fallbackSort: { type: 'alphabetical', order: 'asc' } } ``` ### alphabet default: `''` Used only when the [`type`](#type) option is set to `'custom'`. Specifies the custom alphabet for sorting. Use the `Alphabet` utility class from `eslint-plugin-perfectionist/alphabet` to quickly generate a custom alphabet. Example: `0123456789abcdef...` ### ignoreCase default: `true` Specifies whether sorting should be case-sensitive. - `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”). ### specialCharacters default: `'keep'` Specifies whether to trim, remove, or keep special characters 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. Refer To [String.prototype.localeCompare() - locales](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare#locales). - `string` — A BCP 47 language tag (e.g. `'en'`, `'en-US'`, `'zh-CN'`). - `string[]` — An array of BCP 47 language tags. ### sortBy default: `'name'` Controls whether sorting should be done only using the interface's values. - `name` — Use interface types keys. - `value` — Use the values of properties. Non-properties will not have an enforced sort order. Example ```ts interface User { createdAt: Date lastLoginAt: Date _id: ObjectId groupId: ObjectId city: string } ``` `sortBy` option configuration: ```ts { sortBy: 'value', } ``` ### partitionByComment default: `false` Enables the use of comments to separate the properties of interfaces into logical groups. This can help in organizing and maintaining large interfaces by creating partitions within the interface based on comments. - `true` — All comments will be treated as delimiters, creating partitions. - `false` — Comments will not be used as delimiters. - `RegExpPattern = string | { pattern: string; flags: string}` — A regexp pattern to specify which comments should act as delimiters. - `RegExpPattern[]` — A list of regexp patterns to specify which comments should act as delimiters. - `{ block: boolean | RegExpPattern | RegExpPattern[]; line: boolean | RegExpPattern | RegExpPattern[] }` — Specify which block and line comments should act as delimiters. ### partitionByNewLine default: `false` When `true`, the rule will not sort the members of an interface if there is an empty line between them. This helps maintain the defined order of logically separated groups of members. ```ts interface User { // Group 1 firstName: string; lastName: string; // Group 2 age: number; birthDate: Date; // Group 3 address: string; phone?: string; } ``` Each group of members (separated by empty lines) is treated independently, and the order within each group is preserved. ### newlinesBetween type: `number | 'ignore'` default: `'ignore'` Specifies how to handle newlines between groups. - `'ignore'` — Do not report errors related to newlines. - `0` — No newlines are allowed. - Any other number — Enforce this number of newlines between each group. You can also enforce the newline behavior between two specific groups through the [`groups`](#newlines-between-groups) option. This option is only applicable when [`partitionByNewLine`](#partitionbynewline) is `false`. ### newlinesInside type: `number | 'ignore' | 'newlinesBetween'` default: `'newlinesBetween'` Specifies how to handle newlines inside groups. - `'ignore'` — Do not report errors related to newlines. - `'newlinesBetween'` — \[DEPRECATED] If [`newlinesBetween`](#newlinesbetween) is `'ignore'`, then `'ignore'`, otherwise `0`. - `0` — No newlines are allowed. - Any other number — Enforce this number of newlines between each element of the same group. You can also enforce the newline behavior inside a given group through the [`groups`](#group-with-overridden-settings) or [`customGroups`](#customgroups) options. This option is only applicable when [`partitionByNewLine`](#partitionbynewline) is `false`. ### useConfigurationIf type: ```ts { allNamesMatchPattern?: | string | string[] | { pattern: string; flags: string } | { pattern: string; flags: string }[] declarationMatchesPattern?: | string | string[] | { pattern: string; flags: string } | { pattern: string; flags: string }[] declarationCommentMatchesPattern?: | string | string[] | { pattern: string; flags: string } | { pattern: string; flags: string }[] hasNumericKeysOnly?: boolean matchesAstSelector?: string } ``` Specifies filters to match a particular options configuration for a given interface. The first matching options configuration will be used. If no configuration matches, the default options configuration will be used. - `allNamesMatchPattern` — A regexp pattern that all keys must match. Example configuration: ```ts { 'perfectionist/sort-interfaces': [ 'error', { groups: ['r', 'g', 'b'], // Sort colors types by RGB customGroups: [ { groupName: 'r', elementNamePattern: '^r$', }, { groupName: 'g', elementNamePattern: '^g$', }, { groupName: 'b', elementNamePattern: '^b$', }, ], useConfigurationIf: { allNamesMatchPattern: '^[rgb]$', }, }, { type: 'alphabetical' // Fallback configuration } ], } ``` - `declarationMatchesPattern` — A regexp pattern that the interface declaration must match. Example configuration: ```ts { 'perfectionist/sort-interfaces': [ 'error', { type: 'unsorted', // Do not sort Metadata interfaces useConfigurationIf: { declarationMatchesPattern: '*Metadata$', }, }, { type: 'alphabetical' // Fallback configuration } ], } ``` - `declarationCommentMatchesPattern` — A regexp pattern to specify which comments above the interface declaration should match. Example configuration: ```ts { 'perfectionist/sort-interfaces': [ 'error', { type: 'unsorted', // Don't sort interfaces with a "do not sort" comment useConfigurationIf: { declarationCommentMatchesPattern: '^do not sort$', }, }, { type: 'alphabetical' // Fallback configuration } ], } ``` - `hasNumericKeysOnly` — If `true`, matches only interfaces 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-interfaces': [ 'error', { type: 'natural', // Sort numeric keys naturally (by numeric value) useConfigurationIf: { hasNumericKeysOnly: true, }, }, { type: 'alphabetical' // Fallback configuration } ], } ``` - `matchesAstSelector` — An [AST selector](https://eslint.org/docs/latest/extend/selectors) matching a `TSInterfaceDeclaration` node. To avoid unexpected behavior, do not use `:exit` or `:enter` pseudo-selectors. ### groups type: ```ts Array< | string | string[] | { newlinesBetween: number | 'ignore' } | { group: string | string[]; type?: 'alphabetical' | 'natural' | 'line-length' | 'custom' | 'unsorted'; order?: 'asc' | 'desc'; fallbackSort?: { type: string; order?: 'asc' | 'desc'; sortBy?: 'name' | 'value' }; sortBy?: 'name' | 'value' newlinesInside?: number | 'ignore'; } > ``` default: `[]` Specifies a list of interface member groups for sorting. Groups help organize members into categories, making your interfaces more readable and maintainable. Each interface member 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. Predefined groups are characterized by a single selector and potentially multiple modifiers. You may enter modifiers in any order, but the selector must always come at the end. #### Example ```ts interface User { firstName: string // unknown lastName: string // unknown username: string // unknown job: { // multiline-member // Stuff about job } localization: { // multiline-member // Stuff about localization } } ``` `groups` option configuration: ```ts { groups: [ 'unknown', 'method', 'multiline-member', ] } ``` #### Index-signatures - Selectors: `'index-signature'`, `'member'`. - Modifiers: `'required'`, `'optional'`, `'multiline'`. - Example: `'optional-index-signature'`, `'index-signature'`, `'member'`. #### Methods - Selectors: `'method'`, `'member'`. - Modifiers: `'required'`, `'optional'`, `'multiline'`. - Example: `'optional-multiline-method'`, `'method'`, `'member'`. #### Properties - Selectors: `'property'`, `'member'`. - Modifiers: `'required'`, `'optional'`, `'multiline'`. - Example: `'optional-property'`, `'property'`, `'member'`. ##### Scope of the `required` modifier Elements that are not `optional` will be matched with the `required` modifier, even if the keyword is not present. #### Important notes ##### The `unknown` group Members that don't fit into any group specified in the `groups` option will be placed in the `unknown` group. If the `unknown` group is not specified in the `groups` option, it will automatically be added to the end of the list. ##### Behavior when multiple groups match an element The lists of modifiers above are sorted by importance, from most to least important. In case of multiple groups matching an element, the following rules will be applied: 1. The group with the most modifiers matching will be selected. 2. If modifiers quantity is the same, order will be chosen based on modifier importance as listed above. Example : ```ts interface Test { optionalMethod?: () => { property: string; } } ``` `optionalMethod` can be matched by the following groups, from most to least important: - `'multiline-optional-method'` or `'optional-multiline-method'`. - `'multiline-method'`. - `'optional-method'`. - `'method'`. - `'multiline-optional-member'` or `'optional-multiline-member'`. - `'multiline-member'`. - `'optional-member'`. - `'member'`. - `'unknown'`. Example 2 (The most important group is written in the comments): ```ts interface Interface { // 'index-signature' [key: string]: any; // 'optional-property' description?: string; // 'required-method' method(): string ``` #### Group with overridden settings You may directly override options for a specific group by using an object with the `group` property and other option overrides. - `type` — Overrides the [`type`](#type) option for that group. - `order` — Overrides the [`order`](#order) option for that group. - `fallbackSort` — Overrides the [`fallbackSort`](#fallbacksort) option for that group. - `sortBy` — Overrides the [`sortBy`](#sortby) option for that group. - `newlinesInside` — Overrides the [`newlinesInside`](#newlinesinside) option for that group. ```ts { groups: [ 'method', { group: 'multiline-member', type: 'unsorted' }, // Elements from this group will not be sorted ] } ``` ##### Newlines between groups You may place `newlinesBetween` objects between your groups to enforce the newline behavior between two specific groups. See the [`newlinesBetween`](#newlinesbetween) option. This feature is only applicable when [`partitionByNewLine`](#partitionbynewline) is `false`. ```ts { newlinesBetween: 1, groups: [ 'a', { newlinesBetween: 0 }, // Overrides the global newlinesBetween option 'b', ] } ``` ### customGroups > **Migrating from the old API** > > Support for the object-based `customGroups` option is deprecated. > > Migrating from the old to the current API is easy: > > Old API: > > ```ts > { > "key1": "value1", > "key2": "value2" > } > ``` > > Current API: > > ```ts > [ > { > "groupName": "key1", > "elementNamePattern": "value1" > }, > { > "groupName": "key2", > "elementNamePattern": "value2" > } > ] > ``` type: `Array` default: `[]` Defines custom groups to match specific interface members. A custom group definition may follow one of the two following interfaces: ```ts interface CustomGroupDefinition { groupName: string type?: 'alphabetical' | 'natural' | 'line-length' | 'unsorted' order?: 'asc' | 'desc' fallbackSort?: { type: string; order?: 'asc' | 'desc'; sortBy?: 'name' | 'value' } sortBy?: 'name' | 'value' newlinesInside?: number | 'ignore' selector?: string modifiers?: string[] elementNamePattern?: string | string[] | { pattern: string; flags?: string } | { pattern: string; flags?: string }[] elementValuePattern?: string | string[] | { pattern: string; flags?: string } | { pattern: string; flags?: string }[] } ``` An interface member will match a `CustomGroupDefinition` group if it matches all the filters of the custom group's definition. or: ```ts interface CustomGroupAnyOfDefinition { groupName: string type?: 'alphabetical' | 'natural' | 'line-length' | 'unsorted' order?: 'asc' | 'desc' fallbackSort?: { type: string; order?: 'asc' | 'desc'; sortBy?: 'name' | 'value' } sortBy?: 'name' | 'value' newlinesInside?: number | 'ignore' anyOf: Array<{ selector?: string modifiers?: string[] elementNamePattern?: string | string[] | { pattern: string; flags?: string } | { pattern: string; flags?: string }[] elementValuePattern?: string | string[] | { pattern: string; flags?: string } | { pattern: string; flags?: string }[] }> } ``` An interface member will match a `CustomGroupAnyOfDefinition` group if it matches all the filters of at least one of the `anyOf` items. #### Attributes - `groupName` — The group's name, which needs to be put in the [`groups`](#groups) option. - `selector` — Filter on the `selector` of the element. - `modifiers` — Filter on the `modifiers` of the element. (All the modifiers of the element must be present in that list) - `elementNamePattern` — If entered, will check that the name of the element matches the pattern entered. - `elementValuePattern` — Only for properties. If entered, will check that the value of the property matches the pattern entered. - `type` — Overrides the [`type`](#type) option for that custom group. - `order` — Overrides the [`order`](#order) option for that custom group. - `fallbackSort` — Overrides the [`fallbackSort`](#fallbacksort) option for that custom group. - `sortBy` — Overrides the [`sortBy`](#sortby) option for that custom group. - `newlinesInside` — Overrides the [`newlinesInside`](#newlinesinside) option for that group. #### Match importance The `customGroups` list is ordered: The first custom group definition that matches an element will be used. Custom groups have a higher priority than any predefined group. #### Example Put all properties starting with `id` and `name` at the top, combine and sort metadata and optional multiline properties at the bottom. Anything else is put in the middle. ```ts interface User { id: string // top name: string // top age: number // unknown isAdmin: boolean // unknown lastUpdated_metadata: Date // bottom localization?: { // optional-multiline-member // Stuff about localization } version_metadata: string // bottom } ``` `groups` and `customGroups` configuration: ```ts { groups: [ + 'top', // [!code ++] 'unknown', + ['optional-multiline-member', 'bottom'] // [!code ++] ], + customGroups: [ // [!code ++] + { // [!code ++] + groupName: 'top', // [!code ++] + selector: 'property', // [!code ++] + elementNamePattern: '^(?:id|name)$', // [!code ++] + }, // [!code ++] + { // [!code ++] + groupName: 'bottom', // [!code ++] + selector: 'property', // [!code ++] + elementNamePattern: '.+_metadata$', // [!code ++] + } // [!code ++] + ] // [!code ++] } ``` ## Usage **Flat Config** ```tsx // eslint.config.js import perfectionist from 'eslint-plugin-perfectionist' export default [ { plugins: { perfectionist, }, rules: { 'perfectionist/sort-interfaces': [ 'error', { type: 'alphabetical', order: 'asc', fallbackSort: { type: 'unsorted' }, ignoreCase: true, specialCharacters: 'keep', sortBy: 'name', partitionByComment: false, partitionByNewLine: false, newlinesBetween: 'ignore', newlinesInside: 'ignore', useConfigurationIf: {}, groups: [], customGroups: [], }, ], }, }, ] ``` **Legacy Config** ```tsx // .eslintrc.js module.exports = { plugins: [ 'perfectionist', ], rules: { 'perfectionist/sort-interfaces': [ 'error', { type: 'alphabetical', order: 'asc', fallbackSort: { type: 'unsorted' }, ignoreCase: true, specialCharacters: 'keep', sortBy: 'name', partitionByComment: false, partitionByNewLine: false, newlinesBetween: 'ignore', newlinesInside: 'ignore', useConfigurationIf: {}, groups: [], customGroups: [], }, ], }, } ``` ## Version This rule was introduced in [v0.1.0](https://github.com/azat-io/eslint-plugin-perfectionist/releases/tag/v0.1.0). ## Resources - [Rule source](https://github.com/azat-io/eslint-plugin-perfectionist/blob/main/rules/sort-interfaces.ts) - [Test source](https://github.com/azat-io/eslint-plugin-perfectionist/blob/main/test/rules/sort-interfaces.test.ts)