# All files / utils alphaNumericSort.ts

100% Statements 137/137
50% Branches 2/4
100% Functions 1/1
100% Lines 137/137

Press n or j to go to the next uncovered block, b, p or k for the previous block.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    1381x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    1x
    4x
    4x
    4x
    4x
    4x
    4x
    4x
    4x
    4x
    4x
    4x
    11x
    11x
    11x
    11x
    11x
    11x
    11x
    11x
    4x
    4x
    4x
     import { defaultExtractor } from "../searching/utils.js";
    import { type TextExtractor } from "../types.js";

    /**
     * The default `Intl.Collator` that should be used for sorting large lists.
     *
     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare#performance
     * @remarks \@since 6.0.0
     */
    export const DEFAULT_COLLATOR = new Intl.Collator("en-US", {
      numeric: true,
      caseFirst: "upper",
    });

    /** @remarks \@since 6.0.0 */
    export interface AlphaNumericSortOptions<T> {
      /**
       * The extractor is only required when the list of items are not strings.
       *
       * @example
       * Simple Example
       * ```ts
       * interface Item {
       *   name: string;
       * }
       *
       * const items: Item[] = [{ name: 'Hello' }, { name: 'World' }];
       *
       * `alphaNumericSort(items, {
       *   extractor: item => item.name,
       * })`
       * ```
       *
       * @remarks
       * For javascript developers, this will throw an error in dev mode if an
       * extractor is not provided for non-string lists.
       *
       * @defaultValue `typeof item === "string" ? item : ""`
       */
      extractor?: TextExtractor<T>;

      /**
       * A custom compare function for sorting the list. This should really only be
       * provided if the language for your app is not `"en-US"` or you'd like to
       * provide some custom sorting options.
       *
       * @example
       * Custom Compare using Intl.Collator
       * ```ts
       * const collator = new Intl.Collator("en-US", {
       *   numeric: false,
       *   caseFirst: "lower",
       *   usage: "search",
       * });
       *
       * alphaNumericSort(items, {
       *   compare: collator.compare,
       * })
       * ```
       *
       * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator
       * @defaultValue `new Intl.Collator("en-US", { numeric: true, caseFirst: "upper" }).compare`
       */
      compare?(a: string, b: string): number;

      /**
       * Setting this to `true` will return the list in descending order instead of
       * ascending.
       *
       * @defaultValue `false`
       */
      descending?: boolean;
    }

    /**
     * @example
     * Simple Example
     * ```ts
     * const items = ["World", "Hello"];
     *
     * const sorted = alphaNumericSort(items);
     * // sorted == ["Hello", "World"]
     * ```
     *
     * @param list - The list of strings to sort
     * @returns a new sorted list
     */
    export function alphaNumericSort<T extends string>(
      list: readonly T[],
      options?: Omit<AlphaNumericSortOptions<T>, "extractor">
    ): readonly T[];
    /**
     * @example
     * Simple Example
     * ```ts
     * interface Item {
     *   name: string;
     * }
     *
     * const items: Item[] = [{ name: "World" }, { name: "Hello" }];
     *
     * const sorted = alphaNumericSort(items, {
     *   extractor: item => item.name,
     * });
     * // sorted == [{ name: "Hello" }, { name: "World" }]
     * ```
     *
     * @param list - The list of items to sort
     * @returns a new sorted list
     */
    export function alphaNumericSort<T>(
      list: readonly T[],
      options: AlphaNumericSortOptions<T> & { extractor: TextExtractor<T> }
    ): readonly T[];
    export function alphaNumericSort<T>(
      list: readonly T[],
      options: AlphaNumericSortOptions<T> = {}
    ): readonly T[] {
      const {
        compare = DEFAULT_COLLATOR.compare,
        extractor = defaultExtractor("alphaNumericSort"),
        descending = false,
      } = options;

      const sorted = list.slice();
      sorted.sort((a, b) => {
        const aValue = extractor(a);
        const bValue = extractor(b);

        const value1 = descending ? bValue : aValue;
        const value2 = descending ? aValue : bValue;

        return compare(value1, value2);
      });

      return sorted;
    }