@northguild/gmt 1.14.2

package/dist/internal/normalizeTimeZone.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resolve a timezone string for the Unix/UTC formatters.
+ *
+ * - `"local"` → the system timezone via `getSystemTimeZone()`.
+ * - A valid IANA timezone identifier → returned as-is.
+ * - Anything else (undefined, empty, invalid name, typo) → `"UTC"`.
+ *
+ * The UTC fallback is intentional: `formatUnix` / `formatUtc` / the relative
+ * formatters expose `timeZone` as an *optional* convenience, so we degrade
+ * gracefully when callers pass nothing or pass a typo. Callers that need
+ * strict timezone validation should use `isValidTimeZone()` themselves
+ * before calling these formatters.
+ */
+export declare function normalizeTimeZone(tz?: string): string;

package/dist/internal/normalizeTimeZone.js

@@ -0,0 +1,22 @@
+import { getSystemTimeZone } from "../zoned/get/getSystemTimeZone.js";
+import { isValidTimeZone } from "../zoned/validate/index.js";
+/**
+ * Resolve a timezone string for the Unix/UTC formatters.
+ *
+ * - `"local"` → the system timezone via `getSystemTimeZone()`.
+ * - A valid IANA timezone identifier → returned as-is.
+ * - Anything else (undefined, empty, invalid name, typo) → `"UTC"`.
+ *
+ * The UTC fallback is intentional: `formatUnix` / `formatUtc` / the relative
+ * formatters expose `timeZone` as an *optional* convenience, so we degrade
+ * gracefully when callers pass nothing or pass a typo. Callers that need
+ * strict timezone validation should use `isValidTimeZone()` themselves
+ * before calling these formatters.
+ */
+export function normalizeTimeZone(tz) {
+    if (tz === "local")
+        return getSystemTimeZone();
+    if (typeof tz === "string" && tz.length > 0 && isValidTimeZone(tz))
+        return tz;
+    return "UTC";
+}

package/dist/internal/patternToken.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared token-pattern engine for J11's `parse*WithPattern` family.
+ *
+ * This is GMT's one named exception to `context/coding-standards.md`'s
+ * "manual string parsing" prohibition (Decision 4 in
+ * `context/roadmap/issues/J.md`). The exception is scoped to this module
+ * and the three `parse*WithPattern` public functions, and is bound by
+ * three rules, enforced throughout this file:
+ *   1. The regex is always built *from the pattern string itself* at call
+ *      time (see `compilePattern`) — never hand-rolled per-format string
+ *      slicing.
+ *   2. Extracted fields are handed to the caller for `Temporal.*.from(...,
+ *      { overflow: "reject" })` — a regex match alone only proves *shape*,
+ *      never validity (see each `parse*WithPattern` wrapper).
+ *   3. Never throws; malformed pattern, no match, or invalid input all
+ *      resolve to `null` here (the public wrappers translate that to
+ *      `""`).
+ */
+/** Field categories a pattern token can produce. Each may appear at most once per pattern. */
+export type PatternField = "year" | "month" | "day" | "hour" | "minute" | "second" | "millisecond" | "weekday" | "meridiem" | "era";
+/** Fields accepted by `parseDateWithPattern` — date-shaped tokens only. */
+export declare const DATE_PATTERN_FIELDS: ReadonlySet<PatternField>;
+/** Fields accepted by `parseTimeWithPattern` — time-shaped tokens only. */
+export declare const TIME_PATTERN_FIELDS: ReadonlySet<PatternField>;
+/** Fields accepted by `parseDateTimeWithPattern` — the full combined set. */
+export declare const DATE_TIME_PATTERN_FIELDS: ReadonlySet<PatternField>;
+/** Resolved output of a successful parse — only fields the pattern actually contained are set. */
+export interface ParsedPatternFields {
+    year?: number;
+    month?: number;
+    day?: number;
+    hour?: number;
+    minute?: number;
+    second?: number;
+    millisecond?: number;
+}
+/**
+ * Parse `value` against `pattern` and return the resolved candidate
+ * fields, or `null` on malformed pattern / no match / invalid input.
+ *
+ * `null` here always means "return the sentinel" to the caller — it
+ * never distinguishes malformed-pattern from no-match from invalid-input,
+ * matching the shared never-throw / sentinel-return contract.
+ */
+export declare function parseValueWithPattern(value: string, pattern: string, locale: string | undefined, allowedFields: ReadonlySet<PatternField>): ParsedPatternFields | null;

package/dist/internal/patternToken.js

@@ -0,0 +1,385 @@
+import { getLocaleEraNames } from "../plain/locale/getLocaleEraNames.js";
+import { getLocaleMeridiems } from "../plain/locale/getLocaleMeridiems.js";
+import { getLocaleMonthNames } from "../plain/locale/getLocaleMonthNames.js";
+import { getLocaleWeekdayNames } from "../plain/locale/getLocaleWeekdayNames.js";
+/** Fields accepted by `parseDateWithPattern` — date-shaped tokens only. */
+export const DATE_PATTERN_FIELDS = new Set([
+    "year",
+    "month",
+    "day",
+    "weekday",
+    "era",
+]);
+/** Fields accepted by `parseTimeWithPattern` — time-shaped tokens only. */
+export const TIME_PATTERN_FIELDS = new Set([
+    "hour",
+    "minute",
+    "second",
+    "millisecond",
+    "meridiem",
+]);
+/** Fields accepted by `parseDateTimeWithPattern` — the full combined set. */
+export const DATE_TIME_PATTERN_FIELDS = new Set([
+    ...DATE_PATTERN_FIELDS,
+    ...TIME_PATTERN_FIELDS,
+]);
+// Recognized vocabulary letters (Decision 1's Luxon-derived token set,
+// restricted to what's unambiguous to parse — no offset/zone-name tokens
+// since this story is plain-only). Any other unquoted letter in a pattern
+// is malformed. Numeric ranges are baked into each regex so a shape
+// mismatch (e.g. "13" for a 12-hour token) fails at the regex stage,
+// before ever reaching Temporal.
+const TOKEN_TABLE = {
+    y4: { field: "year", kind: "yearFull", regexSource: "\\d{4}" },
+    y2: { field: "year", kind: "yearShort", regexSource: "\\d{2}" },
+    M2: {
+        field: "month",
+        kind: "monthNumber",
+        regexSource: "(?:0[1-9]|1[0-2])",
+    },
+    M1: {
+        field: "month",
+        kind: "monthNumber",
+        regexSource: "(?:0?[1-9]|1[0-2])",
+    },
+    M3: { field: "month", kind: "monthNameShort" },
+    M4: { field: "month", kind: "monthNameLong" },
+    d2: { field: "day", kind: "day", regexSource: "(?:0[1-9]|[12]\\d|3[01])" },
+    d1: {
+        field: "day",
+        kind: "day",
+        regexSource: "(?:0?[1-9]|[12]\\d|3[01])",
+    },
+    H2: { field: "hour", kind: "hour24", regexSource: "(?:[01]\\d|2[0-3])" },
+    H1: {
+        field: "hour",
+        kind: "hour24",
+        regexSource: "(?:[01]?\\d|2[0-3])",
+    },
+    h2: { field: "hour", kind: "hour12", regexSource: "(?:0[1-9]|1[0-2])" },
+    h1: {
+        field: "hour",
+        kind: "hour12",
+        regexSource: "(?:0?[1-9]|1[0-2])",
+    },
+    m2: { field: "minute", kind: "minute", regexSource: "[0-5]\\d" },
+    m1: { field: "minute", kind: "minute", regexSource: "(?:[0-5]?\\d)" },
+    s2: { field: "second", kind: "second", regexSource: "[0-5]\\d" },
+    s1: { field: "second", kind: "second", regexSource: "(?:[0-5]?\\d)" },
+    S3: { field: "millisecond", kind: "millisecond", regexSource: "\\d{3}" },
+    E3: { field: "weekday", kind: "weekdayShort" },
+    E4: { field: "weekday", kind: "weekdayLong" },
+    a1: { field: "meridiem", kind: "meridiem" },
+    G2: { field: "era", kind: "eraShort" },
+    G4: { field: "era", kind: "eraLong" },
+};
+const VOCABULARY_LETTERS = "yMdHhmsSEaG";
+/**
+ * Split a pattern string into literal and letter-run parts.
+ *
+ * Quoted segments (`'...'`) are literals matched verbatim; a doubled `''`
+ * *inside* an open quote is the escape for one literal `'` character
+ * (mirrors Luxon's own escaping exactly — Decision 1 already establishes
+ * Luxon's vocabulary as this story's starting point). Any character that
+ * isn't part of a letter run and isn't inside a quote (separators,
+ * literal digits, punctuation) is automatically a one-character literal —
+ * no explicit quoting required for those.
+ */
+function tokenizePattern(pattern) {
+    const parts = [];
+    let i = 0;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        if (ch === "'") {
+            let j = i + 1;
+            let text = "";
+            let closed = false;
+            while (j < pattern.length) {
+                if (pattern[j] === "'") {
+                    if (pattern[j + 1] === "'") {
+                        text += "'";
+                        j += 2;
+                        continue;
+                    }
+                    j += 1;
+                    closed = true;
+                    break;
+                }
+                text += pattern[j];
+                j += 1;
+            }
+            // An unterminated quote has no unambiguous literal meaning — treat
+            // it as a malformed pattern rather than guessing where it "should"
+            // have closed.
+            if (!closed)
+                return null;
+            parts.push({ type: "literal", text });
+            i = j;
+            continue;
+        }
+        if (/[a-zA-Z]/.test(ch)) {
+            let j = i;
+            while (j < pattern.length && pattern[j] === ch)
+                j++;
+            parts.push({ type: "token", letter: ch, length: j - i });
+            i = j;
+            continue;
+        }
+        parts.push({ type: "literal", text: ch });
+        i++;
+    }
+    return parts;
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Build a case-insensitive alternation from a locale's name list.
+ *
+ * Names are sorted by descending length before joining with `|` so a
+ * longer name is tried before a shorter one that happens to be its
+ * prefix (e.g. a locale where a short-form weekday name is a strict
+ * prefix of a longer name) — otherwise the regex engine's left-to-right
+ * alternation would greedily commit to the shorter match and never
+ * backtrack into the longer one.
+ */
+function buildNameAlternation(names) {
+    return [...names]
+        .sort((a, b) => b.length - a.length)
+        .map((name) => escapeRegExp(name))
+        .join("|");
+}
+/**
+ * Compile a token pattern into an anchored `RegExp` plus the metadata
+ * needed to resolve each capture back to a field value.
+ *
+ * Returns `null` for any malformed pattern: an unquoted letter outside
+ * the recognized vocabulary, a recognized letter repeated to an
+ * unsupported width, a field appearing more than once, a field outside
+ * `allowedFields` (e.g. a time token handed to the date-only parser), an
+ * unterminated quote, or (for a locale-aware token) a locale that
+ * `Intl.Locale` cannot resolve.
+ */
+function compilePattern(pattern, allowedFields, locale) {
+    const parts = tokenizePattern(pattern);
+    if (parts === null)
+        return null;
+    const usedFields = new Set();
+    const tokens = [];
+    const regexPieces = [];
+    let groupCounter = 0;
+    for (const part of parts) {
+        if (part.type === "literal") {
+            regexPieces.push(escapeRegExp(part.text ?? ""));
+            continue;
+        }
+        const letter = part.letter;
+        const length = part.length;
+        // An unquoted letter outside the recognized vocabulary is always
+        // malformed, regardless of run length.
+        if (!VOCABULARY_LETTERS.includes(letter))
+            return null;
+        const spec = TOKEN_TABLE[`${letter}${length}`];
+        // A recognized letter repeated to a width not in the token table
+        // (e.g. "yyy", "hhh", "SS") is malformed.
+        if (!spec)
+            return null;
+        // A time-only token in a date-only pattern (or vice versa) is
+        // rejected here, before ever attempting to match `value` — this is
+        // the pattern-parsing-stage rejection the spec requires.
+        if (!allowedFields.has(spec.field))
+            return null;
+        // The same field appearing twice (e.g. two independent yyyy runs, or
+        // H combined with hh) is malformed — each field may resolve to only
+        // one captured value.
+        if (usedFields.has(spec.field))
+            return null;
+        usedFields.add(spec.field);
+        const groupName = `g${groupCounter++}`;
+        if (spec.regexSource) {
+            regexPieces.push(`(?<${groupName}>${spec.regexSource})`);
+            tokens.push({ groupName, field: spec.field, kind: spec.kind });
+            continue;
+        }
+        if (spec.kind === "monthNameShort" || spec.kind === "monthNameLong") {
+            const names = getLocaleMonthNames(locale, spec.kind === "monthNameLong" ? "long" : "short");
+            if (names.length !== 12)
+                return null; // locale not resolvable
+            regexPieces.push(`(?<${groupName}>${buildNameAlternation(names)})`);
+            tokens.push({
+                groupName,
+                field: spec.field,
+                kind: spec.kind,
+                monthNames: names,
+            });
+            continue;
+        }
+        if (spec.kind === "weekdayShort" || spec.kind === "weekdayLong") {
+            const names = getLocaleWeekdayNames(locale, spec.kind === "weekdayLong" ? "long" : "short");
+            if (names.length !== 7)
+                return null;
+            // Deliberate scope limit: the weekday name is consumed and matched
+            // against the pattern (so the overall shape still has to line up)
+            // but is NOT cross-validated against the constructed date — that
+            // would require a second weekday-index-to-ISO-dayOfWeek mapping
+            // layer this story does not build. No capturing group is created;
+            // nothing about this token feeds `resolvePatternFields`.
+            regexPieces.push(`(?:${buildNameAlternation(names)})`);
+            continue;
+        }
+        if (spec.kind === "meridiem") {
+            const meridiems = getLocaleMeridiems(locale);
+            if (meridiems.length !== 2)
+                return null;
+            regexPieces.push(`(?<${groupName}>${buildNameAlternation(meridiems)})`);
+            tokens.push({
+                groupName,
+                field: spec.field,
+                kind: spec.kind,
+                meridiems,
+            });
+            continue;
+        }
+        // era (eraShort | eraLong)
+        const eras = getLocaleEraNames(locale, spec.kind === "eraLong" ? "long" : "short");
+        if (eras.length !== 2)
+            return null;
+        regexPieces.push(`(?<${groupName}>${buildNameAlternation(eras)})`);
+        tokens.push({ groupName, field: spec.field, kind: spec.kind, eras });
+    }
+    // Anchor the fully assembled pattern so only a whole-string match
+    // counts — a `value` that merely starts with something pattern-shaped
+    // (e.g. trailing garbage) must not silently succeed. The whole
+    // alternation is case-insensitive so locale name matching (and any
+    // literal separators) doesn't depend on the caller's casing.
+    const regex = new RegExp(`^${regexPieces.join("")}$`, "i");
+    return { regex, tokens };
+}
+/**
+ * Resolve a successful regex match's captures back into date/time field
+ * values, applying the two-digit-year pivot, 12-hour-to-24-hour
+ * conversion (via a matched meridiem), and BCE/CE year adjustment.
+ *
+ * This step only ever produces a *candidate* fields object — it does not
+ * itself prove the fields form a real date/time. The caller is
+ * responsible for handing the result to `Temporal.*.from(fields, {
+ * overflow: "reject" })`, which is what actually validates it.
+ */
+function resolvePatternFields(match, tokens) {
+    const groups = (match.groups ?? {});
+    const fields = {};
+    let hourIsTwelveHour = false;
+    let meridiemIsPM = false;
+    let eraIsBCE = false;
+    for (const token of tokens) {
+        const raw = groups[token.groupName];
+        if (raw === undefined)
+            continue;
+        switch (token.kind) {
+            case "yearFull":
+                fields.year = Number.parseInt(raw, 10);
+                break;
+            case "yearShort": {
+                // Two-digit year pivot: 00-68 -> 2000-2068, 69-99 -> 1969-1999.
+                // Fixed rule (mirrors common strptime %y behavior) — not a
+                // configurable/global setting.
+                const numeric = Number.parseInt(raw, 10);
+                fields.year = numeric <= 68 ? 2000 + numeric : 1900 + numeric;
+                break;
+            }
+            case "monthNumber":
+                fields.month = Number.parseInt(raw, 10);
+                break;
+            case "monthNameShort":
+            case "monthNameLong": {
+                const names = token.monthNames ?? [];
+                const index = names.findIndex((name) => name.toLowerCase() === raw.toLowerCase());
+                fields.month = index + 1; // -1 (not found) would yield 0, which Temporal rejects
+                break;
+            }
+            case "day":
+                fields.day = Number.parseInt(raw, 10);
+                break;
+            case "hour24":
+                fields.hour = Number.parseInt(raw, 10);
+                break;
+            case "hour12":
+                hourIsTwelveHour = true;
+                fields.hour = Number.parseInt(raw, 10);
+                break;
+            case "minute":
+                fields.minute = Number.parseInt(raw, 10);
+                break;
+            case "second":
+                fields.second = Number.parseInt(raw, 10);
+                break;
+            case "millisecond":
+                fields.millisecond = Number.parseInt(raw, 10);
+                break;
+            case "meridiem": {
+                const [amLabel, pmLabel] = token.meridiems ?? ["", ""];
+                // Guard against a locale whose AM/PM labels happen to coincide —
+                // in that case there is nothing to distinguish, so don't treat
+                // the match as PM by accident.
+                meridiemIsPM =
+                    raw.toLowerCase() === (pmLabel ?? "").toLowerCase() &&
+                        (pmLabel ?? "").toLowerCase() !== (amLabel ?? "").toLowerCase();
+                break;
+            }
+            case "eraShort":
+            case "eraLong": {
+                const [bceLabel, ceLabel] = token.eras ?? ["", ""];
+                eraIsBCE =
+                    raw.toLowerCase() === (bceLabel ?? "").toLowerCase() &&
+                        (bceLabel ?? "").toLowerCase() !== (ceLabel ?? "").toLowerCase();
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    if (hourIsTwelveHour && fields.hour !== undefined) {
+        // Resolve h/hh to 24-hour. With no `a` token present in the pattern
+        // at all, `meridiemIsPM` stays false and this falls through the same
+        // branch as an explicit AM match — the documented "ambiguous AM
+        // default" behavior.
+        if (meridiemIsPM && fields.hour !== 12)
+            fields.hour += 12;
+        if (!meridiemIsPM && fields.hour === 12)
+            fields.hour = 0;
+    }
+    if (eraIsBCE && fields.year !== undefined) {
+        // Proleptic Gregorian: 1 BCE = year 0, 2 BCE = year -1, etc.
+        fields.year = 1 - fields.year;
+    }
+    return fields;
+}
+/**
+ * Parse `value` against `pattern` and return the resolved candidate
+ * fields, or `null` on malformed pattern / no match / invalid input.
+ *
+ * `null` here always means "return the sentinel" to the caller — it
+ * never distinguishes malformed-pattern from no-match from invalid-input,
+ * matching the shared never-throw / sentinel-return contract.
+ */
+export function parseValueWithPattern(value, pattern, locale, allowedFields) {
+    if (typeof value !== "string" || value.length === 0)
+        return null;
+    if (typeof pattern !== "string" || pattern.length === 0)
+        return null;
+    if (locale !== undefined && typeof locale !== "string")
+        return null;
+    // No `locale` is required to parse a pattern containing only numeric
+    // tokens, but a name-based token (MMM/MMMM/EEE/EEEE/a/GG/GGGG) needs
+    // *some* locale to resolve against — default to "en-US" rather than
+    // silently returning "" for every caller who didn't have another
+    // locale in mind.
+    const resolvedLocale = typeof locale === "string" ? locale : "en-US";
+    const compiled = compilePattern(pattern, allowedFields, resolvedLocale);
+    if (compiled === null)
+        return null;
+    const match = value.match(compiled.regex);
+    if (match === null)
+        return null;
+    return resolvePatternFields(match, compiled.tokens);
+}

package/dist/internal/resolveDateTimeUnit.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Normalize a date-time unit string to its singular form.
+ *
+ * - Accepts singular ("day"), plural ("days"), and already-singular forms.
+ * - Returns the original string if it is not a recognized DateTimeUnit.
+ * - Singular counterpart of `resolveDurationUnit`, which normalizes to plurals.
+ *
+ * @param unit raw unit string from caller input
+ * @returns normalized singular unit string, or the original if not recognized
+ */
+export declare function resolveDateTimeUnit(unit: string): string;

package/dist/internal/resolveDateTimeUnit.js

@@ -0,0 +1,23 @@
+import { isValidDateTimeUnit } from "../plain/validate/index.js";
+/**
+ * Normalize a date-time unit string to its singular form.
+ *
+ * - Accepts singular ("day"), plural ("days"), and already-singular forms.
+ * - Returns the original string if it is not a recognized DateTimeUnit.
+ * - Singular counterpart of `resolveDurationUnit`, which normalizes to plurals.
+ *
+ * @param unit raw unit string from caller input
+ * @returns normalized singular unit string, or the original if not recognized
+ */
+export function resolveDateTimeUnit(unit) {
+    if (isValidDateTimeUnit(unit)) {
+        return unit;
+    }
+    if (unit.endsWith("s")) {
+        const singular = unit.slice(0, -1);
+        if (isValidDateTimeUnit(singular)) {
+            return singular;
+        }
+    }
+    return unit;
+}

package/dist/internal/resolveDurationRelativeTo.d.ts

@@ -0,0 +1,29 @@
+import type { DurationRelativeTo } from "../types/index.js";
+/**
+ * Resolve a `DurationRelativeTo` value for `Temporal.Duration`'s `relativeTo` option, converting
+ * a GMT calendar-annotated PlainDate string (`"5784-06-15[u-ca=hebrew]"`, as produced by
+ * `convertDateToCalendar`) into the `Temporal.PlainDate` it actually names before handing it to
+ * Temporal.
+ *
+ * Without this, Temporal's own `relativeTo` string parsing reads GMT's native-digit shape as if
+ * it were Temporal's ISO-digit `[u-ca=...]` convention instead (see
+ * `context/coding-standards.md`'s E1 scoped-exception note on the two conventions), silently
+ * resolving to the wrong date with no error — e.g. `relativeTo: "5784-06-15[u-ca=hebrew]"`
+ * previously returned the day count for Gregorian year 5784, not the Hebrew date it names. Found
+ * and fixed as part of E5 (issue #78); this is D1's "`duration/`'s `relativeTo` accepts the GMT
+ * shape only" decision of record.
+ *
+ * Every other `relativeTo` shape (a plain ISO string, a `PlainDateTime`/`ZonedDateTime` object
+ * or `-Like`, or any string that isn't a GMT calendar-annotated PlainDate) passes through
+ * unchanged — GMT's calendar-string contract only covers `plain/` `PlainDate` (D1).
+ *
+ * Resolves to a `Temporal.PlainDateTime` (midnight, same calendar) rather than a bare
+ * `Temporal.PlainDate` — verified equivalent at runtime (`.total`/`.round`/`.compare` all
+ * produce the identical result either way) and `PlainDateTime` is the type Temporal's own
+ * `relativeTo` option signature actually accepts, unlike `PlainDate`.
+ *
+ * Throws if the calendar-annotated string is malformed. Callers already wrap the Temporal call
+ * consuming this in `try { ... } catch { return sentinel }` per GMT's contract, so this composes
+ * directly into that same block rather than needing its own try/catch.
+ */
+export declare function resolveDurationRelativeTo(relativeTo: DurationRelativeTo | undefined): DurationRelativeTo | undefined;

package/dist/internal/resolveDurationRelativeTo.js

@@ -0,0 +1,35 @@
+import { calendarDate } from "../regex/index.js";
+import { parseCalendarDateValue } from "./calendarDateString.js";
+/**
+ * Resolve a `DurationRelativeTo` value for `Temporal.Duration`'s `relativeTo` option, converting
+ * a GMT calendar-annotated PlainDate string (`"5784-06-15[u-ca=hebrew]"`, as produced by
+ * `convertDateToCalendar`) into the `Temporal.PlainDate` it actually names before handing it to
+ * Temporal.
+ *
+ * Without this, Temporal's own `relativeTo` string parsing reads GMT's native-digit shape as if
+ * it were Temporal's ISO-digit `[u-ca=...]` convention instead (see
+ * `context/coding-standards.md`'s E1 scoped-exception note on the two conventions), silently
+ * resolving to the wrong date with no error — e.g. `relativeTo: "5784-06-15[u-ca=hebrew]"`
+ * previously returned the day count for Gregorian year 5784, not the Hebrew date it names. Found
+ * and fixed as part of E5 (issue #78); this is D1's "`duration/`'s `relativeTo` accepts the GMT
+ * shape only" decision of record.
+ *
+ * Every other `relativeTo` shape (a plain ISO string, a `PlainDateTime`/`ZonedDateTime` object
+ * or `-Like`, or any string that isn't a GMT calendar-annotated PlainDate) passes through
+ * unchanged — GMT's calendar-string contract only covers `plain/` `PlainDate` (D1).
+ *
+ * Resolves to a `Temporal.PlainDateTime` (midnight, same calendar) rather than a bare
+ * `Temporal.PlainDate` — verified equivalent at runtime (`.total`/`.round`/`.compare` all
+ * produce the identical result either way) and `PlainDateTime` is the type Temporal's own
+ * `relativeTo` option signature actually accepts, unlike `PlainDate`.
+ *
+ * Throws if the calendar-annotated string is malformed. Callers already wrap the Temporal call
+ * consuming this in `try { ... } catch { return sentinel }` per GMT's contract, so this composes
+ * directly into that same block rather than needing its own try/catch.
+ */
+export function resolveDurationRelativeTo(relativeTo) {
+    if (typeof relativeTo !== "string" || !calendarDate.test(relativeTo)) {
+        return relativeTo;
+    }
+    return parseCalendarDateValue(relativeTo).toPlainDateTime();
+}

package/dist/internal/resolveDurationUnit.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Normalize a duration unit string to its plural form.
+ *
+ * - Accepts singular ("day"), plural ("days"), and already-plural forms.
+ * - Returns the original string if it is not a recognized DateTimeDurationUnit.
+ *
+ * @param unit raw unit string from caller input
+ * @returns normalized plural unit string, or the original if not recognized
+ */
+export declare function resolveDurationUnit(unit: string): string;

package/dist/internal/resolveDurationUnit.js

@@ -0,0 +1,23 @@
+import { isValidDateTimeDurationUnit } from "../plain/validate/index.js";
+/**
+ * Normalize a duration unit string to its plural form.
+ *
+ * - Accepts singular ("day"), plural ("days"), and already-plural forms.
+ * - Returns the original string if it is not a recognized DateTimeDurationUnit.
+ *
+ * @param unit raw unit string from caller input
+ * @returns normalized plural unit string, or the original if not recognized
+ */
+export function resolveDurationUnit(unit) {
+    if (isValidDateTimeDurationUnit(unit)) {
+        return unit;
+    }
+    if (unit.endsWith("s")) {
+        return unit;
+    }
+    const plural = `${unit}s`;
+    if (isValidDateTimeDurationUnit(plural)) {
+        return plural;
+    }
+    return unit;
+}

package/dist/internal/resolveOverflow.d.ts

@@ -0,0 +1,10 @@
+import type { Overflow } from "../types/index.js";
+/**
+ * Resolve an optional overflow value to its default ("constrain") when unset.
+ *
+ * @param overflow optional overflow value
+ * @example resolveOverflow(undefined) // "constrain"
+ * @example resolveOverflow("reject") // "reject"
+ * @returns the resolved overflow value
+ */
+export declare function resolveOverflow(overflow?: Overflow): Overflow;

package/dist/internal/resolveOverflow.js

@@ -0,0 +1,11 @@
+/**
+ * Resolve an optional overflow value to its default ("constrain") when unset.
+ *
+ * @param overflow optional overflow value
+ * @example resolveOverflow(undefined) // "constrain"
+ * @example resolveOverflow("reject") // "reject"
+ * @returns the resolved overflow value
+ */
+export function resolveOverflow(overflow) {
+    return overflow ?? "constrain";
+}

package/dist/internal/resolveRelativeRounding.d.ts

@@ -0,0 +1,19 @@
+import type { RelativeRoundingMethod } from "../types/index.js";
+/**
+ * Round a relative-time distance to an integer using the given method, defaulting to "round".
+ *
+ * Applied directly to the signed fractional value (not its absolute value), so floor/ceil
+ * respect whether the distance is past (negative) or future (positive) — matches date-fns's
+ * `formatDistanceStrict` `roundingMethod` semantics. A rounded `-0` is preserved rather than
+ * normalized to `0`: `Intl.RelativeTimeFormat` treats the sign of zero as meaningful (with
+ * `numeric: "always"`, `-0` renders as "0 <unit> ago" and `0` as "in 0 <unit>"), so collapsing
+ * it here would change existing `formatRelative*` output for near-zero distances.
+ *
+ * @param value the fractional distance in the target display unit
+ * @param method optional: "floor" | "ceil" | "round" (default "round")
+ * @returns the rounded amount
+ * @example resolveRelativeRounding(2.7) // 3
+ * @example resolveRelativeRounding(2.7, "floor") // 2
+ * @example resolveRelativeRounding(-2.7, "ceil") // -2
+ */
+export declare function resolveRelativeRounding(value: number, method?: RelativeRoundingMethod): number;