Add expiresAt, registeredAt, updatedAt, and expiresInDays date helper functions

Author: boutetnico

src/dates.ts

@@ -0,0 +1,43 @@
+import type { Dates } from "./types.js";
+
+/**
+ * Parse the registered date into a Date object, or null if absent or unparseable.
+ */
+export function registeredAt(dates: Dates): Date | null {
+  return parseISO(dates.registered);
+}
+
+/**
+ * Parse the expiry date into a Date object, or null if absent or unparseable.
+ */
+export function expiresAt(dates: Dates): Date | null {
+  return parseISO(dates.expires);
+}
+
+/**
+ * Parse the updated date into a Date object, or null if absent or unparseable.
+ */
+export function updatedAt(dates: Dates): Date | null {
+  return parseISO(dates.updated);
+}
+
+/**
+ * Days until expiration, or null if no expiry date is available.
+ *
+ * Returns a negative number if the domain has already expired.
+ */
+export function expiresInDays(dates: Dates): number | null {
+  const exp = expiresAt(dates);
+  if (exp === null) {
+    return null;
+  }
+  return Math.floor((exp.getTime() - Date.now()) / 86_400_000);
+}
+
+function parseISO(value: string | null): Date | null {
+  if (value === null) {
+    return null;
+  }
+  const d = new Date(value);
+  return isNaN(d.getTime()) ? null : d;
+}

src/index.ts

@@ -32,4 +32,6 @@ export type {
   Remark,
 } from "./types.js";
 
+export { expiresAt, expiresInDays, registeredAt, updatedAt } from "./dates.js";
+
 export { VERSION } from "./version.js";

tests/dates.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { expiresAt, expiresInDays, registeredAt, updatedAt } from "../src/dates.js";
+import type { Dates } from "../src/types.js";
+
+describe("date helpers", () => {
+  const dates: Dates = {
+    registered: "2020-01-01T00:00:00Z",
+    expires: "2028-09-14T04:00:00Z",
+    updated: "2024-02-20T10:16:08Z",
+  };
+
+  it("parses registered date", () => {
+    const d = registeredAt(dates);
+    expect(d).toBeInstanceOf(Date);
+    expect(d!.getUTCFullYear()).toBe(2020);
+  });
+
+  it("parses expires date", () => {
+    const d = expiresAt(dates);
+    expect(d).toBeInstanceOf(Date);
+    expect(d!.getUTCFullYear()).toBe(2028);
+  });
+
+  it("parses updated date", () => {
+    const d = updatedAt(dates);
+    expect(d).toBeInstanceOf(Date);
+    expect(d!.getUTCFullYear()).toBe(2024);
+  });
+
+  it("calculates days until expiry", () => {
+    const days = expiresInDays(dates);
+    expect(days).toBeTypeOf("number");
+    expect(days!).toBeGreaterThan(0);
+  });
+
+  it("returns null for null fields", () => {
+    const nullDates: Dates = { registered: null, expires: null, updated: null };
+    expect(registeredAt(nullDates)).toBeNull();
+    expect(expiresAt(nullDates)).toBeNull();
+    expect(updatedAt(nullDates)).toBeNull();
+    expect(expiresInDays(nullDates)).toBeNull();
+  });
+
+  it("returns null for invalid date strings", () => {
+    const badDates: Dates = { registered: "not-a-date", expires: "garbage", updated: null };
+    expect(registeredAt(badDates)).toBeNull();
+    expect(expiresAt(badDates)).toBeNull();
+    expect(expiresInDays(badDates)).toBeNull();
+  });
+});