Skip to content

Commit

Permalink
feat: add custom sort type through custom alphabet
Browse files Browse the repository at this point in the history
* feat: adds alphabet generator

* We will be using that class in tests as well.

* feat: adds `custom` sort type

* feat: adds custom sort validation

* refactor: create function for each sort type

* test: adds tests for all rules

* The custom sort generated mimics `localeCompare()` for simplicity.
* I have added a single test with the `custom` sort type for each rule. I don't think that adding as many tests as other types is necessary: the objective is not to test that the behavior of a custom sort works for all rules, but rather to check that the rule handles that sorting type.
* Custom sorting behavior should be verified in `compare.ts`.

* refactor: moves some util files to `utils` folder

* docs: updates main pages

* docs: updates rules

* docs: improves style

* docs: fixes invalid documentation

* fix: fix invalid config creation

* fix: fixes typings

* refactor: [FEEDBACK] avoids using undefined

Co-authored-by: Azat S. <[email protected]>

* refactor: [FEEDBACK] avoids using undefined

Co-authored-by: Azat S. <[email protected]>

* refactor: [FEEDBACK] reduces comments length

* docs: [FEEDBACK] fixes missing `Alphabet`

* docs: [FEEDBACK] adds Astro section

* feat: [FEEDBACK] adds `convertBooleanToSign` function

* docs: added `Alphabet` documentation

- Removed `removeUnicodePlane` function, which is likely not that useful for users.

* build: [FEEDBACK] adds `eslint-plugin-perfectionist/alphabet` export

* docs: [FEEDBACK] adds `eslint-plugin-perfectionist/alphabet` export

* style: ESLint fix

---------

Co-authored-by: Azat S. <[email protected]>
  • Loading branch information
hugop95 and azat-io authored Dec 12, 2024
1 parent e2bf4e9 commit ac7d709
Show file tree
Hide file tree
Showing 83 changed files with 3,068 additions and 112 deletions.
199 changes: 199 additions & 0 deletions docs/content/configs/recommended-custom.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,199 @@
---
title: recommended-custom
description: Learn more about the recommended custom ESLint Plugin Perfectionist configuration for sorting and organizing your code. Take customization to new levels while maintaining a consistent coding style with this setup
shortDescription: All plugin rules with your own custom sorting
keywords:
- eslint
- recommended custom config
- eslint configuration
- coding standards
- code quality
- javascript linting
- custom sorting
- eslint-plugin-perfectionist
---

import CodeTabs from '../../components/CodeTabs.svelte'
import { dedent } from 'ts-dedent'

Configuration for the `eslint-plugin-perfectionist` plugin, which provides all plugin rules with your predefined custom ordered alphabet.

This configuration allows you to define your own custom order for sorting elements in your codebase as you truly desire.

## When to Use

Each rule in `eslint-plugin-perfectionist` offers a lot of options that should suit most use cases.

If this is not enough, you may define your own alphabet and use the `recommended-custom` configuration to enforce a consistent custom order across various data structures in your codebase.

Use this configuration to precisely tune how elements should be sorted while keeping readability and maintainability to their highest levels.

## Usage

You must provide an `alphabet` option in the `perfectionist` settings object or for each rule individually.
This option should be a string that represents an ordered alphabet.

Example: `01234564789abcdef...`

Use the `Alphabet` utility class from `eslint-plugin-perfectionist/alphabet` to quickly generate a custom alphabet.

<CodeTabs
code={[
{
source: dedent`
// eslint.config.js
import { Alphabet } from 'eslint-plugin-perfectionist/alphabet'
import perfectionist from 'eslint-plugin-perfectionist'
import naturalCompare from 'natural-compare-lite';
const myCustomAlphabet = Alphabet
.generateRecommendedAlphabet()
.sortingBy((a, b) => naturalCompare(a, b))
.getCharacters();
export default [
{
...perfectionist.configs['recommended-custom'],
settings: {
perfectionist: {
alphabet: myCustomAlphabet
}
}
}
]
`,
name: 'Flat Config',
value: 'flat',
},
{
source: dedent`
// .eslintrc.js
import { Alphabet } from 'eslint-plugin-perfectionist/alphabet'
import perfectionist from 'eslint-plugin-perfectionist'
import naturalCompare from 'natural-compare-lite';
const myCustomAlphabet = Alphabet
.generateRecommendedAlphabet()
.sortingBy((a, b) => naturalCompare(a, b))
.getCharacters();
module.exports = {
extends: [
'plugin:perfectionist/recommended-custom-legacy',
],
settings: {
perfectionist: {
alphabet: myCustomAlphabet
}
}
}
`,
name: 'Legacy Config',
value: 'legacy',
},
]}
type="config-type"
client:load
lang="tsx"
/>

## Alphabet class

The `Alphabet` class from `eslint-plugin-perfectionist/alphabet` provides a set of methods to generate and manipulate alphabets.

### Static generators

#### - `static generateCompleteAlphabet(): Alphabet`

Generates an alphabet containing all characters from the Unicode standard except for irrelevant [Unicode planes](https://en.wikipedia.org/wiki/Plane_(Unicode)).
Contains the Unicode planes 0, 1, 2 and 3.

#### - `static generateRecommendedAlphabet(): Alphabet`

Generates an alphabet containing relevant characters from the Unicode standard. Contains the [Unicode planes](https://en.wikipedia.org/wiki/Plane_(Unicode)) 0 and 1.

#### - `static generateFrom(values: string[] | string): Alphabet`

Generates an alphabet from the given characters.

### Adding/Removing characters

#### - `pushCharacters(values: string[] | string): this`

Adds specific characters to the end of the alphabet.

#### - `removeCharacters(values: string[] | string): this`

Removes specific characters from the alphabet.

#### - `removeUnicodeRange({ start: number; end: number }): this`

Removes specific characters from the alphabet by their range

### Sorters

#### - `sortByLocaleCompare(locales?: Intl.LocalesArgument): this`

Sorts the alphabet by the locale order of the characters.

#### - `sortByNaturalSort(locale?: string): this`

Sorts the alphabet by the natural order of the characters using [natural-orderby](https://github.com/yobacca/natural-orderby).

#### - `sortByCharCodeAt(): this`

Sorts the alphabet by the character code point.

#### - `sortBy(sortingFunction: (characterA: string, characterB: string) => number): this`

Sorts the alphabet by the sorting function provided

#### - `reverse(): this`

Reverses the alphabet.

### Other methods

#### - `prioritizeCase(casePriority: 'lowercase' | 'uppercase'): this`

For each character with a lower and upper case, permutes the two cases so that the alphabet is ordered by the case priority entered.

```ts
Alphabet.generateFrom('aAbBcdCD')
.prioritizeCase('uppercase')
// Returns 'AaBbCDcd'
````

#### - `placeAllWithCaseBeforeAllWithOtherCase(caseToComeFirst: 'uppercase' | 'lowercase'): this`

Permutes characters with cases so that all characters with the entered case are put before the other characters.

```ts
Alphabet.generateFrom('aAbBcCdD')
.placeAllWithCaseBeforeAllWithOtherCase('lowercase')
// Returns 'abcdABCD'
````
#### - `placeCharacterBefore({ characterBefore: string; characterAfter: string }): this`
Places a specific character right before another character in the alphabet.
```ts
Alphabet.generateFrom('ab-cd/')
.placeCharacterBefore({ characterBefore: '/', characterAfter: '-' })
// Returns 'ab/-cd'
```

#### - `placeCharacterAfter({ characterBefore: string; characterAfter: string }): this`

Places a specific character right after another character in the alphabet.

```ts
Alphabet.generateFrom('ab-cd/')
.placeCharacterAfter({ characterBefore: '/', characterAfter: '-' })
// Returns 'abcd/-'
```

#### - `getCharacters(): string`

Retrieves the characters from the alphabet.
3 changes: 2 additions & 1 deletion docs/content/guide/getting-started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -140,8 +140,9 @@ The highest priority is given to the settings of a particular rule. Next comes t

In settings you can set the following options:

- `type` — The type of sorting. Possible values are `'alphabetical'`, `'natural'` and `'line-length'`.
- `type` — The type of sorting. Possible values are `'alphabetical'`, `'natural'`, `'line-length'` and `custom`.
- `order` — The order of sorting. Possible values are `'asc'` and `'desc'`.
- `alphabet` — The custom alphabet to use when `type` is `custom`.
- `ignoreCase` — Ignore case when sorting.
- `ignorePattern` — Ignore sorting for elements that match the pattern.
- `specialCharacters` — Control whether special characters should be kept, trimmed or removed before sorting. Values can be `'keep'`, `'trim'` or `'remove'`.
Expand Down
11 changes: 11 additions & 0 deletions docs/content/rules/sort-array-includes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,7 @@ 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 the length of the code line (shorter lines first).
- `'custom'` — Sort items using the alphabet entered in the [`alphabet`](#alphabet) option.

### order

Expand All @@ -138,6 +139,16 @@ Determines whether the sorted items should be 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).

### alphabet

<sub>default: `''`</sub>

Only used when the [`type`](#type) option is set to `'custom'`. Specifies the custom alphabet to use when sorting.

Use the `Alphabet` utility class from `eslint-plugin-perfectionist/alphabet` to quickly generate a custom alphabet.

Example: `0123456789abcdef...`

### ignoreCase

<sub>default: `true`</sub>
Expand Down
11 changes: 11 additions & 0 deletions docs/content/rules/sort-classes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,7 @@ 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 the length of the code line (shorter lines first).
- `'custom'` — Sort items using the alphabet entered in the [`alphabet`](#alphabet) option.

### order

Expand All @@ -173,6 +174,16 @@ Determines whether the sorted items should be 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).

### alphabet

<sub>default: `''`</sub>

Only used when the [`type`](#type) option is set to `'custom'`. Specifies the custom alphabet to use when sorting.

Use the `Alphabet` utility class from `eslint-plugin-perfectionist/alphabet` to quickly generate a custom alphabet.

Example: `0123456789abcdef...`

### ignoreCase

<sub>default: `true`</sub>
Expand Down
11 changes: 11 additions & 0 deletions docs/content/rules/sort-decorators.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,7 @@ 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 the length of the code line (shorter lines first).
- `'custom'` — Sort items using the alphabet entered in the [`alphabet`](#alphabet) option.

### order

Expand All @@ -137,6 +138,16 @@ Determines whether the sorted items should be 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).

### alphabet

<sub>default: `''`</sub>

Only used when the [`type`](#type) option is set to `'custom'`. Specifies the custom alphabet to use when sorting.

Use the `Alphabet` utility class from `eslint-plugin-perfectionist/alphabet` to quickly generate a custom alphabet.

Example: `0123456789abcdef...`

### ignoreCase

<sub>default: `true`</sub>
Expand Down
11 changes: 11 additions & 0 deletions docs/content/rules/sort-enums.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@ 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 the length of the code line (shorter lines first).
- `'custom'` — Sort items using the alphabet entered in the [`alphabet`](#alphabet) option.

### order

Expand All @@ -103,6 +104,16 @@ Determines whether the sorted items should be 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).

### alphabet

<sub>default: `''`</sub>

Only used when the [`type`](#type) option is set to `'custom'`. Specifies the custom alphabet to use when sorting.

Use the `Alphabet` utility class from `eslint-plugin-perfectionist/alphabet` to quickly generate a custom alphabet.

Example: `0123456789abcdef...`

### ignoreCase

<sub>default: `true`</sub>
Expand Down
11 changes: 11 additions & 0 deletions docs/content/rules/sort-exports.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,7 @@ 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 the length of the code line (shorter lines first).
- `'custom'` — Sort items using the alphabet entered in the [`alphabet`](#alphabet) option.

### order

Expand All @@ -97,6 +98,16 @@ Determines whether the sorted items should be 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).

### alphabet

<sub>default: `''`</sub>

Only used when the [`type`](#type) option is set to `'custom'`. Specifies the custom alphabet to use when sorting.

Use the `Alphabet` utility class from `eslint-plugin-perfectionist/alphabet` to quickly generate a custom alphabet.

Example: `0123456789abcdef...`

### ignoreCase

<sub>default: `true`</sub>
Expand Down
11 changes: 11 additions & 0 deletions docs/content/rules/sort-heritage-clauses.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ 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 the length of the code line (shorter lines first).
- `'custom'` — Sort items using the alphabet entered in the [`alphabet`](#alphabet) option.

### order

Expand All @@ -80,6 +81,16 @@ Determines whether the sorted items should be 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).

### alphabet

<sub>default: `''`</sub>

Only used when the [`type`](#type) option is set to `'custom'`. Specifies the custom alphabet to use when sorting.

Use the `Alphabet` utility class from `eslint-plugin-perfectionist/alphabet` to quickly generate a custom alphabet.

Example: `0123456789abcdef...`

### ignoreCase

<sub>default: `true`</sub>
Expand Down
11 changes: 11 additions & 0 deletions docs/content/rules/sort-imports.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,7 @@ 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 the length of the code line (shorter lines first).
- `'custom'` — Sort items using the alphabet entered in the [`alphabet`](#alphabet) option.

### order

Expand All @@ -136,6 +137,16 @@ Determines whether the sorted items should be 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).

### alphabet

<sub>default: `''`</sub>

Only used when the [`type`](#type) option is set to `'custom'`. Specifies the custom alphabet to use when sorting.

Use the `Alphabet` utility class from `eslint-plugin-perfectionist/alphabet` to quickly generate a custom alphabet.

Example: `0123456789abcdef...`

### ignoreCase

<sub>default: `true`</sub>
Expand Down
Loading

0 comments on commit ac7d709

Please sign in to comment.