1 files changed, 139 insertions, 0 deletions
diff --git a/test/timezone.test.ts b/test/timezone.test.ts
new file mode 100644
index 0000000..d4ba6d6
--- /dev/null
+++ b/test/timezone.test.ts
@@ -0,0 +1,139 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildDstOffsetList,
+  buildTimeZoneList,
+  formatUtcOffset,
+  isValidTimeZone,
+  nextOffsetTransition,
+  standardOffsetSeconds,
+  utcOffsetSeconds,
+} from "../src/timezone.js";
+
+// All builder timestamps are Unix-epoch microseconds (matter.js TlvEpochUs
+// convention); "since the beginning of time" is Matter epoch zero in Unix us.
+const MATTER_ZERO = 946_684_800_000_000n;
+const FALL_BACK_2026 = BigInt(Date.parse("2026-11-01T07:00:00Z")) * 1_000n;
+const SPRING_FORWARD_2027 = BigInt(Date.parse("2027-03-14T08:00:00Z")) * 1_000n;
+
+describe("isValidTimeZone", () => {
+  it("accepts IANA names", () => {
+    expect(isValidTimeZone("America/Chicago")).toBe(true);
+    expect(isValidTimeZone("Europe/Berlin")).toBe(true);
+    expect(isValidTimeZone("UTC")).toBe(true);
+  });
+
+  it("rejects invalid names", () => {
+    expect(isValidTimeZone("Central Time")).toBe(false);
+    expect(isValidTimeZone("")).toBe(false);
+    expect(isValidTimeZone("America/Springfield")).toBe(false);
+  });
+});
+
+describe("utcOffsetSeconds", () => {
+  it("returns CST offset in January", () => {
+    expect(utcOffsetSeconds("America/Chicago", new Date("2026-01-15T12:00:00Z"))).toBe(-6 * 3600);
+  });
+
+  it("returns CDT offset in July", () => {
+    expect(utcOffsetSeconds("America/Chicago", new Date("2026-07-15T12:00:00Z"))).toBe(-5 * 3600);
+  });
+
+  it("returns 0 for UTC", () => {
+    expect(utcOffsetSeconds("UTC", new Date("2026-07-15T12:00:00Z"))).toBe(0);
+  });
+
+  it("handles half-hour offsets", () => {
+    expect(utcOffsetSeconds("Asia/Kolkata", new Date("2026-07-15T12:00:00Z"))).toBe(5.5 * 3600);
+  });
+});
+
+describe("formatUtcOffset", () => {
+  it("formats negative, positive, and zero offsets", () => {
+    expect(formatUtcOffset(-6 * 3600)).toBe("UTC-06:00");
+    expect(formatUtcOffset(5.5 * 3600)).toBe("UTC+05:30");
+    expect(formatUtcOffset(0)).toBe("UTC+00:00");
+  });
+});
+
+describe("nextOffsetTransition", () => {
+  it("finds the exact spring-forward instant for Chicago", () => {
+    const transition = nextOffsetTransition("America/Chicago", new Date("2026-01-15T00:00:00Z"));
+    expect(transition).not.toBeNull();
+    // 2026-03-08 02:00 CST (UTC-6) -> 03:00 CDT (UTC-5): 08:00:00 UTC.
+    expect(transition!.at.toISOString()).toBe("2026-03-08T08:00:00.000Z");
+    expect(transition!.offsetBeforeSeconds).toBe(-6 * 3600);
+    expect(transition!.offsetAfterSeconds).toBe(-5 * 3600);
+  });
+
+  it("finds the exact fall-back instant for Chicago", () => {
+    const transition = nextOffsetTransition("America/Chicago", new Date("2026-07-15T00:00:00Z"));
+    expect(transition).not.toBeNull();
+    // 2026-11-01 02:00 CDT (UTC-5) -> 01:00 CST (UTC-6): 07:00:00 UTC.
+    expect(transition!.at.toISOString()).toBe("2026-11-01T07:00:00.000Z");
+    expect(transition!.offsetBeforeSeconds).toBe(-5 * 3600);
+    expect(transition!.offsetAfterSeconds).toBe(-6 * 3600);
+  });
+
+  it("returns null for fixed-offset zones", () => {
+    expect(nextOffsetTransition("UTC", new Date("2026-01-15T00:00:00Z"))).toBeNull();
+  });
+});
+
+describe("standardOffsetSeconds", () => {
+  it("returns the non-DST offset regardless of season", () => {
+    expect(standardOffsetSeconds("America/Chicago", new Date("2026-07-15T00:00:00Z"))).toBe(-6 * 3600);
+    expect(standardOffsetSeconds("America/Chicago", new Date("2026-01-15T00:00:00Z"))).toBe(-6 * 3600);
+  });
+
+  it("handles the southern hemisphere", () => {
+    // Sydney: AEST UTC+10 standard, AEDT UTC+11 in southern summer.
+    expect(standardOffsetSeconds("Australia/Sydney", new Date("2026-01-15T00:00:00Z"))).toBe(10 * 3600);
+  });
+
+  it("handles fixed-offset zones", () => {
+    expect(standardOffsetSeconds("UTC", new Date("2026-07-15T00:00:00Z"))).toBe(0);
+    expect(standardOffsetSeconds("Asia/Kolkata", new Date("2026-07-15T00:00:00Z"))).toBe(5.5 * 3600);
+  });
+});
+
+describe("buildTimeZoneList", () => {
+  it("builds a single always-valid entry with the standard offset and IANA name", () => {
+    const list = buildTimeZoneList("America/Chicago", new Date("2026-07-26T00:00:00Z"));
+    expect(list).toEqual([{ offset: -6 * 3600, validAt: MATTER_ZERO, name: "America/Chicago" }]);
+  });
+});
+
+describe("buildDstOffsetList", () => {
+  const from = new Date("2026-07-26T00:00:00Z");
+
+  it("builds the active DST period plus the following one (max 2, as on ALPSTUGA)", () => {
+    expect(buildDstOffsetList("America/Chicago", 2, from)).toEqual([
+      { offset: 3600, validStarting: MATTER_ZERO, validUntil: FALL_BACK_2026 },
+      { offset: 0, validStarting: FALL_BACK_2026, validUntil: SPRING_FORWARD_2027 },
+    ]);
+  });
+
+  it("caps the list at the device's maximum", () => {
+    expect(buildDstOffsetList("America/Chicago", 1, from)).toEqual([
+      { offset: 3600, validStarting: MATTER_ZERO, validUntil: FALL_BACK_2026 },
+    ]);
+  });
+
+  it("emits a single open-ended zero entry for zones without DST", () => {
+    expect(buildDstOffsetList("UTC", 2, from)).toEqual([
+      { offset: 0, validStarting: MATTER_ZERO, validUntil: null },
+    ]);
+    expect(buildDstOffsetList("Asia/Kolkata", 5, from)).toEqual([
+      { offset: 0, validStarting: MATTER_ZERO, validUntil: null },
+    ]);
+  });
+
+  it("starts from standard time when DST is not in effect", () => {
+    const winter = new Date("2026-01-15T00:00:00Z");
+    const springForward2026 = BigInt(Date.parse("2026-03-08T08:00:00Z")) * 1_000n;
+    const list = buildDstOffsetList("America/Chicago", 2, winter);
+    expect(list[0]).toEqual({ offset: 0, validStarting: MATTER_ZERO, validUntil: springForward2026 });
+    expect(list[1]!.offset).toBe(3600);
+    expect(list[1]!.validStarting).toBe(springForward2026);
+  });
+});