chore: Cleanup utils, add JSDoc comments (#661)

Author: kydecker

web/src/lib/utils/__tests__/formatPageTitle.test.ts

@@ -6,7 +6,7 @@ describe("formatPageTitle", () => {
     expect(formatPageTitle("Court Order")).toEqual("Court Order · Namesake");
   });
 
-  it("renders the title with custom divider", () => {
+  it("renders the title with custom delimiter", () => {
     expect(formatPageTitle("Court Order", " - ")).toEqual(
       "Court Order - Namesake",
     );
@@ -18,7 +18,7 @@ describe("formatPageTitle", () => {
     );
   });
 
-  it("hides the divider when site title is not provided", () => {
+  it("hides the delimiter when site title is not provided", () => {
     expect(formatPageTitle("Test Page", " · ", null)).toEqual("Test Page");
   });
 

web/src/lib/utils/createOgImageResponse.ts

@@ -10,6 +10,18 @@ type OgImageOptions = {
   origin: string;
 };
 
+/**
+ * Given a subhead, title, and color, return a rendered PNG Open Graph
+ * image response for social sharing previews.
+ *
+ * @example
+ * await createOgImageResponse({
+ *   subhead: "Massachusetts",
+ *   title: "Plan your name change",
+ *   origin: "https://namesake.fyi",
+ * })
+ * // ImageResponse (PNG, 1200x630)
+ */
 export async function createOgImageResponse({
   subhead,
   title,

web/src/lib/utils/deriveCurrentAge.ts

@@ -1,26 +1,17 @@
 /**
- * Derives current age from a date-of-birth string (YYYY-MM-DD).
+ * Given a date-of-birth string (YYYY-MM-DD), return the current age.
  * Treats the input as a calendar date with no timezone.
+ *
+ * @example
+ * deriveCurrentAge("1990-06-15") // assuming today is 2026-06-24
+ * // 36
  */
 export const deriveCurrentAge = (dateOfBirth?: string): number | undefined => {
-  if (typeof dateOfBirth !== "string" || !dateOfBirth) {
-    return undefined;
-  }
+  if (typeof dateOfBirth !== "string" || !dateOfBirth) return undefined;
 
   const birth = new Date(dateOfBirth);
-  if (Number.isNaN(birth.getTime())) {
-    return undefined;
-  }
+  if (Number.isNaN(birth.getTime())) return undefined;
 
-  const today = new Date();
-  let age = today.getFullYear() - birth.getFullYear();
-
-  const hasBirthdayOccurredThisYear =
-    today.getMonth() > birth.getMonth() ||
-    (today.getMonth() === birth.getMonth() &&
-      today.getDate() >= birth.getDate());
-
-  if (!hasBirthdayOccurredThisYear) age -= 1;
-
-  return age;
+  const elapsed = new Date(Date.now() - birth.getTime());
+  return elapsed.getUTCFullYear() - new Date(0).getUTCFullYear();
 };

web/src/lib/utils/fetchLocationResults.ts

@@ -12,6 +12,14 @@ export interface GeoapifyResult {
   place_id: string;
 }
 
+/**
+ * Given partial address text, return matching location results from the
+ * Geoapify-backed location API.
+ *
+ * @example
+ * await fetchLocations("123 Main St, Boston")
+ * // [{ formatted: "123 Main St, Boston, MA 02108, United States", ... }]
+ */
 export async function fetchLocations(
   text: string,
   signal?: AbortSignal,
@@ -36,6 +44,14 @@ async function sleep(durationMs: number, signal?: AbortSignal) {
   });
 }
 
+/**
+ * Given a debounce delay, return an async list loader for `<ComboBox>`-style
+ * location fields, debouncing requests and giving up on the API after one failure.
+ *
+ * @example
+ * createLocationLoader(200)
+ * // ({ signal, filterText }) => Promise<{ items: GeoapifyResult[] }>
+ */
 export function createLocationLoader(
   debounceMs = 200,
 ): AsyncListLoadFunction<GeoapifyResult, string> {

web/src/lib/utils/fetchPovertyGuideline.ts

@@ -9,9 +9,13 @@ export interface PovertyGuideline {
 }
 
 /**
- * Fetches the federal poverty guideline for a given year, state, and
- * household size from the HHS ASPE API. Household size is clamped to 1–8
- * per API constraints. Returns null on any failure.
+ * Given a year, state, and household size, return the federal poverty
+ * guideline from the HHS ASPE API, or null on failure. Household size is
+ * clamped to 1–8 per API constraints.
+ *
+ * @example
+ * await fetchPovertyGuideline(2025, 3, "ma")
+ * // { year: 2025, state: "ma", householdSize: 3, povertyThreshold: ... }
  */
 export async function fetchPovertyGuideline(
   year: number,

web/src/lib/utils/fetchYouTubeVideoDetails.ts

@@ -4,6 +4,14 @@ export interface YouTubeOEmbedResponse {
   thumbnail_url: string;
 }
 
+/**
+ * Given a YouTube video URL, return its title, author, and thumbnail via
+ * the oEmbed API, or null if the request fails.
+ *
+ * @example
+ * await fetchYouTubeVideoDetails("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+ * // { title: "...", author_name: "...", thumbnail_url: "..." }
+ */
 export async function fetchYouTubeVideoDetails(
   url: string,
 ): Promise<YouTubeOEmbedResponse | null> {

web/src/lib/utils/formatAddress.ts

@@ -5,6 +5,13 @@ type Address = {
   zip?: string;
 };
 
+/**
+ * Given the parts of a mailing address, return the present ones joined together.
+ *
+ * @example
+ * formatAddress({ street: "123 Main St", city: "Boston", state: "MA", zip: "02108" })
+ * // "123 Main St, Boston, MA, 02108"
+ */
 export const formatAddress = ({ street, city, state, zip }: Address) => {
   return [street, city, state, zip].filter(Boolean).join(", ");
 };

web/src/lib/utils/formatBirthplaceCountryOrState.ts

@@ -1,6 +1,16 @@
 import { COUNTRIES } from "#constants/countries";
 import { JURISDICTIONS } from "#constants/jurisdictions";
 
+/**
+ * Given a birthplace country and/or state, return the country name
+ * if born outside the US, or the state name otherwise.
+ *
+ * @example
+ * formatBirthplaceCountryOrState("MX")
+ * // "Mexico"
+ * formatBirthplaceCountryOrState("US", "MA")
+ * // "Massachusetts"
+ */
 export const formatBirthplaceCountryOrState = (
   birthplaceCountry?: string,
   birthplaceState?: string,

web/src/lib/utils/formatBrowser.ts

@@ -1,5 +1,17 @@
 import type { IBrowser } from "ua-parser-js";
 
+/**
+ * Given a browser from `UAParser()`, return the browser name
+ * or "this browser" if unknown.
+ *
+ * Use with `UAParser(navigator.userAgent).browser` from "ua-parser-js".
+ *
+ * @example
+ * formatBrowser({ name: "Chrome" })
+ * // "Chrome"
+ * formatBrowser(null)
+ * // "this browser"
+ */
 export function formatBrowser(browser: Partial<IBrowser> | null) {
   return browser?.name || "this browser";
 }

web/src/lib/utils/formatCleanUrl.ts

@@ -1,6 +1,9 @@
 /**
- * Strips protocol, www prefix, and trailing slash from a URL for display.
- * e.g. "https://www.masstpc.org/" -> "masstpc.org"
+ * Given a URL, return the URL without protocol, "www", or trailing slash.
+ *
+ * @example
+ * formatCleanUrl("https://www.masstpc.org/")
+ * // "masstpc.org"
  */
 export function formatCleanUrl(url: string): string {
   return url.replace(/^https?:\/\/(www\.)?/, "").replace(/\/$/, "");