Documentation
    Preparing search index...

    Namespace GaffComparator

    Type-safe comparator functions for Array.sort() operations with advanced field access.

    GaffComparator provides a collection of specialized comparator functions designed to work seamlessly with Array.sort() and testing frameworks like TestValidator.sort(). Each comparator supports both single values and arrays of values, enabling complex multi-field sorting scenarios with lexicographic ordering.

    Key features:

    • Generic type safety for any object structure
    • Support for single values or arrays of values per field
    • Lexicographic comparison for multi-value scenarios
    • Locale-aware string comparison
    • Automatic type conversion for dates and numbers

    The comparators follow the standard JavaScript sort contract:

    • Return < 0 if first element should come before second
    • Return > 0 if first element should come after second
    • Return 0 if elements are equal

    Processing cost: Each comparison extracts both key lists and visits their common prefix until the first difference; date keys additionally parse all supplied strings once per comparison. No sort or repeated scan is performed inside a comparison.

    Jeongho Nam - https://github.com/samchon

    // Basic usage with single fields
      users.sort(GaffComparator.strings((user) => user.name));
      posts.sort(GaffComparator.dates((post) => post.createdAt));
      products.sort(GaffComparator.numbers((product) => product.price));

      // Multi-field sorting with arrays
      users.sort(
        GaffComparator.strings((user) => [user.lastName, user.firstName]),
      );
      events.sort(
        GaffComparator.dates((event) => [event.startDate, event.endDate]),
      );

      // Integration with TestValidator's currying pattern
      const validator = TestValidator.sort("user sorting", (sortable) =>
        api.getUsers({ sort: sortable }),
      )(
        "name",
        "email",
      )(GaffComparator.strings((user) => [user.name, user.email]));
      await validator("+"); // ascending
      await validator("-"); // descending

    contracts/common.md#principled-implementation Each comparator maps both operands to arrays of comparable values and decides by the first position where they differ, then by array length, which is a lexicographic order that satisfies the sort contract for well-defined values; it is used to check server-side sorting from the client.

    contracts/common.md#clear-and-simple-design Three comparators share scalar-to-array wrapping. Strings compare each key by collation; dates and numbers use a shared strict mismatch search over their numeric keys.

    contracts/common.md#prohibited-implementation-shortcuts The ordering rule is generic in the getter, with no field, entity, or locale special case.

    contracts/common.md#meaningful-documentation The namespace prose lists the features and the sort contract with an example.

    dates
    numbers
    strings

    Settings
    Member Visibility

    On This Page
    Functions