diff --git a/packages/eslint-plugin/README.md b/packages/eslint-plugin/README.md index cdf79f97f3f..21100c9cb56 100644 --- a/packages/eslint-plugin/README.md +++ b/packages/eslint-plugin/README.md @@ -160,7 +160,7 @@ Pro Tip: For larger codebases you may want to consider splitting our linting int | [`@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: | | [`@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: | | [`@typescript-eslint/quotes`](./docs/rules/quotes.md) | Enforce the consistent use of either backticks, double, or single quotes | | :wrench: | | -| [`@typescript-eslint/require-array-sort-compare`](./docs/rules/require-array-sort-compare.md) | Enforce giving `compare` argument to `Array#sort` | | | :thought_balloon: | +| [`@typescript-eslint/require-array-sort-compare`](./docs/rules/require-array-sort-compare.md) | Requires `Array#sort` calls to always provide a `compareFunction` | | | :thought_balloon: | | [`@typescript-eslint/require-await`](./docs/rules/require-await.md) | Disallow async functions which have no `await` expression | :heavy_check_mark: | | :thought_balloon: | | [`@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: | | [`@typescript-eslint/restrict-template-expressions`](./docs/rules/restrict-template-expressions.md) | Enforce template literal expressions to be of string type | | | :thought_balloon: | diff --git a/packages/eslint-plugin/docs/rules/require-array-sort-compare.md b/packages/eslint-plugin/docs/rules/require-array-sort-compare.md index 5b30533a9e9..3a939f7d149 100644 --- a/packages/eslint-plugin/docs/rules/require-array-sort-compare.md +++ b/packages/eslint-plugin/docs/rules/require-array-sort-compare.md @@ -1,21 +1,23 @@ -# Enforce giving `compare` argument to `Array#sort` (`require-array-sort-compare`) +# Requires `Array#sort` calls to always provide a `compareFunction` (`require-array-sort-compare`) -This rule prevents to invoke `Array#sort()` method without `compare` argument. +This rule prevents invoking the `Array#sort()` method without providing a `compare` argument. -`Array#sort()` method sorts that element by the alphabet order. +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. + +The result is that elements are sorted alphabetically, regardless of their type. +When sorting numbers, this results in the classic "10 before 2" order: ```ts [1, 2, 3, 10, 20, 30].sort(); //→ [1, 10, 2, 20, 3, 30] ``` -The language specification also noted this trap. +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: > 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.
> https://www.ecma-international.org/ecma-262/9.0/#sec-sortcompare ## Rule Details -This rule is aimed at preventing the calls of `Array#sort` method. -This rule ignores the `sort` methods of user-defined types. +This rule aims to ensure all calls of the native `Array#sort` method provide a `compareFunction`, while ignoring calls to user-defined `sort` methods. Examples of **incorrect** code for this rule: @@ -25,7 +27,7 @@ const stringArray: string[]; array.sort(); -// Even if a string array, warns it in favor of `String#localeCompare` method. +// String arrays should be sorted using `String#localeCompare`. stringArray.sort(); ``` @@ -41,9 +43,9 @@ array.sort((a, b) => a.localeCompare(b)); userDefinedType.sort(); ``` -### Options +## Options -There is no option. +None. ## When Not To Use It diff --git a/packages/eslint-plugin/src/rules/require-array-sort-compare.ts b/packages/eslint-plugin/src/rules/require-array-sort-compare.ts index 580b36f591d..25c4c2e5747 100644 --- a/packages/eslint-plugin/src/rules/require-array-sort-compare.ts +++ b/packages/eslint-plugin/src/rules/require-array-sort-compare.ts @@ -9,7 +9,8 @@ export default util.createRule({ meta: { type: 'problem', docs: { - description: 'Enforce giving `compare` argument to `Array#sort`', + description: + 'Requires `Array#sort` calls to always provide a `compareFunction`', category: 'Best Practices', recommended: false, requiresTypeChecking: true,