Temporal

Date and time helpers built around the Temporal API with an @js-temporal/polyfill fallback, offering Day.js-style formatting and immutable values.

AI Agent Quick Reference

Core Exports

| Export | Type | Description | | --- | --- | --- | | temporal(input?: DateTimeInput, options?: DateTimeFactoryOptions): DateTimeValue | Function | Instantiates a wrapper around a zoned datetime. Returns a fallback invalid object on parse errors. | | tryTemporal(input?: DateTimeInput, options?: DateTimeFactoryOptions): DateTimeValue \| null | Function | Instantiates a wrapper, returning null if parsing fails. | | toDateString(year: number, month: number, day: number): string | Function | Combines parts into an ISO-8601 date string (YYYY-MM-DD). | | parseDate(value: string): DateParts \| null | Function | Extracts { year, month, day } from an ISO date. | | getTodayString(timeZone?: string): string | Function | Returns current date string (YYYY-MM-DD) in specified timezone. | | formatDate(value: string, locale: string, format?: string): string | Function | Formats an ISO-8601 date string. | | formatTimestamp(value: DateTimeInput \| "", locale?: string, options?: Intl.DateTimeFormatOptions): string | Function | Formats timestamps according to Intl options. | | getCalendarDays(year: number, month: number, min?: string, max?: string): CalendarDay[] | Function | Builds a 42-day calendar array (useful for monthly grid rendering). |

Core Types & Accessors

• DateTimeValue: Immutable datetime wrapper:
  • Accessors: year(), month() (0-indexed), date(), day(), hour(), minute(), second(), millisecond(), unix()
  • Math: add(amount, unit), subtract(amount, unit)
  • Comparisons: isBefore(other, unit?), isAfter(other, unit?), isSame(other, unit?), isBetween(start, end, unit?, inclusivity?)
  • Boundaries: startOf(unit), endOf(unit)
  • Serializers: toISOString(), toJSON(), toDate()
• Supported Units: "year" | "month" | "week" | "day" | "hour" | "minute" | "second" | "millisecond" (singular/plural and shorthand e.g. "y", "M", "d" are supported).

Basic Usage

import { temporal, formatTimestamp } from "@azlib/temporal";

// Create instance
const dt = temporal("2026-05-29T10:00:00Z", { timeZone: "UTC" });

// Immutable operations
const nextDayStr = dt.add(1, "day").format("YYYY-MM-DD"); // "2026-05-30"

// Formatting options
const formatted = formatTimestamp(dt.toISOString(), "en-US", { dateStyle: "long" });

Calendar Grid Calculations

import { getCalendarDays } from "@azlib/temporal";

// Generate 42 calendar grid cells (including month padding offsets)
const days = getCalendarDays(2026, 5); // June 2026 (0-indexed month 5)
days.forEach((cell) => {
  console.log(cell.date, cell.isCurrentMonth, cell.isToday, cell.isDisabled);
});

Formatting Tokens Reference

• YYYY: 4-digit year (e.g. 2026)
• YY: 2-digit year (e.g. 26)
• MMMM: Full month name (e.g. January)
• MMM: Short month name (e.g. Jan)
• MM: 2-digit month (e.g. 01)
• M: 1-digit month (e.g. 1)
• DD: 2-digit day of month (e.g. 09)
• D: 1-digit day of month (e.g. 9)
• HH: 2-digit hour (24h)
• mm: 2-digit minute
• ss: 2-digit second
• Z: Timezone offset (e.g. +00:00)

Behavioral Gotchas

• 0-Indexed Months: Month accessors (month(), parseDate(), getCalendarDays()) treat January as 0 and December as 11 to mirror JavaScript Date conventions. However, toDateString() accepts standard 1-based months.
• Fail-Safe Parsing: Unlike vanilla Temporal API which throws on parse errors, calling temporal("invalid-input") does not crash. It returns a valid object structure whose .isValid() method evaluates to false.