The type of objects being compared
Function that extracts date string(s) from input objects
A comparator function suitable for Array.sort()
interface Event {
id: string;
title: string;
startDate: string;
endDate: string;
createdAt: string;
updatedAt: string;
}
const events: Event[] = [
{
id: "1",
title: "Conference",
startDate: "2024-03-15T09:00:00Z",
endDate: "2024-03-15T17:00:00Z",
createdAt: "2024-01-10T10:00:00Z",
updatedAt: "2024-02-01T15:30:00Z",
},
{
id: "2",
title: "Workshop",
startDate: "2024-03-10T14:00:00Z",
endDate: "2024-03-10T16:00:00Z",
createdAt: "2024-01-15T11:00:00Z",
updatedAt: "2024-01-20T09:15:00Z",
},
];
// Sort by start date (chronological order)
events.sort(GaffComparator.dates((event) => event.startDate));
// Sort by creation date (oldest first)
events.sort(GaffComparator.dates((event) => event.createdAt));
// Multi-field: start date, then end date
events.sort(
GaffComparator.dates((event) => [event.startDate, event.endDate]),
);
// Sort by modification history: created date, then updated date
events.sort(
GaffComparator.dates((event) => [event.createdAt, event.updatedAt]),
);
// Validate API date sorting with TestValidator
const dateValidator = TestValidator.sort(
"event chronological sorting",
(sortFields) => eventApi.getEvents({ sort: sortFields }),
)("startDate")(GaffComparator.dates((event) => event.startDate));
await dateValidator("+", true); // ascending with trace logging
// Test complex date-based sorting
const sortByEventSchedule = GaffComparator.dates((event) => [
event.startDate,
event.endDate,
]);
contracts/common.md#principled-implementation Each value is parsed by the Date constructor and compared by its millisecond timestamp, so ISO 8601 and the other formats the constructor accepts order correctly; a string the constructor cannot parse yields NaN, and the comparator then returns NaN, which a sort treats as equality, a limit the caller must respect by giving valid dates.
contracts/common.md#clear-and-simple-design It uses the shared wrap and mismatch, and adds only the parsing.
Creates a comparator function for date-based sorting with automatic string parsing.
Generates a comparator that extracts date values from objects, automatically converting string representations to Date objects for numerical comparison. Supports both single dates and arrays of dates for complex temporal sorting.
Date strings are parsed using the standard Date constructor, which supports ISO 8601 format, RFC 2822 format, and other common date representations. The comparison is performed on millisecond timestamps for precise ordering.
Processing cost: Both getters run once, each returned string is parsed once, and the bounded mismatch search visits at most the common key count. Numeric key arrays require space proportional to the two lists.