Skip to content

Commit 317baaa

Browse files
hugop95hugop95
authoredJan 18, 2025··
feat(sort-maps): add groups, custom groups and new lines between options
·
v4.11.0v4.7.0
1 parent a6e1daf commit 317baaa

File tree

6 files changed

+1025
-66
lines changed

6 files changed

+1025
-66
lines changed
 

‎docs/content/rules/sort-array-includes.mdx

+2-2
Original file line numberDiff line numberDiff line change
@@ -239,11 +239,11 @@ Each group of elements (separated by empty lines) is treated independently, and
239239
</sub>
240240
<sub>default: `{}`</sub>
241241

242-
Allows you to specify filters to match a particular options configuration for a given object.
242+
Allows you to specify filters to match a particular options configuration for a given array.
243243

244244
The first matching options configuration will be used. If no configuration matches, the default options configuration will be used.
245245

246-
- `allNamesMatchPattern` — A regexp pattern that all object keys must match.
246+
- `allNamesMatchPattern` — A regexp pattern that all array keys must match.
247247

248248
Example configuration:
249249
```ts

‎docs/content/rules/sort-maps.mdx

+134
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,7 @@ Specifies the sorting method.
8989
- `'natural'` — Sort items in a [natural](https://github.com/yobacca/natural-orderby) order (e.g., “item2” < “item10”).
9090
- `'line-length'` — Sort items by the length of the code line (shorter lines first).
9191
- `'custom'` — Sort items using the alphabet entered in the [`alphabet`](#alphabet) option.
92+
- `'unsorted'` — Do not sort items. To be used with the [`useConfigurationIf`](#useconfigurationif) option.
9293

9394
### order
9495

@@ -177,6 +178,131 @@ new Map([
177178

178179
Each group of map members (separated by empty lines) is treated independently, and the order within each group is preserved.
179180

181+
### newlinesBetween
182+
183+
<sub>default: `'ignore'`</sub>
184+
185+
Specifies how new lines should be handled between map members.
186+
187+
- `ignore` — Do not report errors related to new lines between map members.
188+
- `always` — Enforce one new line between each group, and forbid new lines inside a group.
189+
- `never` — No new lines are allowed in maps.
190+
191+
This option is only applicable when `partitionByNewLine` is `false`.
192+
193+
### useConfigurationIf
194+
195+
<sub>
196+
type: `{ allNamesMatchPattern?: string }`
197+
</sub>
198+
<sub>default: `{}`</sub>
199+
200+
Allows you to specify filters to match a particular options configuration for a given map.
201+
202+
The first matching options configuration will be used. If no configuration matches, the default options configuration will be used.
203+
204+
- `allNamesMatchPattern` — A regexp pattern that all map keys must match.
205+
206+
Example configuration:
207+
```ts
208+
{
209+
'perfectionist/sort-maps': [
210+
'error',
211+
{
212+
groups: ['r', 'g', 'b'], // Sort colors by RGB
213+
customGroups: [
214+
{
215+
elementNamePattern: '^r$',
216+
groupName: 'r',
217+
},
218+
{
219+
elementNamePattern: '^g$',
220+
groupName: 'g',
221+
},
222+
{
223+
elementNamePattern: '^b$',
224+
groupName: 'b',
225+
},
226+
],
227+
useConfigurationIf: {
228+
allNamesMatchPattern: '^r|g|b$',
229+
},
230+
},
231+
{
232+
type: 'alphabetical' // Fallback configuration
233+
}
234+
],
235+
}
236+
```
237+
238+
### groups
239+
240+
<sub>
241+
type: `Array<string | string[]>`
242+
</sub>
243+
<sub>default: `[]`</sub>
244+
245+
Allows you to specify a list of groups for sorting. Groups help organize elements into categories.
246+
247+
Each element will be assigned a single group specified in the `groups` option (or the `unknown` group if no match is found).
248+
The order of items in the `groups` option determines how groups are ordered.
249+
250+
Within a given group, members will be sorted according to the `type`, `order`, `ignoreCase`, etc. options.
251+
252+
Individual groups can be combined together by placing them in an array. The order of groups in that array does not matter.
253+
All members of the groups in the array will be sorted together as if they were part of a single group.
254+
255+
### customGroups
256+
257+
<sub>
258+
type: `Array<CustomGroupDefinition | CustomGroupAnyOfDefinition>`
259+
</sub>
260+
<sub>default: `{}`</sub>
261+
262+
You can define your own groups and use regexp patterns to match specific elements.
263+
264+
A custom group definition may follow one of the two following interfaces:
265+
266+
```ts
267+
interface CustomGroupDefinition {
268+
groupName: string
269+
type?: 'alphabetical' | 'natural' | 'line-length' | 'unsorted'
270+
order?: 'asc' | 'desc'
271+
elementNamePattern?: string
272+
}
273+
274+
```
275+
An array element will match a `CustomGroupDefinition` group if it matches all the filters of the custom group's definition.
276+
277+
or:
278+
279+
```ts
280+
interface CustomGroupAnyOfDefinition {
281+
groupName: string
282+
type?: 'alphabetical' | 'natural' | 'line-length' | 'unsorted'
283+
order?: 'asc' | 'desc'
284+
anyOf: Array<{
285+
elementNamePattern?: string
286+
}>
287+
}
288+
```
289+
290+
An array element will match a `CustomGroupAnyOfDefinition` group if it matches all the filters of at least one of the `anyOf` items.
291+
292+
#### Attributes
293+
294+
- `groupName`: The group's name, which needs to be put in the `groups` option.
295+
- `elementNamePattern`: If entered, will check that the name of the element matches the pattern entered.
296+
- `type`: Overrides the sort type for that custom group. `unsorted` will not sort the group.
297+
- `order`: Overrides the sort order for that custom group
298+
299+
#### Match importance
300+
301+
The `customGroups` list is ordered:
302+
The first custom group definition that matches an element will be used.
303+
304+
Custom groups have a higher priority than any predefined group.
305+
180306
## Usage
181307

182308
<CodeTabs
@@ -201,6 +327,10 @@ Each group of map members (separated by empty lines) is treated independently, a
201327
specialCharacters: 'keep',
202328
partitionByNewLine: false,
203329
partitionByComment: false,
330+
newlinesBetween: false,
331+
useConfigurationIf: {},
332+
groups: [],
333+
customGroups: [],
204334
},
205335
],
206336
},
@@ -227,6 +357,10 @@ Each group of map members (separated by empty lines) is treated independently, a
227357
specialCharacters: 'keep',
228358
partitionByNewLine: false,
229359
partitionByComment: false,
360+
newlinesBetween: false,
361+
useConfigurationIf: {},
362+
groups: [],
363+
customGroups: [],
230364
},
231365
],
232366
},

‎rules/sort-maps.ts

+161-64
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,69 @@
1-
import type { TSESTree } from '@typescript-eslint/types'
1+
import type { TSESLint } from '@typescript-eslint/utils'
2+
3+
import { TSESTree } from '@typescript-eslint/types'
24

35
import type { SortingNode } from '../types/sorting-node'
6+
import type { Options } from './sort-maps/types'
47

58
import {
9+
buildUseConfigurationIfJsonSchema,
10+
buildCustomGroupsArrayJsonSchema,
611
partitionByCommentJsonSchema,
712
partitionByNewLineJsonSchema,
813
specialCharactersJsonSchema,
14+
newlinesBetweenJsonSchema,
915
ignoreCaseJsonSchema,
1016
buildTypeJsonSchema,
1117
alphabetJsonSchema,
1218
localesJsonSchema,
19+
groupsJsonSchema,
1320
orderJsonSchema,
1421
} from '../utils/common-json-schemas'
22+
import { validateGeneratedGroupsConfiguration } from '../utils/validate-generated-groups-configuration'
1523
import { validateCustomSortConfiguration } from '../utils/validate-custom-sort-configuration'
24+
import { getCustomGroupsCompareOptions } from '../utils/get-custom-groups-compare-options'
25+
import { getMatchingContextOptions } from '../utils/get-matching-context-options'
1626
import { getEslintDisabledLines } from '../utils/get-eslint-disabled-lines'
27+
import { doesCustomGroupMatch } from './sort-maps/does-custom-group-match'
1728
import { isNodeEslintDisabled } from '../utils/is-node-eslint-disabled'
1829
import { hasPartitionComment } from '../utils/has-partition-comment'
1930
import { createNodeIndexMap } from '../utils/create-node-index-map'
31+
import { sortNodesByGroups } from '../utils/sort-nodes-by-groups'
2032
import { getCommentsBefore } from '../utils/get-comments-before'
33+
import { getNewlinesErrors } from '../utils/get-newlines-errors'
34+
import { singleCustomGroupJsonSchema } from './sort-maps/types'
2135
import { createEslintRule } from '../utils/create-eslint-rule'
2236
import { getLinesBetween } from '../utils/get-lines-between'
37+
import { getGroupNumber } from '../utils/get-group-number'
2338
import { getSourceCode } from '../utils/get-source-code'
2439
import { toSingleLine } from '../utils/to-single-line'
2540
import { rangeToDiff } from '../utils/range-to-diff'
2641
import { getSettings } from '../utils/get-settings'
2742
import { isSortable } from '../utils/is-sortable'
2843
import { makeFixes } from '../utils/make-fixes'
29-
import { sortNodes } from '../utils/sort-nodes'
44+
import { useGroups } from '../utils/use-groups'
3045
import { complete } from '../utils/complete'
3146
import { pairwise } from '../utils/pairwise'
3247

33-
type Options = [
34-
Partial<{
35-
partitionByComment:
36-
| {
37-
block?: string[] | boolean | string
38-
line?: string[] | boolean | string
39-
}
40-
| string[]
41-
| boolean
42-
| string
43-
type: 'alphabetical' | 'line-length' | 'natural' | 'custom'
44-
specialCharacters: 'remove' | 'trim' | 'keep'
45-
locales: NonNullable<Intl.LocalesArgument>
46-
partitionByNewLine: boolean
47-
order: 'desc' | 'asc'
48-
ignoreCase: boolean
49-
alphabet: string
50-
}>,
51-
]
52-
53-
type MESSAGE_ID = 'unexpectedMapElementsOrder'
48+
type MESSAGE_ID =
49+
| 'missedSpacingBetweenMapElementsMembers'
50+
| 'extraSpacingBetweenMapElementsMembers'
51+
| 'unexpectedMapElementsGroupOrder'
52+
| 'unexpectedMapElementsOrder'
5453

5554
let defaultOptions: Required<Options[0]> = {
5655
specialCharacters: 'keep',
5756
partitionByComment: false,
5857
partitionByNewLine: false,
58+
newlinesBetween: 'ignore',
59+
useConfigurationIf: {},
5960
type: 'alphabetical',
6061
ignoreCase: true,
62+
customGroups: [],
6163
locales: 'en-US',
6264
alphabet: '',
6365
order: 'asc',
66+
groups: [],
6467
}
6568

6669
export default createEslintRule<Options, MESSAGE_ID>({
@@ -79,11 +82,29 @@ export default createEslintRule<Options, MESSAGE_ID>({
7982
return
8083
}
8184

85+
let sourceCode = getSourceCode(context)
8286
let settings = getSettings(context.settings)
83-
let options = complete(context.options.at(0), settings, defaultOptions)
87+
88+
let matchedContextOptions = getMatchingContextOptions({
89+
nodeNames: elements
90+
.filter(
91+
element =>
92+
element !== null &&
93+
element.type !== TSESTree.AST_NODE_TYPES.SpreadElement,
94+
)
95+
.map(element => getNodeName({ sourceCode, element })),
96+
contextOptions: context.options,
97+
})
98+
99+
let options = complete(matchedContextOptions[0], settings, defaultOptions)
84100
validateCustomSortConfiguration(options)
101+
validateGeneratedGroupsConfiguration({
102+
customGroups: options.customGroups,
103+
groups: options.groups,
104+
selectors: [],
105+
modifiers: [],
106+
})
85107

86-
let sourceCode = getSourceCode(context)
87108
let eslintDisabledLines = getEslintDisabledLines({
88109
ruleName: context.id,
89110
sourceCode,
@@ -106,29 +127,39 @@ export default createEslintRule<Options, MESSAGE_ID>({
106127
for (let part of parts) {
107128
let formattedMembers: SortingNode[][] = [[]]
108129
for (let element of part) {
109-
let name: string
130+
let name: string = getNodeName({
131+
sourceCode,
132+
element,
133+
})
110134

111-
if (element.type === 'ArrayExpression') {
112-
let [left] = element.elements
135+
let lastSortingNode = formattedMembers.at(-1)?.at(-1)
113136

114-
if (!left) {
115-
name = `${left}`
116-
} else if (left.type === 'Literal') {
117-
name = left.raw
118-
} else {
119-
name = sourceCode.getText(left)
137+
let { defineGroup, getGroup } = useGroups(options)
138+
for (let customGroup of options.customGroups) {
139+
if (
140+
doesCustomGroupMatch({
141+
elementName: name,
142+
customGroup,
143+
})
144+
) {
145+
defineGroup(customGroup.groupName, true)
146+
/**
147+
* If the custom group is not referenced in the `groups` option, it
148+
* will be ignored
149+
*/
150+
if (getGroup() === customGroup.groupName) {
151+
break
152+
}
120153
}
121-
} else {
122-
name = sourceCode.getText(element)
123154
}
124155

125-
let lastSortingNode = formattedMembers.at(-1)?.at(-1)
126156
let sortingNode: SortingNode = {
127157
isEslintDisabled: isNodeEslintDisabled(
128158
element,
129159
eslintDisabledLines,
130160
),
131161
size: rangeToDiff(element, sourceCode),
162+
group: getGroup(),
132163
node: element,
133164
name,
134165
}
@@ -155,7 +186,11 @@ export default createEslintRule<Options, MESSAGE_ID>({
155186
let sortNodesExcludingEslintDisabled = (
156187
ignoreEslintDisabledNodes: boolean,
157188
): SortingNode[] =>
158-
sortNodes(nodes, options, { ignoreEslintDisabledNodes })
189+
sortNodesByGroups(nodes, options, {
190+
getGroupCompareOptions: groupNumber =>
191+
getCustomGroupsCompareOptions(options, groupNumber),
192+
ignoreEslintDisabledNodes,
193+
})
159194
let sortedNodes = sortNodesExcludingEslintDisabled(false)
160195
let sortedNodesExcludingEslintDisabled =
161196
sortNodesExcludingEslintDisabled(true)
@@ -166,69 +201,131 @@ export default createEslintRule<Options, MESSAGE_ID>({
166201
let leftIndex = nodeIndexMap.get(left)!
167202
let rightIndex = nodeIndexMap.get(right)!
168203

204+
let leftNumber = getGroupNumber(options.groups, left)
205+
let rightNumber = getGroupNumber(options.groups, right)
206+
169207
let indexOfRightExcludingEslintDisabled =
170208
sortedNodesExcludingEslintDisabled.indexOf(right)
209+
210+
let messageIds: MESSAGE_ID[] = []
211+
171212
if (
172-
leftIndex < rightIndex &&
173-
leftIndex < indexOfRightExcludingEslintDisabled
213+
leftIndex > rightIndex ||
214+
leftIndex >= indexOfRightExcludingEslintDisabled
174215
) {
175-
return
216+
messageIds.push(
217+
leftNumber === rightNumber
218+
? 'unexpectedMapElementsOrder'
219+
: 'unexpectedMapElementsGroupOrder',
220+
)
176221
}
177222

178-
context.report({
179-
fix: fixer =>
180-
makeFixes({
181-
sortedNodes: sortedNodesExcludingEslintDisabled,
182-
sourceCode,
183-
options,
184-
fixer,
185-
nodes,
186-
}),
187-
data: {
188-
right: toSingleLine(right.name),
189-
left: toSingleLine(left.name),
190-
},
191-
messageId: 'unexpectedMapElementsOrder',
192-
node: right.node,
193-
})
223+
messageIds = [
224+
...messageIds,
225+
...getNewlinesErrors({
226+
missedSpacingError: 'missedSpacingBetweenMapElementsMembers',
227+
extraSpacingError: 'extraSpacingBetweenMapElementsMembers',
228+
rightNum: rightNumber,
229+
leftNum: leftNumber,
230+
sourceCode,
231+
options,
232+
right,
233+
left,
234+
}),
235+
]
236+
237+
for (let messageId of messageIds) {
238+
context.report({
239+
fix: fixer =>
240+
makeFixes({
241+
sortedNodes: sortedNodesExcludingEslintDisabled,
242+
sourceCode,
243+
options,
244+
fixer,
245+
nodes,
246+
}),
247+
data: {
248+
right: toSingleLine(right.name),
249+
left: toSingleLine(left.name),
250+
rightGroup: right.group,
251+
leftGroup: left.group,
252+
},
253+
node: right.node,
254+
messageId,
255+
})
256+
}
194257
})
195258
}
196259
}
197260
},
198261
}),
199262
meta: {
200-
schema: [
201-
{
263+
schema: {
264+
items: {
202265
properties: {
203266
partitionByComment: {
204267
...partitionByCommentJsonSchema,
205268
description:
206269
'Allows you to use comments to separate the maps members into logical groups.',
207270
},
271+
customGroups: buildCustomGroupsArrayJsonSchema({
272+
singleCustomGroupJsonSchema,
273+
}),
274+
useConfigurationIf: buildUseConfigurationIfJsonSchema(),
208275
partitionByNewLine: partitionByNewLineJsonSchema,
209276
specialCharacters: specialCharactersJsonSchema,
277+
newlinesBetween: newlinesBetweenJsonSchema,
210278
ignoreCase: ignoreCaseJsonSchema,
211279
alphabet: alphabetJsonSchema,
212280
type: buildTypeJsonSchema(),
213281
locales: localesJsonSchema,
282+
groups: groupsJsonSchema,
214283
order: orderJsonSchema,
215284
},
216285
additionalProperties: false,
217286
type: 'object',
218287
},
219-
],
220-
docs: {
221-
url: 'https://perfectionist.dev/rules/sort-maps',
222-
description: 'Enforce sorted Map elements.',
223-
recommended: true,
288+
uniqueItems: true,
289+
type: 'array',
224290
},
225291
messages: {
292+
unexpectedMapElementsGroupOrder:
293+
'Expected "{{right}}" ({{rightGroup}}) to come before "{{left}}" ({{leftGroup}}).',
294+
missedSpacingBetweenMapElementsMembers:
295+
'Missed spacing between "{{left}}" and "{{right}}" members.',
296+
extraSpacingBetweenMapElementsMembers:
297+
'Extra spacing between "{{left}}" and "{{right}}" members.',
226298
unexpectedMapElementsOrder:
227299
'Expected "{{right}}" to come before "{{left}}".',
228300
},
301+
docs: {
302+
url: 'https://perfectionist.dev/rules/sort-maps',
303+
description: 'Enforce sorted Map elements.',
304+
recommended: true,
305+
},
229306
type: 'suggestion',
230307
fixable: 'code',
231308
},
232309
defaultOptions: [defaultOptions],
233310
name: 'sort-maps',
234311
})
312+
313+
let getNodeName = ({
314+
sourceCode,
315+
element,
316+
}: {
317+
sourceCode: TSESLint.SourceCode
318+
element: TSESTree.Expression
319+
}): string => {
320+
if (element.type === 'ArrayExpression') {
321+
let [left] = element.elements
322+
323+
if (!left) {
324+
return `${left}`
325+
} else if (left.type === 'Literal') {
326+
return left.raw
327+
}
328+
return sourceCode.getText(left)
329+
}
330+
return sourceCode.getText(element)
331+
}

‎rules/sort-maps/does-custom-group-match.ts

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
import type { SingleCustomGroup, AnyOfCustomGroup } from './types'
2+
3+
import { matches } from '../../utils/matches'
4+
5+
interface DoesCustomGroupMatchProps {
6+
customGroup: SingleCustomGroup | AnyOfCustomGroup
7+
elementName: string
8+
}
9+
10+
export let doesCustomGroupMatch = (
11+
props: DoesCustomGroupMatchProps,
12+
): boolean => {
13+
if ('anyOf' in props.customGroup) {
14+
// At least one subgroup must match
15+
return props.customGroup.anyOf.some(subgroup =>
16+
doesCustomGroupMatch({ ...props, customGroup: subgroup }),
17+
)
18+
}
19+
20+
if (
21+
'elementNamePattern' in props.customGroup &&
22+
props.customGroup.elementNamePattern
23+
) {
24+
let matchesElementNamePattern: boolean = matches(
25+
props.elementName,
26+
props.customGroup.elementNamePattern,
27+
)
28+
if (!matchesElementNamePattern) {
29+
return false
30+
}
31+
}
32+
33+
return true
34+
}

‎rules/sort-maps/types.ts

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
import type { JSONSchema4 } from '@typescript-eslint/utils/json-schema'
2+
3+
import { elementNamePatternJsonSchema } from '../../utils/common-json-schemas'
4+
5+
export type Options = Partial<{
6+
partitionByComment:
7+
| {
8+
block?: string[] | boolean | string
9+
line?: string[] | boolean | string
10+
}
11+
| string[]
12+
| boolean
13+
| string
14+
groups: (
15+
| { newlinesBetween: 'ignore' | 'always' | 'never' }
16+
| Group[]
17+
| Group
18+
)[]
19+
useConfigurationIf: {
20+
allNamesMatchPattern?: string
21+
}
22+
type: 'alphabetical' | 'line-length' | 'natural' | 'custom'
23+
newlinesBetween: 'ignore' | 'always' | 'never'
24+
specialCharacters: 'remove' | 'trim' | 'keep'
25+
locales: NonNullable<Intl.LocalesArgument>
26+
partitionByNewLine: boolean
27+
customGroups: CustomGroup[]
28+
order: 'desc' | 'asc'
29+
ignoreCase: boolean
30+
alphabet: string
31+
}>[]
32+
33+
export interface SingleCustomGroup {
34+
elementNamePattern?: string
35+
}
36+
37+
export interface AnyOfCustomGroup {
38+
anyOf: SingleCustomGroup[]
39+
}
40+
41+
type CustomGroup = (
42+
| {
43+
order?: Options[0]['order']
44+
type?: Options[0]['type']
45+
}
46+
| {
47+
type?: 'unsorted'
48+
}
49+
) &
50+
(SingleCustomGroup | AnyOfCustomGroup) & {
51+
groupName: string
52+
}
53+
54+
type Group = 'unknown' | string
55+
56+
export let singleCustomGroupJsonSchema: Record<string, JSONSchema4> = {
57+
elementNamePattern: elementNamePatternJsonSchema,
58+
}

‎test/rules/sort-maps.test.ts

+636
Large diffs are not rendered by default.

0 commit comments

Comments
 (0)
Please sign in to comment.