Alphabet Utility

/**
 * Utility class for building and manipulating custom alphabets for sorting
 */
class Alphabet {
  /**
   * Generates an alphabet from the given characters
   * @param values - The characters to generate the alphabet from
   * @returns The wrapped alphabet instance
   * @throws Error if alphabet contains repeated characters or non-single characters
   */
  static generateFrom(values: string[] | string): Alphabet;

  /**
   * Generates an alphabet containing relevant characters from Unicode planes 0 and 1
   * @returns The generated alphabet (recommended for most use cases)
   */
  static generateRecommendedAlphabet(): Alphabet;

  /**
   * Generates an alphabet containing all characters from Unicode planes 0, 1, 2 and 3
   * @returns The generated alphabet (complete Unicode coverage)
   */
  static generateCompleteAlphabet(): Alphabet;
}

/**
 * Static methods for alphabet generation
 */
interface AlphabetStatic {
  /**
   * Creates alphabet from custom character set
   * @param values - String or array of single characters
   * @returns New Alphabet instance
   * @example
   * Alphabet.generateFrom('abcdef')
   * Alphabet.generateFrom(['a', 'b', 'c'])
   */
  generateFrom(values: string[] | string): Alphabet;

  /**
   * Generates Unicode alphabet for common use cases (planes 0-1)
   * Includes most commonly used characters across languages
   * @returns Alphabet with recommended Unicode range
   */
  generateRecommendedAlphabet(): Alphabet;

  /**
   * Generates comprehensive Unicode alphabet (planes 0-3)
   * Includes extensive Unicode character coverage
   * @returns Alphabet with complete Unicode range
   */
  generateCompleteAlphabet(): Alphabet;
}

/**
 * Instance methods for alphabet manipulation
 */
interface AlphabetInstance {
  /**
   * Prioritizes case order within the alphabet
   * @param casePriority - Which case to prioritize
   * @returns Same alphabet instance (chainable)
   * @example
   * alphabet.prioritizeCase('uppercase') // 'AaBbCc' → 'ABCabc'
   */
  prioritizeCase(casePriority: "lowercase" | "uppercase"): this;

  /**
   * Adds characters to the end of the alphabet
   * @param values - Characters to add
   * @returns Same alphabet instance (chainable)
   * @throws Error if characters already exist in alphabet
   */
  pushCharacters(values: string[] | string): this;

  /**
   * Removes specific characters from the alphabet
   * @param values - Characters to remove
   * @returns Same alphabet instance (chainable)
   */
  removeCharacters(values: string[] | string): this;

  /**
   * Removes Unicode characters within specified range
   * @param range - Unicode codepoint range to remove
   * @returns Same alphabet instance (chainable)
   */
  removeUnicodeRange(range: { start: number; end: number }): this;

  /**
   * Sorts alphabet using custom comparison function
   * @param sortingFunction - Function to compare two characters
   * @returns Same alphabet instance (chainable)
   */
  sortBy(sortingFunction: (a: string, b: string) => number): this;

  /**
   * Sorts alphabet using natural order (human-friendly)
   * @param locale - Optional locale for sorting
   * @returns Same alphabet instance (chainable)
   */
  sortByNaturalSort(locale?: string): this;

  /**
   * Sorts alphabet by character code points
   * @returns Same alphabet instance (chainable)
   */
  sortByCharCodeAt(): this;

  /**
   * Sorts alphabet using locale-specific comparison
   * @param locales - Locales for comparison
   * @returns Same alphabet instance (chainable)
   */
  sortByLocaleCompare(locales?: Intl.LocalesArgument): this;

  /**
   * Reverses the current alphabet order
   * @returns Same alphabet instance (chainable)
   */
  reverse(): this;

  /**
   * Returns the alphabet as a string
   * @returns String representation of the alphabet
   */
  getCharacters(): string;
}

/**
 * Advanced character positioning methods
 */
interface AlphabetPositioning {
  /**
   * Places all characters with specified case before characters with other case
   * @param caseToComeFirst - Case to prioritize
   * @returns Same alphabet instance (chainable)
   * @example
   * alphabet.placeAllWithCaseBeforeAllWithOtherCase('uppercase')
   * // Results in all uppercase letters before lowercase letters
   */
  placeAllWithCaseBeforeAllWithOtherCase(
    caseToComeFirst: "uppercase" | "lowercase"
  ): this;

  /**
   * Places a character immediately before another character
   * @param params - Character positioning parameters
   * @returns Same alphabet instance (chainable)
   * @example
   * alphabet.placeCharacterBefore({ 
   *   characterBefore: '/', 
   *   characterAfter: '-' 
   * })
   */
  placeCharacterBefore(params: {
    characterBefore: string;
    characterAfter: string;
  }): this;

  /**
   * Places a character immediately after another character
   * @param params - Character positioning parameters
   * @returns Same alphabet instance (chainable)
   * @example
   * alphabet.placeCharacterAfter({ 
   *   characterBefore: '/', 
   *   characterAfter: '-' 
   * })
   */
  placeCharacterAfter(params: {
    characterBefore: string;
    characterAfter: string;
  }): this;
}

import { Alphabet } from "eslint-plugin-perfectionist/alphabet";

// Create from custom characters
const customAlphabet = Alphabet.generateFrom("zyxwvutsrqponmlkjihgfedcba");

// Use recommended Unicode set
const unicodeAlphabet = Alphabet.generateRecommendedAlphabet();

// Get alphabet string
const alphabetString = customAlphabet.getCharacters();

// Create and customize alphabet
const alphabet = Alphabet.generateFrom("abcdefghijklmnopqrstuvwxyz")
  .prioritizeCase("uppercase")
  .pushCharacters("0123456789")
  .removeCharacters("xyz")
  .sortByNaturalSort()
  .reverse();

// Use in custom sorting
const customSort = alphabet.getCharacters();

// Use custom alphabet in ESLint configuration
{
  "perfectionist/sort-objects": ["error", {
    "type": "custom",
    "alphabet": Alphabet.generateRecommendedAlphabet()
      .prioritizeCase("lowercase")
      .getCharacters()
  }]
}

// Advanced Unicode alphabet with custom ordering
const complexAlphabet = Alphabet.generateCompleteAlphabet()
  .removeUnicodeRange({ start: 0x2000, end: 0x206F }) // Remove general punctuation
  .placeAllWithCaseBeforeAllWithOtherCase("lowercase")
  .placeCharacterBefore({ characterBefore: "_", characterAfter: "a" })
  .sortByLocaleCompare("en-US");

const result = complexAlphabet.getCharacters();

/**
 * Internal character representation with Unicode metadata
 */
interface Character {
  uppercaseCharacterCodePoint?: number;
  lowercaseCharacterCodePoint?: number;
  codePoint: number;
  value: string;
}

/**
 * Case priority options for sorting
 */
type CasePriority = "lowercase" | "uppercase";

/**
 * Unicode range specification for removal
 */
interface UnicodeRange {
  start: number;
  end: number;
}

/**
 * Character positioning parameters
 */
interface CharacterPositioning {
  characterBefore: string;
  characterAfter: string;
}

/**
 * Sorting function type for custom sorting
 */
type SortingFunction = (characterA: string, characterB: string) => number;