8000 docs(eslint-plugin): improve doc for `requ-array-sort-comp` (#1434) · alex-dow/typescript-eslint@4ee1a25 · GitHub
[go: up one dir, main page]
Skip to content

Commit 4ee1a25

Browse files
G-Rathbradzacher
G-Rath
authored and
bradzacher
committed
docs(eslint-plugin): improve doc for requ-array-sort-comp (typescript-eslint#1434)
1 parent c69e402 commit 4ee1a25

File tree

3 files changed

+14
-11
lines changed

3 files changed

+14
-11
lines changed

‎packages/eslint-plugin/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,7 @@ Pro Tip: For larger codebases you may want to consider splitting our linting int
160160
| [`@typescript-eslint/prefer-string-starts-ends-with`](./docs/rules/prefer-string-starts-ends-with.md) | Enforce the use of `String#startsWith` and `String#endsWith` instead of other equivalent methods of checking substrings | :heavy_check_mark: | :wrench: | :thought_balloon: |
161161
| [`@typescript-eslint/promise-function-async`](./docs/rules/promise-function-async.md) | Requires any function or method that returns a Promise to be marked async | | | :thought_balloon: |
162162
| [`@typescript-eslint/quotes`](./docs/rules/quotes.md) | Enforce the consistent use of either backticks, double, or single quotes | | :wrench: | |
163-
| [`@typescript-eslint/require-array-sort-compare`](./docs/rules/require-array-sort-compare.md) | Enforce giving `compare` argument to `Array#sort` | | | :thought_balloon: |
163+
| [`@typescript-eslint/require-array-sort-compare`](./docs/rules/require-array-sort-compare.md) | Requires `Array#sort` calls to always provide a `compareFunction` | | | :thought_balloon: |
164164
| [`@typescript-eslint/require-await`](./docs/rules/require-await.md) | Disallow async functions which have no `await` expression | :heavy_check_mark: | | :thought_balloon: |
165165
| [`@typescript-eslint/restrict-plus-operands`](./docs/rules/restrict-plus-operands.md) | When adding two variables, operands must both be of type number or of type string | | | :thought_balloon: |
166166
| [`@typescript-eslint/restrict-template-expressions`](./docs/rules/restrict-template-expressions.md) | Enforce template literal expressions to be of string type | | | :thought_balloon: |

‎packages/eslint-plugin/docs/rules/require-array-sort-compare.md

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,23 @@
1-
# Enforce giving `compare` argument to `Array#sort` (`require-array-sort-compare`)
1+
# Requires `Array#sort` calls to always provide a `compareFunction` (`require-array-sort-compare`)
22

3-
This rule prevents to invoke `Array#sort()` method without `compare` argument.
3+
This rule prevents invoking the `Array#sort()` method without providing a `compare` argument.
44

5-
`Array#sort()` method sorts that element by the alphabet order.
5+
When called without a compare function, `Array#sort()` converts all non-undefined array elements into strings and then compares said strings based off their UTF-16 code units.
6+
7+
The result is that elements are sorted alphabetically, regardless of their type.
8+
When sorting numbers, this results in the classic "10 before 2" order:
69

710
```ts
811
[1, 2, 3, 10, 20, 30].sort(); //→ [1, 10, 2, 20, 3, 30]
912
```
1013

11-
The language specification also noted this trap.
14+
This also means that `Array#sort` does not always sort consistently, as elements may have custom `#toString` implementations that are not deterministic; this trap is noted in the noted in the language specification thusly:
1215

1316
> NOTE 2: Method calls performed by the `ToString` abstract operations in steps 5 and 7 have the potential to cause `SortCompare` to not behave as a consistent comparison function.<br> > https://www.ecma-international.org/ecma-262/9.0/#sec-sortcompare
1417
1518
## Rule Details
1619

17-
This rule is aimed at preventing the calls of `Array#sort` method.
18-
This rule ignores the `sort` methods of user-defined types.
20+
This rule aims to ensure all calls of the native `Array#sort` method provide a `compareFunction`, while ignoring calls to user-defined `sort` methods.
1921

2022
Examples of **incorrect** code for this rule:
2123

@@ -25,7 +27,7 @@ const stringArray: string[];
2527

2628
array.sort();
2729

28-
// Even if a string array, warns it in favor of `String#localeCompare` method.
30+
// String arrays should be sorted using `String#localeCompare`.
2931
stringArray.sort();
3032
```
3133

@@ -41,9 +43,9 @@ array.sort((a, b) => a.localeCompare(b));
4143
userDefinedType.sort();
4244
```
4345

44-
### Options
46+
## Options
4547

46-
There is no option.
48+
None.
4749

4850
## When Not To Use It
4951

‎packages/eslint-plugin/src/rules/require-array-sort-compare.ts

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@ export default util.createRule({
99
meta: {
1010
type: 'problem',
1111
docs: {
12-
description: 'Enforce giving `compare` argument to `Array#sort`',
12+
description:
13+
'Requires `Array#sort` calls to always provide a `compareFunction`',
1314
category: 'Best Practices',
1415
recommended: false,
1516
requiresTypeChecking: true,

0 commit comments

Comments
 (0)
0