temporal-hijri/test.mjs

/**
 * ESM test suite for temporal-hijri.
 *
 * Test dates are chosen against verified Umm al-Qura and FCNA calendar data.
 * Reference point: 2023-03-23 = 1 Ramadan 1444 AH (both UAQ and FCNA agree).
 */

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { Temporal } from "@js-temporal/polyfill";
import { UaqCalendar, FcnaCalendar, uaqCalendar, fcnaCalendar } from "./dist/index.mjs";

// Reference date: 2023-03-23 = 1 Ramadan 1444 AH
const isoRamadan = Temporal.PlainDate.from("2023-03-23");
// 2023-04-21 = 1 Shawwal 1444 AH (first day after Ramadan)
const isoShawwal = Temporal.PlainDate.from("2023-04-21");
// 2021-08-09 = 1 Muharram 1443 AH (a 355-day / leap year)
const isoLeapYear = Temporal.PlainDate.from("2021-08-09");

// ── 1. Class exports ──────────────────────────────────────────────────────────

describe("Class exports", () => {
  it("UaqCalendar class export", () => {
    assert(UaqCalendar, "UaqCalendar should be exported");
    const cal = new UaqCalendar();
    assert(cal instanceof UaqCalendar, "UaqCalendar should be instantiable");
  });

  it("FcnaCalendar class export", () => {
    assert(FcnaCalendar, "FcnaCalendar should be exported");
    const cal = new FcnaCalendar();
    assert(cal instanceof FcnaCalendar, "FcnaCalendar should be instantiable");
  });
});

// ── 2. Calendar IDs ───────────────────────────────────────────────────────────

describe("Calendar IDs", () => {
  it("uaqCalendar.id", () => {
    assert.equal(uaqCalendar.id, "hijri-uaq");
  });

  it("fcnaCalendar.id", () => {
    assert.equal(fcnaCalendar.id, "hijri-fcna");
  });
});

// ── 3. Field accessors on 1 Ramadan 1444 (2023-03-23) ────────────────────────

describe("Field accessors (UAQ, 1 Ramadan 1444)", () => {
  it("year = 1444", () => {
    assert.equal(uaqCalendar.year(isoRamadan), 1444);
  });

  it("month = 9 (Ramadan)", () => {
    assert.equal(uaqCalendar.month(isoRamadan), 9);
  });

  it("day = 1", () => {
    assert.equal(uaqCalendar.day(isoRamadan), 1);
  });

  it('monthCode = "M09"', () => {
    assert.equal(uaqCalendar.monthCode(isoRamadan), "M09");
  });

  it("daysInMonth = 29 (Ramadan 1444)", () => {
    assert.equal(uaqCalendar.daysInMonth(isoRamadan), 29);
  });

  it("monthsInYear = 12", () => {
    assert.equal(uaqCalendar.monthsInYear(isoRamadan), 12);
  });

  it("daysInWeek = 7", () => {
    assert.equal(uaqCalendar.daysInWeek(isoRamadan), 7);
  });

  it("dayOfWeek = 4 (Thursday)", () => {
    assert.equal(uaqCalendar.dayOfWeek(isoRamadan), 4);
  });

  it("dayOfYear = 237", () => {
    assert.equal(uaqCalendar.dayOfYear(isoRamadan), 237);
  });
});

// ── 4. dateFromFields ─────────────────────────────────────────────────────────

describe("dateFromFields", () => {
  it("dateFromFields({year:1444, month:9, day:1}) = 2023-03-23", () => {
    const result = uaqCalendar.dateFromFields({ year: 1444, month: 9, day: 1 });
    assert.equal(result.toString(), "2023-03-23");
  });
});

// ── 5. dateAdd ────────────────────────────────────────────────────────────────

describe("dateAdd", () => {
  it("adding 1 month from 1 Ramadan 1444 lands on 1 Shawwal 1444", () => {
    const oneMonth = new Temporal.Duration(0, 1, 0, 0);
    const result = uaqCalendar.dateAdd(isoRamadan, oneMonth);
    assert.equal(result.toString(), isoShawwal.toString());
    assert.equal(uaqCalendar.month(result), 10);
  });

  it("adding 7 days from 1 Ramadan 1444", () => {
    const sevenDays = new Temporal.Duration(0, 0, 0, 7);
    const result = uaqCalendar.dateAdd(isoRamadan, sevenDays);
    assert.equal(uaqCalendar.day(result), 8);
    assert.equal(uaqCalendar.month(result), 9);
  });

  it("adding 1 week from 1 Ramadan 1444", () => {
    const oneWeek = new Temporal.Duration(0, 0, 1, 0);
    const result = uaqCalendar.dateAdd(isoRamadan, oneWeek);
    assert.equal(uaqCalendar.day(result), 8);
    assert.equal(uaqCalendar.month(result), 9);
  });

  it("adding 12 months rolls the year forward", () => {
    const twelveMonths = new Temporal.Duration(0, 12, 0, 0);
    const result = uaqCalendar.dateAdd(isoRamadan, twelveMonths);
    assert.equal(uaqCalendar.year(result), 1445);
    assert.equal(uaqCalendar.month(result), 9);
  });

  it("subtracting months via negative duration", () => {
    const negMonth = new Temporal.Duration(0, -1, 0, 0);
    const result = uaqCalendar.dateAdd(isoShawwal, negMonth);
    assert.equal(uaqCalendar.month(result), 9);
    assert.equal(uaqCalendar.year(result), 1444);
  });
});

// ── 6. dateUntil ──────────────────────────────────────────────────────────────

describe("dateUntil", () => {
  it("days between 1 Ramadan and 1 Shawwal 1444", () => {
    const dur = uaqCalendar.dateUntil(isoRamadan, isoShawwal, { largestUnit: "days" });
    assert.equal(dur.days, 29);
  });

  it("months between 1 Ramadan and 1 Shawwal 1444", () => {
    const dur = uaqCalendar.dateUntil(isoRamadan, isoShawwal, { largestUnit: "months" });
    assert.equal(dur.months, 1);
    assert.equal(dur.days, 0);
  });

  it("years between dates spanning one Hijri year", () => {
    const iso1443 = uaqCalendar.dateFromFields({ year: 1443, month: 1, day: 1 });
    const iso1444 = uaqCalendar.dateFromFields({ year: 1444, month: 1, day: 1 });
    const dur = uaqCalendar.dateUntil(iso1443, iso1444, { largestUnit: "years" });
    assert.equal(dur.years, 1);
    assert.equal(dur.months, 0);
    assert.equal(dur.days, 0);
  });

  it("weeks between dates", () => {
    const dur = uaqCalendar.dateUntil(isoRamadan, isoShawwal, { largestUnit: "weeks" });
    assert.equal(dur.weeks, 4);
    assert.equal(dur.days, 1);
  });
});

// ── 7. inLeapYear ─────────────────────────────────────────────────────────────

describe("inLeapYear", () => {
  it("1443 AH (355 days) is a leap year, 1444 AH (354) is not", () => {
    assert.equal(uaqCalendar.inLeapYear(isoLeapYear), true);
    assert.equal(uaqCalendar.inLeapYear(isoRamadan), false);
  });
});

// ── 8. FCNA calendar ──────────────────────────────────────────────────────────

describe("FCNA calendar", () => {
  it("fcnaCalendar.year(2023-03-23) returns a valid Hijri year", () => {
    const year = fcnaCalendar.year(isoRamadan);
    assert(typeof year === "number" && year > 1400, `Expected a Hijri year > 1400, got ${year}`);
  });
});

// ── 9. Out-of-range error ─────────────────────────────────────────────────────

describe("Out-of-range error", () => {
  it("uaqCalendar.year throws RangeError for out-of-range date (1800-01-01)", () => {
    const outOfRange = Temporal.PlainDate.from("1800-01-01");
    assert.throws(
      () => uaqCalendar.year(outOfRange),
      (err) => err instanceof RangeError,
    );
  });
});

// ── 10. overflow option ───────────────────────────────────────────────────────

describe("overflow option", () => {
  it('dateFromFields with overflow: "constrain" clamps day', () => {
    const result = uaqCalendar.dateFromFields(
      { year: 1444, month: 9, day: 31 },
      { overflow: "constrain" },
    );
    assert.equal(uaqCalendar.day(result), 29);
    assert.equal(uaqCalendar.month(result), 9);
  });

  it('dateFromFields with overflow: "reject" throws RangeError', () => {
    assert.throws(
      () => uaqCalendar.dateFromFields({ year: 1444, month: 9, day: 31 }, { overflow: "reject" }),
      (err) => err instanceof RangeError,
    );
  });

  it('monthDayFromFields with overflow: "constrain" clamps day', () => {
    const result = uaqCalendar.monthDayFromFields({ month: 9, day: 31 }, { overflow: "constrain" });
    assert.ok(result);
  });

  it('monthDayFromFields with overflow: "reject" throws RangeError', () => {
    assert.throws(
      () => uaqCalendar.monthDayFromFields({ month: 9, day: 31 }, { overflow: "reject" }),
      (err) => err instanceof RangeError,
    );
  });
});

// ── 11. fields() ──────────────────────────────────────────────────────────────

describe("fields()", () => {
  it("returns the input array unchanged", () => {
    const input = ["year", "month", "day"];
    const result = uaqCalendar.fields(input);
    assert.deepEqual(result, ["year", "month", "day"]);
  });

  it("returns an empty array for empty input", () => {
    assert.deepEqual(uaqCalendar.fields([]), []);
  });
});

// ── 12. yearMonthFromFields ─────────────────────────────────────────────────

describe("yearMonthFromFields", () => {
  it("creates a PlainYearMonth for Ramadan 1444", () => {
    const result = uaqCalendar.yearMonthFromFields({ year: 1444, month: 9 });
    assert.ok(result);
    assert.equal(result.month, 3);
    assert.equal(result.year, 2023);
  });
});

// ── 13. monthDayFromFields ──────────────────────────────────────────────────

describe("monthDayFromFields", () => {
  it("creates a PlainMonthDay for 15 Ramadan (default reference year)", () => {
    const result = uaqCalendar.monthDayFromFields({ month: 9, day: 15 });
    assert.ok(result);
  });

  it("creates a PlainMonthDay with explicit year", () => {
    const result = uaqCalendar.monthDayFromFields({ month: 9, day: 1, year: 1445 });
    assert.ok(result);
  });
});

// ── 14. UTC-day round-trip regression ─────────────────────────────────────────
// Verifies that ISO→Hijri→ISO is exact regardless of host timezone.
// 2025-03-01 = 1 Ramadan 1446 AH (UAQ).

describe("UTC-day round-trip regression (ISO → Hijri → ISO)", () => {
  const isoRamadan1446 = Temporal.PlainDate.from("2025-03-01");

  it("2025-03-01 maps to 1 Ramadan 1446 AH", () => {
    assert.equal(uaqCalendar.year(isoRamadan1446), 1446);
    assert.equal(uaqCalendar.month(isoRamadan1446), 9);
    assert.equal(uaqCalendar.day(isoRamadan1446), 1);
  });

  it("round-trip: 1446-09-01 → ISO → Hijri returns 1446-09-01", () => {
    const iso = uaqCalendar.dateFromFields({ year: 1446, month: 9, day: 1 });
    assert.equal(iso.toString(), "2025-03-01");
    assert.equal(uaqCalendar.year(iso), 1446);
    assert.equal(uaqCalendar.month(iso), 9);
    assert.equal(uaqCalendar.day(iso), 1);
  });
});