The type of objects being compared
Function that extracts string value(s) from input objects
A comparator function suitable for Array.sort()
interface User {
id: string;
firstName: string;
lastName: string;
email: string;
status: "active" | "inactive";
}
const users: User[] = [
{
id: "1",
firstName: "John",
lastName: "Doe",
email: "john@example.com",
status: "active",
},
{
id: "2",
firstName: "Jane",
lastName: "Doe",
email: "jane@example.com",
status: "inactive",
},
{
id: "3",
firstName: "Bob",
lastName: "Smith",
email: "bob@example.com",
status: "active",
},
];
// Single field sorting
users.sort(GaffComparator.strings((user) => user.lastName));
// Result: Doe, Doe, Smith
// Multi-field sorting: last name, then first name
users.sort(
GaffComparator.strings((user) => [user.lastName, user.firstName]),
);
// Result: Doe Jane, Doe John, Smith Bob
// Status-based sorting
users.sort(GaffComparator.strings((user) => user.status));
// Result: active users first, then inactive
// Complex multi-field: status, then last name, then first name
users.sort(
GaffComparator.strings((user) => [
user.status,
user.lastName,
user.firstName,
]),
);
// Integration with TestValidator sorting validation
const sortValidator = TestValidator.sort(
"user name sorting",
(sortFields) => userApi.getUsers({ sort: sortFields }),
)(
"lastName",
"firstName",
)(GaffComparator.strings((user) => [user.lastName, user.firstName]));
await sortValidator("+"); // test ascending order
await sortValidator("-"); // test descending order
contracts/common.md#principled-implementation Each common key position is compared once with localeCompare; a nonzero result decides the order, while collation-equal spellings continue to later keys. Only an entirely equal common prefix falls through to array length, establishing lexicographic order under the runtime's actual collation without assuming strict string equality.
contracts/common.md#clear-and-simple-design Shared wrapping accepts scalar or array keys; one bounded loop returns the first nonzero collation result or the length difference.
Creates a comparator function for string-based sorting with locale-aware comparison.
Generates a comparator that extracts string values from objects and performs lexicographic comparison using locale-sensitive string comparison. Supports both single strings and arrays of strings for multi-field sorting scenarios.
When comparing arrays, performs lexicographic ordering: compares the first elements, then the second elements if the first are equal, and so on. This enables complex sorting like "sort by last name, then by first name". Keys that compare equal under the runtime's collation, including different canonically equivalent Unicode spellings, continue to the next key. If the whole common prefix compares equal, the shorter key list sorts first.
Processing cost: Both getters run once and a bounded loop visits only common keys until the first collation difference. Work depends on examined keys and string comparison cost; scalar wrapping adds constant space.