@burglekitt/gmt/skills/compare-dates/SKILL.md

Temporal-based date and time utilities with timezone support and polyfill integration

---
name: compare-dates
description: >
  Compare date values for ordering. Use isAfterDate, isBeforeDate, areDatesEqual
  for comparisons. Use areDatesEqualBy/areDateTimesEqualBy/areZonedEqualBy/
  areUnixEqualBy/areUtcEqualBy to compare two values at a given calendar unit
  ("same month?"). Use isWeekend/isZonedWeekend for locale-aware weekend checks
  (weekend days vary by locale). Use isBusinessDay for fixed ISO Mon-Fri checks
  (locale-agnostic, matches addBusinessDays). Use
  getLocaleDayOfWeek/getLocaleZonedDayOfWeek for a locale-relative day-of-week
  index (0 = first day of week). Use isRelativeDay/isThisUnit/isPast/isFuture
  (plus isZoned* variants) for now-relative predicates ("is this today", "is
  this overdue") — depend on system clock/timeZone unless using the zoned
  variants with an explicit timeZone. Use nextWeekday/previousWeekday for the
  next/previous occurrence of an ISO day of week ("next Friday"). Returns
  false/null/"" on invalid input.
sources:
  - 'burglekitt/gmt:packages/gmt/src/plain/compare/index.ts'
  - 'burglekitt/gmt:packages/gmt/src/zoned/compare/index.ts'
  - 'burglekitt/gmt:packages/gmt/src/unix/compare/index.ts'
  - 'burglekitt/gmt:packages/gmt/src/utc/compare/index.ts'
  - 'burglekitt/gmt:packages/gmt/src/plain/calculate/getLocaleDayOfWeek.ts'
  - 'burglekitt/gmt:packages/gmt/src/zoned/calculate/getLocaleZonedDayOfWeek.ts'
  - 'burglekitt/gmt:packages/gmt/src/plain/calculate/nextWeekday.ts'
  - 'burglekitt/gmt:packages/gmt/src/plain/calculate/previousWeekday.ts'
metadata:
  type: core
  library: '@burglekitt/gmt'
  library_version: '1.14.1'
---

# Compare Dates

Use this skill when you need to compare date values for ordering.

## Setup

```ts
import { isAfterDate, isBeforeDate, areDatesEqual } from "@burglekitt/gmt";
import { isBetweenDate } from "@burglekitt/gmt";
```

## Core Patterns

### Check if date is after another

```ts
const result = isAfterDate("2024-03-20", "2024-03-15"); // true
```

### Check if date is before another

```ts
const result = isBeforeDate("2024-03-10", "2024-03-15"); // true
```

### Check if dates are equal

```ts
import { areDatesEqual } from "@burglekitt/gmt";

const result = areDatesEqual("2024-03-15", "2024-03-15"); // true
```

### Check if two values are equal at a given unit (same month, same year, ...)

```ts
import { areDatesEqualBy } from "@burglekitt/gmt";

areDatesEqualBy("2024-03-15", "2024-03-20", "month"); // true
areDatesEqualBy("2023-03-15", "2024-03-15", "month"); // false — same month, different year
areDatesEqualBy("2024-03-11", "2024-03-17", "week"); // true (default weekStartsOn: "monday")
```

`areDatesEqualBy`/`areDateTimesEqualBy`/`areZonedEqualBy`/`areUnixEqualBy`/`areUtcEqualBy` are the namespace variants of this pattern (Decision 5 — one parameterized function per namespace instead of a `isSameDay`/`isSameMonth`/`isSameYear`/... family). Equality is measured by comparing the *start of that unit* for each value, so a coarser unit like `"month"` implicitly requires every unit above it (year) to match too — see the Common Mistakes entry below. `areZonedEqualBy` compares each value's own local calendar fields (its own time zone), not the underlying instant.

Migrating from date-fns:

| date-fns                     | GMT                                  |
| ----------------------------- | ------------------------------------- |
| `isSameDay(a, b)`             | `areDatesEqualBy(a, b, "day")`        |
| `isSameWeek(a, b, opts)`      | `areDatesEqualBy(a, b, "week", opts)` |
| `isSameMonth(a, b)`           | `areDatesEqualBy(a, b, "month")`      |
| `isSameYear(a, b)`            | `areDatesEqualBy(a, b, "year")`       |
| `isSameHour(a, b)`            | `areDateTimesEqualBy(a, b, "hour")`   |
| `isSameMinute(a, b)`          | `areDateTimesEqualBy(a, b, "minute")` |
| `isSameSecond(a, b)`          | `areDateTimesEqualBy(a, b, "second")` |

### Check if date is between two dates

```ts
import { isBetweenDate } from "@burglekitt/gmt";

const result = isBetweenDate("2024-03-15", "2024-03-10", "2024-03-20"); // true
```

### Compare datetime values

```ts
import { isAfterDateTime, isBeforeDateTime, areDateTimesEqual } from "@burglekitt/gmt";

const after = isAfterDateTime("2024-03-15T14:30:45", "2024-03-15T14:30:00"); // true
const before = isBeforeDateTime("2024-03-15T14:30:00", "2024-03-15T14:30:45"); // true
const equal = areDateTimesEqual("2024-03-15T14:30:45", "2024-03-15T14:30:45"); // true
```

### Compare time values

```ts
import { isAfterTime, isBeforeTime, areTimesEqual } from "@burglekitt/gmt";

const after = isAfterTime("14:30:45", "14:30:00"); // true
const before = isBeforeTime("14:30:00", "14:30:45"); // true
const equal = areTimesEqual("14:30:45", "14:30:45"); // true
```

### Check if a date falls on a weekend (locale-aware)

```ts
import { isWeekend, isZonedWeekend } from "@burglekitt/gmt";

isWeekend("2024-02-03", "en-US"); // true (Saturday, en-US weekend is Sat/Sun)
isWeekend("2024-02-02", "he-IL"); // true (Friday, he-IL weekend is Fri/Sat)

isZonedWeekend("2024-02-04T10:00:00+02:00[Asia/Jerusalem]", "he-IL"); // false (Sunday isn't part of he-IL's weekend)
```

`isZonedWeekend` checks the `ZonedDateTime`'s own local calendar day — no separate timezone conversion needed.

### Check if a date is a business day (fixed Mon–Fri)

```ts
import { isBusinessDay } from "@burglekitt/gmt";

isBusinessDay("2024-02-05"); // true (Monday)
isBusinessDay("2024-02-10"); // false (Saturday)
isBusinessDay("2024-02-04"); // false (Sunday)
```

`isBusinessDay` uses the fixed ISO Monday–Friday boundary (Mon=1 … Fri=5) — locale-agnostic and with no holiday calendar. It matches the boundary that `addBusinessDays`/`subtractBusinessDays` use, and is the locale-agnostic complement to `isWeekend` (which resolves weekend days per locale via `Intl.Locale`'s `weekInfo`).

### Get the locale-relative day-of-week index

```ts
import { getLocaleDayOfWeek, getLocaleZonedDayOfWeek } from "@burglekitt/gmt";

getLocaleDayOfWeek("2024-02-25", "en-US");       // 0 (Sunday = first day of en-US week)
getLocaleDayOfWeek("2024-02-26", "en-US");       // 1 (Monday)
getLocaleDayOfWeek("2024-02-26", "fr-FR");       // 0 (Monday = first day of fr-FR week)
getLocaleDayOfWeek("2024-02-24", "he-IL");       // 0 (Saturday = first day of he-IL week)

getLocaleZonedDayOfWeek("2024-02-25T12:00:00+00:00[UTC]", "en-US"); // 0
getLocaleZonedDayOfWeek("2024-02-26T12:00:00+00:00[UTC]", "fr-FR"); // 0
```

`getLocaleDayOfWeek` returns `null` on invalid input. `getLocaleZonedDayOfWeek` reads the `ZonedDateTime`'s local calendar day — no separate timezone conversion needed.

### Check now-relative predicates (today, this month, past, future)

```ts
import { isRelativeDay, isThisUnit, isPast, isFuture } from "@burglekitt/gmt";

isRelativeDay("2024-03-15", 0);   // "is today" — true if today is 2024-03-15
isRelativeDay("2024-03-14", -1);  // "is yesterday" — true if today is 2024-03-15
isRelativeDay("2024-03-16", 1);   // "is tomorrow" — true if today is 2024-03-15

isThisUnit("2024-03-15", "month");            // true if today is any day in March 2024
isThisUnit("2024-02-26", "week", "fr-FR");    // locale-aware week boundary (fr-FR starts Monday)

isPast("2024-03-14");   // true if today is 2024-03-15 (strictly before, not on-or-before)
isFuture("2024-03-16"); // true if today is 2024-03-15 (strictly after, not on-or-before)
```

`isRelativeDay` subsumes `isToday`/`isYesterday`/`isTomorrow` (`offsetDays: 0`/`-1`/`1`); `isThisUnit` subsumes `isThisWeek`/`isThisMonth`/`isThisYear` (Decision 5, `context/roadmap/issues/J.md`). All four compare against `getToday()`, so they depend on the **system clock and system timeZone** — see the Common Mistakes entry below before using these in a server or test context.

Zoned counterparts — `isZonedRelativeDay`, `isZonedThisUnit`, `isZonedPast`, `isZonedFuture` — take a `ZonedDateTime` string and resolve "today"/"now" in *that value's own* timeZone, making them deterministic regardless of the host's system timeZone:

```ts
import { isZonedRelativeDay, isZonedThisUnit, isZonedPast, isZonedFuture } from "@burglekitt/gmt";

isZonedRelativeDay("2024-03-15T10:00:00-04:00[America/New_York]", 0); // "today" in America/New_York, not the host's timeZone
isZonedThisUnit("2024-03-15T10:00:00-04:00[America/New_York]", "month");

// isZonedPast/isZonedFuture compare the exact instant (not just the calendar
// day) against Temporal.Now.instant() — the zoned counterpart carries a
// full time-of-day, unlike the plain, day-only isPast/isFuture.
isZonedPast("2020-01-01T00:00:00Z[UTC]");   // true
isZonedFuture("2999-01-01T00:00:00Z[UTC]"); // true
```

### Find the next/previous occurrence of a weekday

```ts
import { nextWeekday, previousWeekday } from "@burglekitt/gmt";

nextWeekday("2024-03-13", 5); // "2024-03-15" (Wednesday -> next Friday)
nextWeekday("2024-03-15", 5); // "2024-03-22" (already Friday -> advances a full week by default)
nextWeekday("2024-03-15", 5, { inclusive: true }); // "2024-03-15" (already Friday -> returned as-is)

previousWeekday("2024-03-13", 5); // "2024-03-08" (Wednesday -> previous Friday)
previousWeekday("2024-03-15", 5); // "2024-03-08" (already Friday -> goes back a full week by default)
```

`dayOfWeek` uses Temporal's ISO numbering (1 = Monday … 7 = Sunday), the same as `getDayOfWeek`/`parseDayOfWeekFromDate`. These replace date-fns's sixteen `next*`/`previous*` functions with two parameterized calls (Decision 5, `context/roadmap/issues/J.md`):

| date-fns          | GMT                          |
| ------------------ | ------------------------------ |
| `nextMonday(v)`    | `nextWeekday(v, 1)`           |
| `nextFriday(v)`    | `nextWeekday(v, 5)`           |
| `nextDay(v, n)`    | `nextWeekday(v, n)`           |
| `previousFriday(v)`| `previousWeekday(v, 5)`       |
| `previousDay(v, n)`| `previousWeekday(v, n)`       |

`date-fns`'s `lastDayOfMonth` is already covered by `endOfDate(value, "month")` — not a gap this pair fills.

## Common Mistakes

### HIGH Using string comparison for dates

Wrong:

```ts
const isAfter = "2024-03-20" > "2024-03-15"; // true but fragile
```

Correct:

```ts
import { isAfterDate } from "@burglekitt/gmt";

const isAfter = isAfterDate("2024-03-20", "2024-03-15"); // true
```

Source: AGENTS.md — Use Temporal for proper comparison

### MEDIUM Not handling invalid input

Wrong:

```ts
const result = isAfterDate("invalid", "2024-03-15");
// Assume result is always boolean
if (result) { // false, not throwing
  process();
}
```

Correct:

```ts
import { isAfterDate, isValidDate } from "@burglekitt/gmt";

const dateA = "invalid";
const dateB = "2024-03-15";
if (!isValidDate(dateA) || !isValidDate(dateB)) {
  throw new Error("Invalid date");
}
const result = isAfterDate(dateA, dateB);
```

Source: packages/gmt/src/plain/compare/isAfterDate.ts — Returns false on invalid

### MEDIUM Comparing different date formats

Wrong:

```ts
const result = isAfterDate("2024-3-5", "2024-03-15"); // may be incorrect
```

Correct:

```ts
// Ensure canonical format before comparison
import { isAfterDate } from "@burglekitt/gmt";

const result = isAfterDate("2024-03-05", "2024-03-15");
```

Source: Temporal.PlainDate.from() — canonicalizes input

### MEDIUM Assuming weekends are always Saturday/Sunday

Wrong:

```ts
import { getDayOfWeek } from "@burglekitt/gmt";

const day = getDayOfWeek(); // ISO day of week, always Monday-start
const isWeekendDay = day === 6 || day === 7; // wrong for he-IL/ar-SA (Fri/Sat)
```

Correct:

```ts
import { isWeekend } from "@burglekitt/gmt";

const isWeekendDay = isWeekend("2024-02-02", "he-IL"); // true — Friday is part of he-IL's weekend
```

Most locales use Saturday/Sunday, but `he-IL`/`ar-SA` use Friday/Saturday — `isWeekend`/`isZonedWeekend` resolve this per-locale via `Intl.Locale`'s `weekInfo` instead of hardcoding a day pair.

Source: packages/gmt/src/plain/compare/isWeekend.ts — locale-aware via Intl.Locale weekInfo

### MEDIUM Confusing isBusinessDay with isWeekend

Wrong:

```ts
const isWeekendDay = isBusinessDay("2024-02-02"); // false (it's a Friday)
// then assume isBusinessDay captures locale-specific weekend days
```

Correct:

```ts
import { isWeekend } from "@burglekitt/gmt";

// isBusinessDay is fixed ISO Mon–Fri (no locale lookup, no holidays)
isBusinessDay("2024-02-02"); // true (Friday)

// For locale-aware weekend detection (e.g. he-IL Fri/Sat), use isWeekend
isWeekend("2024-02-02", "he-IL"); // true (Friday is part of he-IL's weekend)
```

`isBusinessDay` uses a fixed Monday–Friday boundary and never consults `Intl.Locale`'s `weekInfo`; it does not account for holidays. Do not reach for it when you need locale-aware weekend detection — that's `isWeekend`/`isZonedWeekend`'s job.

Source: packages/gmt/src/plain/compare/isBusinessDay.ts — fixed ISO Mon–Fri, locale-agnostic

### MEDIUM Assuming "same month" ignores the year

Wrong:

```ts
import { areDatesEqualBy } from "@burglekitt/gmt";

// Assuming this checks "is it March, regardless of year"
const bothMarch = areDatesEqualBy("2023-03-15", "2024-03-15", "month"); // false, not true
```

Correct:

```ts
import { areDatesEqualBy } from "@burglekitt/gmt";

// "Same month" means the same month AND year — matches date-fns's isSameMonth
// and Luxon's dt.hasSame(other, "month")
areDatesEqualBy("2024-03-01", "2024-03-31", "month"); // true (same month, same year)

// To check "same month-of-year regardless of year", compare the month field directly
import { parseMonthFromDate } from "@burglekitt/gmt";
const sameMonthOfYear =
  parseMonthFromDate("2023-03-15") === parseMonthFromDate("2024-03-15"); // true
```

`areDatesEqualBy(a, b, unit)` compares the start-of-`unit` boundary for each value, so any unit implicitly requires every coarser unit above it to match too — this is deliberate (Decision 5/6, `context/roadmap/issues/J.md`) and matches date-fns/Luxon precedent, not a GMT-specific quirk.

Source: packages/gmt/src/plain/compare/areDatesEqualBy.ts — start-of-unit comparison

### HIGH Assuming isRelativeDay/isThisUnit/isPast/isFuture are timeZone-independent

Wrong:

```ts
import { isRelativeDay } from "@burglekitt/gmt";

// Assuming "today" means the same thing everywhere
const isDueToday = isRelativeDay(dueDate, 0);
```

Correct:

```ts
import { isZonedRelativeDay } from "@burglekitt/gmt";

// "Today" is resolved in the value's own timeZone — deterministic
// regardless of the host machine's system timeZone
const isDueToday = isZonedRelativeDay(dueZonedDateTime, 0);
```

`isRelativeDay`/`isThisUnit`/`isPast`/`isFuture` depend on the **system clock and system timeZone** (they compare against `getToday()`). The same call returns different answers on hosts in different timeZones at the same instant — `isRelativeDay("2024-03-15", 0)` can be true in one timeZone and false in another 24 hours apart (e.g. `Pacific/Apia` vs. `Pacific/Niue`). Callers needing determinism — server-side rendering, tests, scheduled jobs — should use the zoned variants (`isZonedRelativeDay`, `isZonedThisUnit`, `isZonedPast`, `isZonedFuture`) with an explicit timeZone, or compare against an explicit reference with `areDatesEqualBy`/`isBeforeDate`/`isAfterDate`.

Source: packages/gmt/src/plain/compare/isRelativeDay.ts, packages/gmt/src/plain/get/getToday.ts — system clock/timeZone dependency

### MEDIUM Assuming nextWeekday/previousWeekday return the input when it's already on the target day

Wrong:

```ts
import { nextWeekday } from "@burglekitt/gmt";

// Assuming a Friday input returns itself when asking for "next Friday"
const result = nextWeekday("2024-03-15", 5); // "2024-03-22", not "2024-03-15"
```

Correct:

```ts
import { nextWeekday } from "@burglekitt/gmt";

// Pass { inclusive: true } to return the input as-is when it already falls on dayOfWeek
const result = nextWeekday("2024-03-15", 5, { inclusive: true }); // "2024-03-15"
```

`options.inclusive` defaults to `false`, matching date-fns: a `value` already on `dayOfWeek` advances a full week rather than returning itself. Same default applies to `previousWeekday`.

Source: packages/gmt/src/plain/calculate/nextWeekday.ts, packages/gmt/src/plain/calculate/previousWeekday.ts — inclusive defaults to false

## References

- [Full compare API](references/compare-api.md)
- [Temporal.PlainDate comparison](https://tc39.es/proposal-temporal/docs/plaindate.html#comparison)