@northguild/gmt 1.14.2 → 1.16.0

package/skills/compare-dates/SKILL.md

@@ -1,412 +0,0 @@
----
-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:
-  - 'northguild/gmt:packages/gmt/src/plain/compare/index.ts'
-  - 'northguild/gmt:packages/gmt/src/zoned/compare/index.ts'
-  - 'northguild/gmt:packages/gmt/src/unix/compare/index.ts'
-  - 'northguild/gmt:packages/gmt/src/utc/compare/index.ts'
-  - 'northguild/gmt:packages/gmt/src/plain/calculate/getLocaleDayOfWeek.ts'
-  - 'northguild/gmt:packages/gmt/src/zoned/calculate/getLocaleZonedDayOfWeek.ts'
-  - 'northguild/gmt:packages/gmt/src/plain/calculate/nextWeekday.ts'
-  - 'northguild/gmt:packages/gmt/src/plain/calculate/previousWeekday.ts'
-metadata:
-  type: core
-  library: '@northguild/gmt'
-  library_version: '1.14.2'
----
-
-# Compare Dates
-
-Use this skill when you need to compare date values for ordering.
-
-## Setup
-
-```ts
-import { isAfterDate, isBeforeDate, areDatesEqual } from "@northguild/gmt";
-import { isBetweenDate } from "@northguild/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 "@northguild/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 "@northguild/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 "@northguild/gmt";
-
-const result = isBetweenDate("2024-03-15", "2024-03-10", "2024-03-20"); // true
-```
-
-### Compare datetime values
-
-```ts
-import { isAfterDateTime, isBeforeDateTime, areDateTimesEqual } from "@northguild/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 "@northguild/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 "@northguild/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 "@northguild/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 "@northguild/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 "@northguild/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 "@northguild/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 "@northguild/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 "@northguild/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 "@northguild/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 "@northguild/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 "@northguild/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 "@northguild/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 "@northguild/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 "@northguild/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 "@northguild/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 "@northguild/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 "@northguild/gmt";
-
-// Assuming "today" means the same thing everywhere
-const isDueToday = isRelativeDay(dueDate, 0);
-```
-
-Correct:
-
-```ts
-import { isZonedRelativeDay } from "@northguild/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 "@northguild/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 "@northguild/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)