alphaNumericSort

function alphaNumericSort<T>(
  list: readonly T[],
  options: AlphaNumericSortOptions<T> = {}
): readonly T[];

The alphaNumericSort function can be used to performantly sort a list alphanumerically using Intl.Collator.localeCompare.

Example Usage

import { alphaNumericSort } from "@react-md/core/utils/alphaNumericSort";

const items = ["World", "Hello"];
const sorted = alphaNumericSort(items);
// sorted == ["Hello", "World"]

Non-string lists

If the provided list is not a list of strings or a known object type, an extractor option must also be provided to get the search text for each item.

interface Item {
  nameField: string;
}

const items: Item[] = [{ nameField: "World" }, { nameField: "Hello" }];

const sorted = alphaNumericSort(items, {
  extractor: (item) => item.nameField,
});
// sorted == [{ nameField: "Hello" }, { nameField: "World" }]

Descending order

Just enable the descending option to return a descending sorted list instead of ascending.

const list = ["a", "f", "d"];
const sorted = alphaNumericSort(list, { descending: true });
// sorted == ["f", "d", "a"];

Different Locales

The default compare function uses "en-US" and cannot be configured. Instead, provide a custom compare function:

const list = ["Z", "a", "z", "ä"];
const compareDE = new Intl.Collator("de", DEFAULT_COLLATOR_OPTIONS).compare;
const compareSV = new Intl.Collator("sv", DEFAULT_COLLATOR_OPTIONS).compare;

const sortedUS = alphaNumericSort(list);
// sortedUS == ["a", "ä", "Z", "z"]
const sortedDE = alphaNumericSort(list, { compare: compareDE });
// sortedDE == ["a", "ä", "Z", "z"]
const sortedSV = alphaNumericSort(list, { compare: compareSV });
// sortedSV == [ "a", "Z", "z", "ä"]

Parameters

options - an object with the following definition:

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,
   * });
   * ```
   *
   * 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;
}

Returns

A new list sorted alphanumerically.