@northguild/gmt 1.14.2 → 1.16.0

package/dist/plain/format/formatRelativeDateTime.d.ts

@@ -1,32 +1,30 @@
-import type { RelativeRoundingMethod } from "../../types/index.js";
-type RelativeUnit = "year" | "month" | "week" | "day" | "hour" | "minute" | "second";
-export interface FormatRelativeDateTimeOptions {
-    style?: "long" | "short" | "narrow";
-    numeric?: "always" | "auto";
-    largestUnit?: RelativeUnit;
-    /**
-     * How the computed distance rounds to the display unit: "floor" rounds toward the
-     * earlier boundary, "ceil" toward the later boundary, "round" (default) to the nearest —
-     * matches current behavior when omitted.
-     */
-    roundingMethod?: RelativeRoundingMethod;
-    reference?: string;
+import type { RelativeDateTimeUnit, RelativeTimeFormatOptions } from "../../types/index.js";
+export interface FormatRelativeDateTimeOptions extends RelativeTimeFormatOptions {
+    largestUnit?: RelativeDateTimeUnit;
 }
 /**
  * Format the relative time between a plain date-time and a reference date-time.
  *
- * - Auto-picks the display unit (second through year) based on the distance, unless
- *   `largestUnit` forces one.
+ * - Auto-picks the display unit based on the distance, unless `largestUnit` forces one: second
+ *   under a minute, minute under an hour, hour under a day, then `formatRelativeDate`'s thresholds —
+ *   day under 7 days, week under 28, month under 365, year beyond — so a 3-year distance reads
+ *   "3 years ago".
+ * - **Compatibility:** before 1.16.0 week, month and year were never auto-picked ("1,096 days ago").
+ *   Pass `largestUnit: "day"` to keep a day count.
  * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
+ *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO date-time string to format
- * @param locale optional: BCP 47 locale tag
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
  * @returns the formatted relative-time string, or "" on invalid input
  *
- * @example formatRelativeDateTime("2026-03-17T09:00:00", "en-GB", { style: "long" }) // "in 3 hours"
- * @example formatRelativeDateTime(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
+ * @example formatRelativeDateTime("2026-03-17T09:00:00", "en-GB", { style: "long", reference: "2026-03-17T06:00:00" }) // "in 3 hours"
+ * @example formatRelativeDateTime("2026-01-15T00:00:00", "en-US", { reference: "2026-01-15T10:30:00", roundingMethod: "floor" }) // "11 hours ago" (−10.5 hours floors to −11; the default rounds to 10)
+ * @example formatRelativeDateTime("2021-03-15T12:00:00", "en-US", { reference: "2024-03-15T12:00:00" }) // "3 years ago"
  * @example formatRelativeDateTime("not-a-date") // ""
+ * @example formatRelativeDateTime("2024-03-15T09:00:00", ["fr-FR", "en-US"], { reference: "2024-03-15T12:00:00" }) // "il y a 3 heures"
+ * @example formatRelativeDateTime("2024-03-12T10:00:00", "en-US", null as never) // "" (null options)
  */
-export declare function formatRelativeDateTime(value: string, locale?: string, options?: FormatRelativeDateTimeOptions): string;
-export {};
+export declare function formatRelativeDateTime(value: string, locale?: string | string[], options?: FormatRelativeDateTimeOptions): string;

package/dist/plain/format/formatRelativeDateTime.js

@@ -1,57 +1,59 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
-import { normalizeDateTime, resolveRelativeRounding } from "../../internal/index.js";
+import { durationTotal } from "../../internal/index.js";
+import { formatRelativeDuration } from "../../internal/formatRelativeDuration.js";
 import { isValidDateTime } from "../validate/index.js";
-const AUTO_UNITS = [
-    { unit: "second", maxSeconds: 60 },
-    { unit: "minute", maxSeconds: 3_600 },
-    { unit: "hour", maxSeconds: 86_400 },
-    { unit: "day", maxSeconds: Infinity },
-];
 /**
  * Format the relative time between a plain date-time and a reference date-time.
  *
- * - Auto-picks the display unit (second through year) based on the distance, unless
- *   `largestUnit` forces one.
+ * - Auto-picks the display unit based on the distance, unless `largestUnit` forces one: second
+ *   under a minute, minute under an hour, hour under a day, then `formatRelativeDate`'s thresholds —
+ *   day under 7 days, week under 28, month under 365, year beyond — so a 3-year distance reads
+ *   "3 years ago".
+ * - **Compatibility:** before 1.16.0 week, month and year were never auto-picked ("1,096 days ago").
+ *   Pass `largestUnit: "day"` to keep a day count.
  * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
+ *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO date-time string to format
- * @param locale optional: BCP 47 locale tag
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
  * @returns the formatted relative-time string, or "" on invalid input
  *
- * @example formatRelativeDateTime("2026-03-17T09:00:00", "en-GB", { style: "long" }) // "in 3 hours"
- * @example formatRelativeDateTime(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
+ * @example formatRelativeDateTime("2026-03-17T09:00:00", "en-GB", { style: "long", reference: "2026-03-17T06:00:00" }) // "in 3 hours"
+ * @example formatRelativeDateTime("2026-01-15T00:00:00", "en-US", { reference: "2026-01-15T10:30:00", roundingMethod: "floor" }) // "11 hours ago" (−10.5 hours floors to −11; the default rounds to 10)
+ * @example formatRelativeDateTime("2021-03-15T12:00:00", "en-US", { reference: "2024-03-15T12:00:00" }) // "3 years ago"
  * @example formatRelativeDateTime("not-a-date") // ""
+ * @example formatRelativeDateTime("2024-03-15T09:00:00", ["fr-FR", "en-US"], { reference: "2024-03-15T12:00:00" }) // "il y a 3 heures"
+ * @example formatRelativeDateTime("2024-03-12T10:00:00", "en-US", null as never) // "" (null options)
  */
 export function formatRelativeDateTime(value, locale, options = {}) {
-    if (!isValidDateTime(value))
-        return "";
-    if (options.reference !== undefined && !isValidDateTime(options.reference))
-        return "";
     try {
-        const target = Temporal.PlainDateTime.from(value);
-        const reference = options.reference
-            ? Temporal.PlainDateTime.from(options.reference)
-            : Temporal.Now.plainDateTimeISO();
-        const diff = target.since(reference);
-        const absSeconds = Math.abs(diff.total("second"));
-        const unit = options.largestUnit ??
-            AUTO_UNITS.find((t) => absSeconds < t.maxSeconds)?.unit ??
-            "day";
-        let amount;
+        // Temporal GetOptionsObject: options must be an object or omitted; null and other primitives are
+        // invalid input.
+        if (options === null || typeof options !== "object")
+            return "";
+        if (!isValidDateTime(value))
+            return "";
+        if (options.reference !== undefined && !isValidDateTime(options.reference))
+            return "";
         try {
-            amount = resolveRelativeRounding(diff.total(unit), options.roundingMethod);
+            const target = Temporal.PlainDateTime.from(value);
+            const reference = options.reference
+                ? Temporal.PlainDateTime.from(options.reference)
+                : Temporal.Now.plainDateTimeISO();
+            const diff = target.since(reference);
+            // month/year are calendrical — relativeTo needs a PlainDate
+            return formatRelativeDuration(diff, locale, options, (unit) => durationTotal(diff, unit, reference.toPlainDate()));
         }
         catch {
-            // month/year are calendrical — relativeTo needs a PlainDate
-            amount = resolveRelativeRounding(diff.total({ unit, relativeTo: reference.toPlainDate() }), options.roundingMethod);
+            return "";
         }
-        return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
-            numeric: options.numeric ?? "auto",
-            style: options.style ?? "long",
-        }).format(amount, unit));
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/plain/format/formatRelativeTime.d.ts

@@ -1,16 +1,6 @@
-import type { RelativeRoundingMethod } from "../../types/index.js";
-type RelativeUnit = "hour" | "minute" | "second";
-export interface FormatRelativeTimeOptions {
-    style?: "long" | "short" | "narrow";
-    numeric?: "always" | "auto";
-    largestUnit?: RelativeUnit;
-    /**
-     * How the computed distance rounds to the display unit: "floor" rounds toward the
-     * earlier boundary, "ceil" toward the later boundary, "round" (default) to the nearest —
-     * matches current behavior when omitted.
-     */
-    roundingMethod?: RelativeRoundingMethod;
-    reference?: string;
+import type { RelativeTimeFormatOptions, RelativeTimeUnit } from "../../types/index.js";
+export interface FormatRelativeTimeOptions extends RelativeTimeFormatOptions {
+    largestUnit?: RelativeTimeUnit;
 }
 /**
  * Format the relative time between a plain time and a reference time.
@@ -18,15 +8,18 @@ export interface FormatRelativeTimeOptions {
  * - Auto-picks the display unit (second/minute/hour) based on the distance, unless
  *   `largestUnit` forces one.
  * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
+ *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO time string to format
- * @param locale optional: BCP 47 locale tag
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
  * @returns the formatted relative-time string, or "" on invalid input
  *
- * @example formatRelativeTime("14:30:00", "en-US", { style: "short" }) // "2 hr. ago"
- * @example formatRelativeTime(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
+ * @example formatRelativeTime("14:30:00", "en-US", { style: "short", reference: "16:30:00" }) // "2 hr. ago"
+ * @example formatRelativeTime("09:00:00", "en-US", { reference: "10:30:00", roundingMethod: "floor" }) // "2 hours ago" (−1.5 hours floors to −2)
  * @example formatRelativeTime("not-a-time") // ""
+ * @example formatRelativeTime("10:00:00", ["fr-FR", "en-US"], { reference: "12:00:00" }) // "il y a 2 heures"
+ * @example formatRelativeTime("10:00:00", "en-US", null as never) // "" (null options)
  */
-export declare function formatRelativeTime(value: string, locale?: string, options?: FormatRelativeTimeOptions): string;
-export {};
+export declare function formatRelativeTime(value: string, locale?: string | string[], options?: FormatRelativeTimeOptions): string;

package/dist/plain/format/formatRelativeTime.js

@@ -12,38 +12,53 @@ const AUTO_UNITS = [
  * - Auto-picks the display unit (second/minute/hour) based on the distance, unless
  *   `largestUnit` forces one.
  * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
+ *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO time string to format
- * @param locale optional: BCP 47 locale tag
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
  * @returns the formatted relative-time string, or "" on invalid input
  *
- * @example formatRelativeTime("14:30:00", "en-US", { style: "short" }) // "2 hr. ago"
- * @example formatRelativeTime(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
+ * @example formatRelativeTime("14:30:00", "en-US", { style: "short", reference: "16:30:00" }) // "2 hr. ago"
+ * @example formatRelativeTime("09:00:00", "en-US", { reference: "10:30:00", roundingMethod: "floor" }) // "2 hours ago" (−1.5 hours floors to −2)
  * @example formatRelativeTime("not-a-time") // ""
+ * @example formatRelativeTime("10:00:00", ["fr-FR", "en-US"], { reference: "12:00:00" }) // "il y a 2 heures"
+ * @example formatRelativeTime("10:00:00", "en-US", null as never) // "" (null options)
  */
 export function formatRelativeTime(value, locale, options = {}) {
-    if (!isValidTime(value))
-        return "";
-    if (options.reference !== undefined && !isValidTime(options.reference))
-        return "";
     try {
-        const target = Temporal.PlainTime.from(value);
-        const reference = options.reference
-            ? Temporal.PlainTime.from(options.reference)
-            : Temporal.Now.plainTimeISO();
-        const diff = target.since(reference);
-        const absSeconds = Math.abs(diff.total("second"));
-        const unit = options.largestUnit ??
-            AUTO_UNITS.find((t) => absSeconds < t.maxSeconds)?.unit ??
-            "hour";
-        const amount = resolveRelativeRounding(diff.total(unit), options.roundingMethod);
-        return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
-            numeric: options.numeric ?? "auto",
-            style: options.style ?? "long",
-        }).format(amount, unit));
+        // Temporal GetOptionsObject: options must be an object or omitted; null and other primitives are
+        // invalid input.
+        if (options === null || typeof options !== "object")
+            return "";
+        if (!isValidTime(value))
+            return "";
+        if (options.reference !== undefined && !isValidTime(options.reference))
+            return "";
+        try {
+            const target = Temporal.PlainTime.from(value);
+            const reference = options.reference
+                ? Temporal.PlainTime.from(options.reference)
+                : Temporal.Now.plainTimeISO();
+            const diff = target.since(reference);
+            const absSeconds = Math.abs(diff.total("second"));
+            const unit = options.largestUnit === undefined
+                ? (AUTO_UNITS.find((t) => absSeconds < t.maxSeconds)?.unit ?? "hour")
+                : options.largestUnit;
+            const amount = resolveRelativeRounding(diff.total(unit), options.roundingMethod);
+            return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
+                numeric: options.numeric === undefined ? "auto" : options.numeric,
+                style: options.style === undefined ? "long" : options.style,
+            }).format(amount, unit));
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/plain/format/formatSql.d.ts

@@ -1,20 +1,25 @@
 /**
- * Format a plain ISO 8601 datetime string as an ANSI SQL / ODBC datetime
- * literal — the `YYYY-MM-DD HH:MM:SS` form MySQL, SQLite, and standard SQL
- * `DATETIME`/`TIMESTAMP` columns (without a time zone) accept.
+ * Format a plain ISO 8601 datetime string as a SQL timestamp literal without a time zone — the
+ * `YYYY-MM-DD HH:MM:SS[.fff]` form of standard SQL `TIMESTAMP` and MySQL/SQLite `DATETIME`
+ * columns.
  *
- * - **Plain only.** SQL's offset-carrying `TIMESTAMPTZ` literal
- *   (`YYYY-MM-DD HH:MM:SS±HH:MM`, e.g. PostgreSQL) is out of scope — this
- *   targets the far more common tz-less `DATETIME` column shape. There is no
- *   zoned counterpart in this story.
- * - The only change from GMT's own ISO output is the separator: `T` becomes
- *   a single space. Fractional seconds, when present, are preserved as-is.
+ * - **Grammar:** SQL-92 §5.3 `<timestamp string>` and the ODBC `ts` escape, which `parseSql`
+ *   reads: the date, a single space, and the time with seconds always written.
+ * - A year outside SQL-92's `0001`–`9999` (Table 10) returns `""`: the literal has no sign and
+ *   no expanded year to write it with.
+ * - **Plain only.** SQL's offset-carrying `TIMESTAMP WITH TIME ZONE` literal
+ *   (`YYYY-MM-DD HH:MM:SS±HH:MM`, e.g. PostgreSQL) is out of scope — this targets the far more
+ *   common tz-less column shape. There is no zoned counterpart.
+ * - Fractional seconds are written as Temporal writes them: only the digits needed, with
+ *   trailing zeros dropped (`.500` → `.5`).
  *
  * @param value plain ISO 8601 datetime string (e.g. "2024-03-15T14:30:00")
- * @returns SQL datetime literal, or "" on invalid input
+ * @returns SQL timestamp literal, or "" on invalid input
  *
  * @example formatSql("2024-03-15T14:30:00") // "2024-03-15 14:30:00"
+ * @example formatSql("2024-03-15T14:30") // "2024-03-15 14:30:00"
  * @example formatSql("2024-03-15T14:30:00.500") // "2024-03-15 14:30:00.5"
+ * @example formatSql("0000-01-01T00:00:00") // "" (year outside 0001–9999)
  * @example formatSql("invalid") // ""
  */
 export declare function formatSql(value: string): string;

package/dist/plain/format/formatSql.js

@@ -1,29 +1,38 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidDateTime } from "../validate/index.js";
 /**
- * Format a plain ISO 8601 datetime string as an ANSI SQL / ODBC datetime
- * literal — the `YYYY-MM-DD HH:MM:SS` form MySQL, SQLite, and standard SQL
- * `DATETIME`/`TIMESTAMP` columns (without a time zone) accept.
+ * Format a plain ISO 8601 datetime string as a SQL timestamp literal without a time zone — the
+ * `YYYY-MM-DD HH:MM:SS[.fff]` form of standard SQL `TIMESTAMP` and MySQL/SQLite `DATETIME`
+ * columns.
  *
- * - **Plain only.** SQL's offset-carrying `TIMESTAMPTZ` literal
- *   (`YYYY-MM-DD HH:MM:SS±HH:MM`, e.g. PostgreSQL) is out of scope — this
- *   targets the far more common tz-less `DATETIME` column shape. There is no
- *   zoned counterpart in this story.
- * - The only change from GMT's own ISO output is the separator: `T` becomes
- *   a single space. Fractional seconds, when present, are preserved as-is.
+ * - **Grammar:** SQL-92 §5.3 `<timestamp string>` and the ODBC `ts` escape, which `parseSql`
+ *   reads: the date, a single space, and the time with seconds always written.
+ * - A year outside SQL-92's `0001`–`9999` (Table 10) returns `""`: the literal has no sign and
+ *   no expanded year to write it with.
+ * - **Plain only.** SQL's offset-carrying `TIMESTAMP WITH TIME ZONE` literal
+ *   (`YYYY-MM-DD HH:MM:SS±HH:MM`, e.g. PostgreSQL) is out of scope — this targets the far more
+ *   common tz-less column shape. There is no zoned counterpart.
+ * - Fractional seconds are written as Temporal writes them: only the digits needed, with
+ *   trailing zeros dropped (`.500` → `.5`).
  *
  * @param value plain ISO 8601 datetime string (e.g. "2024-03-15T14:30:00")
- * @returns SQL datetime literal, or "" on invalid input
+ * @returns SQL timestamp literal, or "" on invalid input
  *
  * @example formatSql("2024-03-15T14:30:00") // "2024-03-15 14:30:00"
+ * @example formatSql("2024-03-15T14:30") // "2024-03-15 14:30:00"
  * @example formatSql("2024-03-15T14:30:00.500") // "2024-03-15 14:30:00.5"
+ * @example formatSql("0000-01-01T00:00:00") // "" (year outside 0001–9999)
  * @example formatSql("invalid") // ""
  */
 export function formatSql(value) {
     if (!isValidDateTime(value))
         return "";
     try {
-        return Temporal.PlainDateTime.from(value).toString().replace("T", " ");
+        const dateTime = Temporal.PlainDateTime.from(value);
+        // SQL-92 Table 10: YEAR 0001 to 9999.
+        if (dateTime.year < 1 || dateTime.year > 9999)
+            return "";
+        return dateTime.toString().replace("T", " ");
     }
     catch {
         return "";

package/dist/plain/format/formatTime.d.ts

@@ -1,17 +1,32 @@
+import type { DateTimeFormatOptions } from "../../types/index.js";
 /**
  * Return a localized string for a PlainTime ISO input using Intl options.
  *
- * - Uses Temporal.PlainTime.toLocaleString for formatting.
+ * - Formats as Temporal's ECMA-402 PlainTime format (`PlainTime#toLocaleString`) does, through
+ *   the runtime's `Intl.DateTimeFormat`. `era` and `timeZoneName` are ignored, so alone they get
+ *   the hour, minute and second defaults.
  * - Accepts optional BCP 47 locale and Intl.DateTimeFormatOptions.
- * - Returns "" for invalid input.
+ * - Returns "" for invalid input, for a `dateStyle` (with or without `timeStyle`) and for only
+ *   date fields, where `PlainTime#toLocaleString` throws a TypeError.
+ * - **Compatibility:** before 1.16.0 `era` or `timeZoneName` alone returned `""`, `era` beside a
+ *   time field added the era name, and a `dateStyle` beside `timeStyle` was ignored. Pass only
+ *   `timeStyle` to keep the styled text.
+ * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject rejects it. Any
+ *   other non-object — a string, a number, a boolean — formats with the defaults, as
+ *   `Intl.DateTimeFormat` does: CoerceOptionsToObject calls ToObject on it and the wrapper
+ *   carries no recognised option. Only `null` and `undefined` are special-cased.
  *
  * @param value ISO PlainTime string
- * @param locale optional BCP 47 locale identifier
+ * @param locale optional BCP 47 locale identifier, or a preference list of tags (ECMA-402)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized time string or "" on invalid input
  *
  * @example formatTime("14:30:00", "en-US", { timeStyle: "short" }) // "2:30 PM"
  * @example formatTime("14:30:00", "de-DE", { timeStyle: "short" }) // "14:30"
+ * @example formatTime("14:30:45", "en-US", { era: "long" }) // "2:30:45 PM"
+ * @example formatTime("14:30:45", "en-US", { dateStyle: "short", timeStyle: "short" }) // "" — a PlainTime has no date
+ * @example formatTime("14:30:45", "en-US", { timeStyle: "short" }) // "2:30 PM" — the pre-1.16.0 text
  * @example formatTime("invalid") // ""
+ * @example formatTime("14:30:45", ["fr-FR", "en-US"], { hour: "2-digit", minute: "2-digit" }) // "14:30"
  */
-export declare function formatTime(value: string, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+export declare function formatTime(value: string, locale?: string | string[], options?: DateTimeFormatOptions): string;

package/dist/plain/format/formatTime.js

@@ -1,29 +1,56 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { normalizeDateTime } from "../../internal/index.js";
+import { plainTimeFormatOptions } from "../../internal/plainFormatOptions.js";
 import { isValidTime } from "../validate/index.js";
 /**
  * Return a localized string for a PlainTime ISO input using Intl options.
  *
- * - Uses Temporal.PlainTime.toLocaleString for formatting.
+ * - Formats as Temporal's ECMA-402 PlainTime format (`PlainTime#toLocaleString`) does, through
+ *   the runtime's `Intl.DateTimeFormat`. `era` and `timeZoneName` are ignored, so alone they get
+ *   the hour, minute and second defaults.
  * - Accepts optional BCP 47 locale and Intl.DateTimeFormatOptions.
- * - Returns "" for invalid input.
+ * - Returns "" for invalid input, for a `dateStyle` (with or without `timeStyle`) and for only
+ *   date fields, where `PlainTime#toLocaleString` throws a TypeError.
+ * - **Compatibility:** before 1.16.0 `era` or `timeZoneName` alone returned `""`, `era` beside a
+ *   time field added the era name, and a `dateStyle` beside `timeStyle` was ignored. Pass only
+ *   `timeStyle` to keep the styled text.
+ * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject rejects it. Any
+ *   other non-object — a string, a number, a boolean — formats with the defaults, as
+ *   `Intl.DateTimeFormat` does: CoerceOptionsToObject calls ToObject on it and the wrapper
+ *   carries no recognised option. Only `null` and `undefined` are special-cased.
  *
  * @param value ISO PlainTime string
- * @param locale optional BCP 47 locale identifier
+ * @param locale optional BCP 47 locale identifier, or a preference list of tags (ECMA-402)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized time string or "" on invalid input
  *
  * @example formatTime("14:30:00", "en-US", { timeStyle: "short" }) // "2:30 PM"
  * @example formatTime("14:30:00", "de-DE", { timeStyle: "short" }) // "14:30"
+ * @example formatTime("14:30:45", "en-US", { era: "long" }) // "2:30:45 PM"
+ * @example formatTime("14:30:45", "en-US", { dateStyle: "short", timeStyle: "short" }) // "" — a PlainTime has no date
+ * @example formatTime("14:30:45", "en-US", { timeStyle: "short" }) // "2:30 PM" — the pre-1.16.0 text
  * @example formatTime("invalid") // ""
+ * @example formatTime("14:30:45", ["fr-FR", "en-US"], { hour: "2-digit", minute: "2-digit" }) // "14:30"
  */
 export function formatTime(value, locale, options) {
     if (!isValidTime(value)) {
         return "";
     }
     try {
-        const out = Temporal.PlainTime.from(value).toLocaleString(locale, options);
-        return normalizeDateTime(out);
+        // The runtime's Intl.DateTimeFormat formats the time at the UTC anchor on
+        // 1970-01-01 with the options Temporal's PlainTime format resolves to
+        // (CreateDateTimeFormat ~time~, ~time~). Constructing with the caller's
+        // options first surfaces the TypeError or RangeError Intl.DateTimeFormat
+        // raises for invalid ones.
+        new Intl.DateTimeFormat(locale, options);
+        const resolved = plainTimeFormatOptions(options ?? {});
+        if (resolved === null) {
+            return "";
+        }
+        const epochMilliseconds = Temporal.PlainDate.from("1970-01-01")
+            .toPlainDateTime(Temporal.PlainTime.from(value))
+            .toZonedDateTime("UTC").epochMilliseconds;
+        return normalizeDateTime(new Intl.DateTimeFormat(locale, resolved).format(epochMilliseconds));
     }
     catch {
         return "";

package/dist/plain/get/getNowUnit.d.ts

@@ -1,10 +1,12 @@
-import type { DateTimeUnit } from "../../types/index.js";
-type NowUnit = DateTimeUnit | "dayOfWeek";
+import type { NowUnit } from "../../types/index.js";
+export type { NowUnit };
 /**
  * Return the requested current unit value using the system timeZone.
  *
  * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
  * - Uses Temporal.Now.zonedDateTimeISO to get current time in system timezone.
+ * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
+ *   does; `"dayOfWeek"` has no plural.
  * - Returns "" when unit is invalid or system timezone is unavailable.
  *
  * @param unit unit to extract from current local time
@@ -21,7 +23,7 @@ type NowUnit = DateTimeUnit | "dayOfWeek";
  * @example getNowUnit("millisecond") // "000"
  * @example getNowUnit("microsecond") // "000"
  * @example getNowUnit("nanosecond") // "000"
+ * @example getNowUnit("hours") // "14", if the local time is 14:xx (plural unit name)
  * @example getNowUnit("invalid") // ""
  */
 export declare function getNowUnit(unit: NowUnit): string;
-export {};

package/dist/plain/get/getNowUnit.js

@@ -1,7 +1,9 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { zonedNowUnitValue } from "../../internal/zonedNowUnitValue.js";
 import { getSystemTimeZone } from "../../zoned/get/getSystemTimeZone.js";
 import { parseWeekFromDate } from "../parse/index.js";
 import { isValidDateTimeUnit } from "../validate/index.js";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
 function isValidPlainNowUnit(unit) {
     return isValidDateTimeUnit(unit) || ["dayOfWeek"].includes(unit);
 }
@@ -10,6 +12,8 @@ function isValidPlainNowUnit(unit) {
  *
  * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
  * - Uses Temporal.Now.zonedDateTimeISO to get current time in system timezone.
+ * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
+ *   does; `"dayOfWeek"` has no plural.
  * - Returns "" when unit is invalid or system timezone is unavailable.
  *
  * @param unit unit to extract from current local time
@@ -26,10 +30,15 @@ function isValidPlainNowUnit(unit) {
  * @example getNowUnit("millisecond") // "000"
  * @example getNowUnit("microsecond") // "000"
  * @example getNowUnit("nanosecond") // "000"
+ * @example getNowUnit("hours") // "14", if the local time is 14:xx (plural unit name)
  * @example getNowUnit("invalid") // ""
  */
 export function getNowUnit(unit) {
-    if (!isValidPlainNowUnit(String(unit ?? "")))
+    if (typeof unit !== "string") {
+        return "";
+    }
+    const resolvedUnit = resolveDateTimeUnit(unit);
+    if (!isValidPlainNowUnit(resolvedUnit))
         return "";
     const timeZone = getSystemTimeZone();
     if (!timeZone)
@@ -41,32 +50,8 @@ export function getNowUnit(unit) {
     catch {
         return "";
     }
-    switch (unit) {
-        case "year":
-            return now.year.toString();
-        case "month":
-            return now.month.toString().padStart(2, "0");
-        case "week": {
-            const w = parseWeekFromDate(now.toPlainDate().toString());
-            return w === null ? "" : w.toString();
-        }
-        case "day":
-            return now.day.toString().padStart(2, "0");
-        case "dayOfWeek":
-            return now.dayOfWeek.toString();
-        case "hour":
-            return now.hour.toString().padStart(2, "0");
-        case "minute":
-            return now.minute.toString().padStart(2, "0");
-        case "second":
-            return now.second.toString().padStart(2, "0");
-        case "millisecond":
-            return now.millisecond.toString().padStart(3, "0");
-        case "microsecond":
-            return (now.microsecond ?? 0).toString().padStart(3, "0");
-        case "nanosecond":
-            return (now.nanosecond ?? 0).toString().padStart(3, "0");
-        default:
-            return "";
-    }
+    return zonedNowUnitValue(now, resolvedUnit, (zdt) => {
+        const w = parseWeekFromDate(zdt.toPlainDate().toString());
+        return w === null ? "" : w.toString();
+    });
 }

package/dist/plain/index.js

@@ -1,4 +1,4 @@
-// Re-export all Temporal polyfill functionality for plain DateTime operations
+// Re-export the Temporal polyfill (`Temporal`, `Intl`, `toTemporalInstant`) so every namespace subpath offers it
 export * from "@js-temporal/polyfill";
 export * from "./calculate/index.js";
 export * from "./chop/index.js";

package/dist/plain/interval/intervalAbutsDate.d.ts

@@ -1,15 +1,20 @@
 /**
- * Return true when two date intervals are exactly adjacent — one's end equals the other's start
- * with zero gap and zero overlap.
+ * Return true when two half-open date intervals `[aStart, aEnd)` and `[bStart, bEnd)` are exactly
+ * adjacent — one ends where the other starts, so they share nothing and leave no gap.
  *
+ * - Half-open: an interval holds every `t` with `start <= t < end`, so an interval's `end` is the
+ *   first value after it. Returns `true` when `aEnd === bStart` or `bEnd === aStart` (Allen's
+ *   "meets"). There is no one-day step: a one-day gap is a gap.
+ * - An empty interval (`start === end`) abuts nothing.
  * - Uses `Temporal.PlainDate.compare` for comparison.
- * - Returns `true` when `aEnd + 1 day === bStart` or `bEnd + 1 day === aStart`.
  * - Returns `false` when intervals overlap, are disjoint with a gap, or are invalid.
  * - Returns `false` on invalid input (wrong type, malformed strings).
- * - Accepts GMT calendar-annotated PlainDate strings (as produced by `convertDateToCalendar`) —
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings (as produced by `convertDateToCalendar`) —
  *   E5 (issue #78). Comparison is by calendar-independent ordering (`Temporal.PlainDate.compare`
  *   ignores calendar), so the four endpoints may carry different or no calendar tags — E5
  *   decision of record D4 (ordering-only functions accept mixed calendars).
+ * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical
+ *   calendar ids); see `isValidCalendarDate`.
  *
  * @param aStart ISO 8601 date string for the first interval start, optionally calendar-annotated
  * @param aEnd ISO 8601 date string for the first interval end, optionally calendar-annotated
@@ -17,9 +22,9 @@
  * @param bEnd ISO 8601 date string for the second interval end, optionally calendar-annotated
  * @returns true if intervals are exactly adjacent, or false on invalid input
  *
- * @example intervalAbutsDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31") // true
- * @example intervalAbutsDate("2024-07-01", "2024-12-31", "2024-01-01", "2024-06-30") // true
- * @example intervalAbutsDate("2024-01-01", "2024-06-30", "2024-07-02", "2024-12-31") // false (gap)
+ * @example intervalAbutsDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31") // true
+ * @example intervalAbutsDate("2024-06-30", "2024-12-31", "2024-01-01", "2024-06-30") // true
+ * @example intervalAbutsDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31") // false ([01-01, 06-30) ends before 06-30)
  * @example intervalAbutsDate("2024-01-01", "2024-07-01", "2024-06-30", "2024-12-31") // false (overlap)
  * @example intervalAbutsDate("invalid", "2024-06-30", "2024-07-01", "2024-12-31") // false
  */