Skip to content

Commit f7a24d0

Browse files
mskeltonmskelton
authored
Merge pull request #16 from mskelton/rule-docs
Rule docs
2 parents 3092d91 + 2c58a0d commit f7a24d0

10 files changed

+230
-155
lines changed

‎README.md

+9-155
Original file line numberDiff line numberDiff line change
@@ -32,160 +32,14 @@ recommended configuration. This will enable all available rules as warnings.
3232
}
3333
```
3434

35-
## Rules
35+
## List of Supported Rules
3636

37-
While the recommended configuration is the simplest way to use this plugin, you
38-
can also configure the rules manually based on your needs.
37+
✔: Enabled in the `recommended` configuration.\
38+
🔧: Fixable with [`eslint --fix`](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems).
3939

40-
### `sort/object-properties` 🔧
41-
42-
Sorts object properties alphabetically and case insensitive in ascending order.
43-
44-
Examples of **incorrect** code for this rule.
45-
46-
```js
47-
var a = { b: 1, c: 2, a: 3 }
48-
var a = { C: 1, b: 2 }
49-
var a = { C: 1, b: { y: 1, x: 2 } }
50-
```
51-
52-
Examples of **correct** code for this rule.
53-
54-
```js
55-
var a = { a: 1, b: 2, c: 3 }
56-
var a = { b: 1, C: 2 }
57-
var a = { b: { x: 1, y: 2 }, C: 1 }
58-
```
59-
60-
### `sort/destructuring-properties` 🔧
61-
62-
Sorts properties in object destructuring patterns alphabetically and case
63-
insensitive in ascending order.
64-
65-
Examples of **incorrect** code for this rule.
66-
67-
```js
68-
let { b, c, a } = {}
69-
let { C, b } = {}
70-
let { b: a, a: b } = {}
71-
```
72-
73-
Examples of **correct** code for this rule.
74-
75-
```js
76-
let { a, b, c } = {}
77-
let { b, C } = {}
78-
let { a: b, b: a } = {}
79-
```
80-
81-
### `sort/import-members` 🔧
82-
83-
Sorts import members alphabetically and case insensitive in ascending order.
84-
85-
Examples of **incorrect** code for this rule.
86-
87-
```js
88-
import { b, c, a } from "a"
89-
import { C, b } from "a"
90-
import { b as a, a as b } from "a"
91-
```
92-
93-
Examples of **correct** code for this rule.
94-
95-
```js
96-
import { a, b, c } from "a"
97-
import { b, C } from "a"
98-
import { a as b, b as a } from "a"
99-
```
100-
101-
### `sort/imports` 🔧
102-
103-
Sorts imports alphabetically and case insensitive in ascending order.
104-
105-
Example of **incorrect** code for this rule.
106-
107-
```js
108-
import c from "c"
109-
import b from "b"
110-
import a from "a"
111-
```
112-
113-
Example of **correct** code for this rule.
114-
115-
```js
116-
import a from "a"
117-
import b from "b"
118-
import c from "c"
119-
```
120-
121-
#### Sort Groups
122-
123-
While the previous examples for this rule show very basic import sorting, this
124-
rule has a very powerful mechanism for sorting imports into groups. This allows
125-
you to separate common groups of imports to make it easier to scan your imports
126-
at a glance.
127-
128-
There are three built-in sort groups you can use:
129-
130-
1. `side-effect`
131-
- Imports without any imported variables (e.g. `import 'index.css'`).
132-
1. `dependency`
133-
- Imports which do not throw an error when calling `require.resolve`.
134-
- Useful for differentiating between path aliases (e.g. `components/Hello`)
135-
and dependencies (e.g. `react`)
136-
1. `other`
137-
- Catch all sort group for any imports which did not match other sort groups.
138-
139-
You can also define custom regex sort groups if the built-in sort groups aren't
140-
enough. The following configuration shows an example of using the built-in sort
141-
groups as well as a custom regex sort group.
142-
143-
```json
144-
{
145-
"sort/imports": [
146-
"warn",
147-
{
148-
"groups": [
149-
{ "type": "side-effect", "order": 1 },
150-
{ "regex": "\\.(png|jpg|svg)$", "order": 4 },
151-
{ "type": "dependency", "order": 2 },
152-
{ "type": "other", "order": 3 }
153-
]
154-
}
155-
]
156-
}
157-
```
158-
159-
This configuration would result in the following output.
160-
161-
```js
162-
import "index.css"
163-
import React from "react"
164-
import { createStore } from "redux"
165-
import c from "c"
166-
import a from "../a"
167-
import b from "./b"
168-
import image1 from "my-library/static/image.svg"
169-
import image2 from "static/image.jpg"
170-
import image3 from "static/image.png"
171-
```
172-
173-
##### Order
174-
175-
It's important to understand the difference between the order of the sort groups
176-
in the `groups` array, and the `order` property of each sort group. When sorting
177-
imports, this plugin will find the first sort group which the import would apply
178-
to and then assign it an order using the `order` property. This allows you to
179-
define a hierarchy of sort groups in descending specificity (e.g. side effect
180-
then regex) while still having full control over the order of the sort groups in
181-
the resulting code.
182-
183-
For example, the `other` sort group will match any import and thus should always
184-
be last in the list of sort groups. However, if you want to sort static asset
185-
imports (e.g. `.png` or `.jpg`) after the `other` sort group, you can use the
186-
`order` property to give the static assets a higher order than the `other` sort
187-
group.
188-
189-
The configuration example above shows how this works where the static asset
190-
imports are the second sort group even though they have the highest order and
191-
are thus the last sort group in the resulting code.
40+
| ✔ | 🔧 | Rule | Description |
41+
| :-: | :-: | ----------------------------------------------------------------------- | -------------------------------- |
42+
| ✔ | 🔧 | [sort/destructuring-properties](docs/rules/destructuring-properties.md) | Destructuring Properties Sorting |
43+
| ✔ | 🔧 | [sort/import-members](docs/rules/import-members.md) | Import Member Sorting |
44+
| ✔ | 🔧 | [sort/imports](docs/rules/imports.md) | Import Sorting |
45+
| ✔ | 🔧 | [sort/object-properties](docs/rules/object-properties.md) | Object Property Sorting |

‎docs/rules/destructuring-properties.md

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Destructuring Properties Sorting (sort/destructuring-properties)
2+
3+
🔧 The `--fix` option on the command line can automatically fix the problems
4+
reported by this rule.
5+
6+
Sorts properties in object destructuring patterns alphabetically and case
7+
insensitive in ascending order.
8+
9+
## Rule Details
10+
11+
Examples of **incorrect** code for this rule:
12+
13+
```js
14+
let { b, c, a } = {}
15+
let { C, b } = {}
16+
let { b: a, a: b } = {}
17+
```
18+
19+
Examples of **correct** code for this rule:
20+
21+
```js
22+
let { a, b, c } = {}
23+
let { b, C } = {}
24+
let { a: b, b: a } = {}
25+
```
26+
27+
## When Not To Use It
28+
29+
This rule is a formatting preference and not following it won't negatively
30+
affect the quality of your code. If alphabetizing object properties isn't a part
31+
of your coding standards, then you can leave this rule off.

‎docs/rules/import-members.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Import Member Sorting (sort/import-members)
2+
3+
🔧 The `--fix` option on the command line can automatically fix the problems
4+
reported by this rule.
5+
6+
Sorts import members alphabetically and case insensitive in ascending order.
7+
8+
## Rule Details
9+
10+
Examples of **incorrect** code for this rule:
11+
12+
```js
13+
import { b, c, a } from "a"
14+
import { C, b } from "a"
15+
import { b as a, a as b } from "a"
16+
```
17+
18+
Examples of **correct** code for this rule:
19+
20+
```js
21+
import { a, b, c } from "a"
22+
import { b, C } from "a"
23+
import { a as b, b as a } from "a"
24+
```
25+
26+
## When Not To Use It
27+
28+
This rule is a formatting preference and not following it won't negatively
29+
affect the quality of your code. If alphabetizing object properties isn't a part
30+
of your coding standards, then you can leave this rule off.

‎docs/rules/imports.md

+108
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Import Sorting (sort/imports)
2+
3+
🔧 The `--fix` option on the command line can automatically fix the problems
4+
reported by this rule.
5+
6+
Sorts imports alphabetically and case insensitive in ascending order.
7+
8+
## Rule Details
9+
10+
Example of **incorrect** code for this rule:
11+
12+
```js
13+
import c from "c"
14+
import b from "b"
15+
import a from "a"
16+
```
17+
18+
Example of **correct** code for this rule:
19+
20+
```js
21+
import a from "a"
22+
import b from "b"
23+
import c from "c"
24+
```
25+
26+
## Rule Options
27+
28+
This rule has an object with its properties as:
29+
30+
- `"groups"` (default: `[]`)
31+
32+
### Groups
33+
34+
By default, this rule will perform basic alphanumeric sorting but you can
35+
greatly customize your import sorting with sort groups.This allows you to
36+
separate common groups of imports to make it easier to scan your imports at a
37+
glance.
38+
39+
There are three built-in sort groups you can use:
40+
41+
1. `side-effect`
42+
- Imports without any imported variables (e.g. `import 'index.css'`).
43+
1. `dependency`
44+
- Imports which do not throw an error when calling `require.resolve`.
45+
- Useful for differentiating between path aliases (e.g. `components/Hello`)
46+
and dependencies (e.g. `react`)
47+
1. `other`
48+
- Catch all sort group for any imports which did not match other sort groups.
49+
50+
You can also define custom regex sort groups if the built-in sort groups aren't
51+
enough. The following configuration shows an example of using the built-in sort
52+
groups as well as a custom regex sort group.
53+
54+
```json
55+
{
56+
"sort/imports": [
57+
"warn",
58+
{
59+
"groups": [
60+
{ "type": "side-effect", "order": 1 },
61+
{ "regex": "\\.(png|jpg|svg)$", "order": 4 },
62+
{ "type": "dependency", "order": 2 },
63+
{ "type": "other", "order": 3 }
64+
]
65+
}
66+
]
67+
}
68+
```
69+
70+
This configuration would result in the following output.
71+
72+
```js
73+
import "index.css"
74+
import React from "react"
75+
import { createStore } from "redux"
76+
import c from "c"
77+
import a from "../a"
78+
import b from "./b"
79+
import image1 from "my-library/static/image.svg"
80+
import image2 from "static/image.jpg"
81+
import image3 from "static/image.png"
82+
```
83+
84+
#### Group Order
85+
86+
It's important to understand the difference between the order of the sort groups
87+
in the `groups` array, and the `order` property of each sort group. When sorting
88+
imports, this plugin will find the first sort group which the import would apply
89+
to and then assign it an order using the `order` property. This allows you to
90+
define a hierarchy of sort groups in descending specificity (e.g. side effect
91+
then regex) while still having full control over the order of the sort groups in
92+
the resulting code.
93+
94+
For example, the `other` sort group will match any import and thus should always
95+
be last in the list of sort groups. However, if you want to sort static asset
96+
imports (e.g. `.png` or `.jpg`) after the `other` sort group, you can use the
97+
`order` property to give the static assets a higher order than the `other` sort
98+
group.
99+
100+
The configuration example above shows how this works where the static asset
101+
imports are the second sort group even though they have the highest order and
102+
are thus the last sort group in the resulting code.
103+
104+
## When Not To Use It
105+
106+
This rule is a formatting preference and not following it won't negatively
107+
affect the quality of your code. If alphabetizing object properties isn't a part
108+
of your coding standards, then you can leave this rule off.

‎docs/rules/object-properties.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Object Property Sorting (sort/object-properties)
2+
3+
🔧 The `--fix` option on the command line can automatically fix the problems
4+
reported by this rule.
5+
6+
Sorts object properties alphabetically and case insensitive in ascending order.
7+
8+
## Rule Details
9+
10+
Examples of **incorrect** code for this rule:
11+
12+
```js
13+
var a = { b: 1, c: 2, a: 3 }
14+
var a = { C: 1, b: 2 }
15+
var a = { C: 1, b: { y: 1, x: 2 } }
16+
```
17+
18+
Examples of **correct** code for this rule:
19+
20+
```js
21+
var a = { a: 1, b: 2, c: 3 }
22+
var a = { b: 1, C: 2 }
23+
var a = { b: { x: 1, y: 2 }, C: 1 }
24+
```
25+
26+
## When Not To Use It
27+
28+
This rule is a formatting preference and not following it won't negatively
29+
affect the quality of your code. If alphabetizing object properties isn't a part
30+
of your coding standards, then you can leave this rule off.

‎src/rules/destructuring-properties.ts

+4
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import { Rule } from "eslint"
22
import {
33
alphaSorter,
4+
docsURL,
45
enumerate,
56
filterNodes,
67
getName,
@@ -46,6 +47,9 @@ export default {
4647
meta: {
4748
type: "suggestion",
4849
fixable: "code",
50+
docs: {
51+
url: docsURL("destructuring-properties"),
52+
},
4953
messages: {
5054
unsorted: "Destructuring properties should be sorted alphabetically.",
5155
},

0 commit comments

Comments
 (0)