# recommended-custom

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 desire.

## When to Use

Each rule in `eslint-plugin-perfectionist` offers many 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 at 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.

**Flat Config**

```tsx
// 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
      }
    }
  }
]
```

**Legacy Config**

```tsx
// .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
    }
  }
}
```

## 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.