@northguild/gmt 1.17.0 → 1.19.0

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

@@ -5,8 +5,7 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  * - This is GMT's substitute for a token formatter (Luxon `toFormat`, date-fns
  *   `format`). A token pattern hard-codes field order and ships US ordering to
  *   every locale; `formatToParts` gives the caller full control over presentation
- *   while the *locale* keeps control of order. See Decision 1 in
- *   `context/roadmap/issues/J.md`.
+ *   while the *locale* keeps control of order.
  * - Each part is `{ type, value }` where `type` is one of:
  *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
  *   `"literal"`.
@@ -22,6 +21,9 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  *   ignored. With both `dateStyle` and `timeStyle` the parts keep the date style and drop the
  *   `timeStyle` (the `Intl.DateTimeFormat` entry point, required ~any~), whereas the text sibling
  *   `formatDate` returns `""` (`PlainDate#toLocaleString`, required ~date~, is a TypeError).
+ * - The `formatZonedToParts` example below writes the literal before the day period as
+ *   `"\u202f"`, U+202F NARROW NO-BREAK SPACE, which Node 22 and 24 return; Node 26 returns an
+ *   ordinary space there (see `formatZonedToParts`).
  * - Returns `[]` for invalid input.
  * - **Compatibility:** before 1.16.0 time options leaked a UTC midnight and a `"UTC"` zone name
  *   into the parts. `formatZonedToParts` on the date at midnight UTC returns those parts.
@@ -44,6 +46,15 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  * @example formatDateToParts("2024-02-03", ["fr-FR", "en-US"]) // [{ type: "day", value: "03" }, { type: "literal", value: "/" }, …]
  */
 export declare function formatDateToParts(value: string, locale?: string | string[], options?: DateTimeFormatOptions): Array<{
+    /**
+     * The kind of part, named as ECMA-402 `Intl.DateTimeFormat.prototype.formatToParts` names it: a
+     * field such as `"year"`, `"month"` or `"day"`, or `"literal"` for the separator text between
+     * fields.
+     */
     type: string;
+    /**
+     * The text of the part in the requested locale, exactly as the formatter wrote it. Joining every
+     * `value` in array order gives the whole formatted text.
+     */
     value: string;
 }>;

package/dist/plain/format/formatDateToParts.js

@@ -1,14 +1,14 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { plainDateFormatOptions } from "../../internal/plainFormatOptions.js";
 import { isValidDate } from "../validate/index.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
 /**
  * Return the locale-formatted parts of a PlainDate.
  *
  * - This is GMT's substitute for a token formatter (Luxon `toFormat`, date-fns
  *   `format`). A token pattern hard-codes field order and ships US ordering to
  *   every locale; `formatToParts` gives the caller full control over presentation
- *   while the *locale* keeps control of order. See Decision 1 in
- *   `context/roadmap/issues/J.md`.
+ *   while the *locale* keeps control of order.
  * - Each part is `{ type, value }` where `type` is one of:
  *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
  *   `"literal"`.
@@ -24,6 +24,9 @@ import { isValidDate } from "../validate/index.js";
  *   ignored. With both `dateStyle` and `timeStyle` the parts keep the date style and drop the
  *   `timeStyle` (the `Intl.DateTimeFormat` entry point, required ~any~), whereas the text sibling
  *   `formatDate` returns `""` (`PlainDate#toLocaleString`, required ~date~, is a TypeError).
+ * - The `formatZonedToParts` example below writes the literal before the day period as
+ *   `"\u202f"`, U+202F NARROW NO-BREAK SPACE, which Node 22 and 24 return; Node 26 returns an
+ *   ordinary space there (see `formatZonedToParts`).
  * - Returns `[]` for invalid input.
  * - **Compatibility:** before 1.16.0 time options leaked a UTC midnight and a `"UTC"` zone name
  *   into the parts. `formatZonedToParts` on the date at midnight UTC returns those parts.
@@ -56,8 +59,9 @@ export function formatDateToParts(value, locale, options) {
         // PlainDate format may contain, so no time or zone field can appear.
         // 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 = plainDateFormatOptions(options ?? {});
+        const read = readDateTimeFormatOptions(options);
+        new Intl.DateTimeFormat(locale, read);
+        const resolved = plainDateFormatOptions(read);
         if (resolved === null) {
             return [];
         }

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

@@ -1,19 +1,32 @@
 import type { RelativeDateUnit, RelativeTimeFormatOptions } from "../../types/index.js";
+/**
+ * Options for `formatRelativeDate`: the reference date, the display unit, the rounding and the
+ * wording.
+ */
 export interface FormatRelativeDateOptions extends RelativeTimeFormatOptions {
-    largestUnit?: RelativeDateUnit;
+    /**
+     * The unit the distance is written in, whatever its size: `"day"`, `"week"`, `"month"` or
+     * `"year"`, singular or plural. Any other value returns `""`, a time unit such as `"hour"`
+     * included: a date has no time, and Temporal throws RangeError for a unit outside the units of
+     * the type. Omitted, the unit is picked from the distance: day under 7 days, week under 28,
+     * month under 365 and year beyond.
+     *
+     * @defaultValue None. The unit is picked from the distance.
+     */
+    largestUnit?: RelativeDateUnit | `${RelativeDateUnit}s`;
 }
 /**
  * Format the relative time between a plain date and a reference date.
  *
  * - Auto-picks the display unit (day/week/month/year) based on the distance, unless
  *   `largestUnit` forces one.
- * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `largestUnit` is one of those four units, singular or plural. Any other value returns `""`.
  * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
  *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO date string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
+ * @param options How the distance is measured, rounded and worded
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeDate("2026-01-15", "en-US", { reference: "2026-04-15" }) // "3 months ago"

package/dist/plain/format/formatRelativeDate.js

@@ -1,6 +1,16 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { durationTotal, normalizeDateTime, resolveRelativeRounding, } from "../../internal/index.js";
+import { durationTotal } from "../../internal/index.js";
+import { formatRelativeAmount } from "../../internal/formatRelativeDuration.js";
 import { isValidDate } from "../validate/index.js";
+import { resolveRelativeUnit } from "../../internal/resolveRelativeUnit.js";
+import { isObject } from "../../internal/isObject.js";
+// Temporal's date unit group: the units a PlainDate difference may be written in.
+const DATE_UNITS = [
+    "year",
+    "month",
+    "week",
+    "day",
+];
 const AUTO_UNITS = [
     { unit: "day", maxDays: 7 },
     { unit: "week", maxDays: 28 },
@@ -12,13 +22,13 @@ const AUTO_UNITS = [
  *
  * - Auto-picks the display unit (day/week/month/year) based on the distance, unless
  *   `largestUnit` forces one.
- * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `largestUnit` is one of those four units, singular or plural. Any other value returns `""`.
  * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
  *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO date string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
+ * @param options How the distance is measured, rounded and worded
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeDate("2026-01-15", "en-US", { reference: "2026-04-15" }) // "3 months ago"
@@ -31,34 +41,36 @@ export function formatRelativeDate(value, locale, options = {}) {
     try {
         // Temporal GetOptionsObject: options must be an object or omitted; null and other primitives are
         // invalid input.
-        if (options === null || typeof options !== "object")
+        if (!isObject(options))
             return "";
         if (!isValidDate(value))
             return "";
-        if (options.reference !== undefined && !isValidDate(options.reference))
+        // Each option is read once (GetOption).
+        const referenceOption = options.reference;
+        if (referenceOption !== undefined && !isValidDate(referenceOption))
             return "";
         try {
+            const forcedUnit = resolveRelativeUnit(options.largestUnit, DATE_UNITS);
+            const roundingMethod = options.roundingMethod;
             const target = Temporal.PlainDate.from(value);
-            const reference = options.reference
-                ? Temporal.PlainDate.from(options.reference)
+            const reference = referenceOption
+                ? Temporal.PlainDate.from(referenceOption)
                 : Temporal.Now.plainDateISO();
             const diff = target.since(reference);
             const absDays = Math.abs(diff.total("day"));
-            const unit = options.largestUnit === undefined
+            const unit = forcedUnit === undefined
                 ? (AUTO_UNITS.find((t) => absDays < t.maxDays)?.unit ?? "year")
-                : options.largestUnit;
-            let amount;
+                : forcedUnit;
+            let total;
             try {
-                amount = resolveRelativeRounding(diff.total(unit), options.roundingMethod);
+                total = diff.total(unit);
             }
             catch {
                 // month/year are calendrical and need a relativeTo anchor
-                amount = resolveRelativeRounding(durationTotal(diff, unit, reference), options.roundingMethod);
+                total = durationTotal(diff, unit, reference);
             }
-            return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
-                numeric: options.numeric === undefined ? "auto" : options.numeric,
-                style: options.style === undefined ? "long" : options.style,
-            }).format(amount, unit));
+            // Outside the retry: an invalid roundingMethod throws once, straight to the sentinel.
+            return formatRelativeAmount(total, unit, locale, options, roundingMethod);
         }
         catch {
             return "";

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

@@ -1,6 +1,18 @@
 import type { RelativeDateTimeUnit, RelativeTimeFormatOptions } from "../../types/index.js";
+/**
+ * Options for `formatRelativeDateTime`: the reference date-time, the display unit, the rounding
+ * and the wording.
+ */
 export interface FormatRelativeDateTimeOptions extends RelativeTimeFormatOptions {
-    largestUnit?: RelativeDateTimeUnit;
+    /**
+     * The unit the distance is written in, whatever its size: `"second"`, `"minute"`, `"hour"`,
+     * `"day"`, `"week"`, `"month"` or `"year"`, singular or plural. Any other value returns `""`.
+     * Omitted, the unit is picked from the distance: second under a minute, minute under an hour,
+     * hour under a day, day under 7 days, week under 28, month under 365 and year beyond.
+     *
+     * @defaultValue None. The unit is picked from the distance.
+     */
+    largestUnit?: RelativeDateTimeUnit | `${RelativeDateTimeUnit}s`;
 }
 /**
  * Format the relative time between a plain date-time and a reference date-time.
@@ -11,13 +23,14 @@ export interface FormatRelativeDateTimeOptions extends RelativeTimeFormatOptions
  *   "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.
+ * - `largestUnit` is one of the seven units from `"second"` to `"year"`, singular or plural. Any
+ *   other value returns `""`.
  * - `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, or a preference list of tags (ECMA-402)
- * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
+ * @param options How the distance is measured, rounded and worded
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeDateTime("2026-03-17T09:00:00", "en-GB", { style: "long", reference: "2026-03-17T06:00:00" }) // "in 3 hours"

package/dist/plain/format/formatRelativeDateTime.js

@@ -3,6 +3,7 @@ import { Temporal } from "@js-temporal/polyfill";
 import { durationTotal } from "../../internal/index.js";
 import { formatRelativeDuration } from "../../internal/formatRelativeDuration.js";
 import { isValidDateTime } from "../validate/index.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Format the relative time between a plain date-time and a reference date-time.
  *
@@ -12,13 +13,14 @@ import { isValidDateTime } from "../validate/index.js";
  *   "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.
+ * - `largestUnit` is one of the seven units from `"second"` to `"year"`, singular or plural. Any
+ *   other value returns `""`.
  * - `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, or a preference list of tags (ECMA-402)
- * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
+ * @param options How the distance is measured, rounded and worded
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeDateTime("2026-03-17T09:00:00", "en-GB", { style: "long", reference: "2026-03-17T06:00:00" }) // "in 3 hours"
@@ -32,16 +34,18 @@ export function formatRelativeDateTime(value, locale, options = {}) {
     try {
         // Temporal GetOptionsObject: options must be an object or omitted; null and other primitives are
         // invalid input.
-        if (options === null || typeof options !== "object")
+        if (!isObject(options))
             return "";
         if (!isValidDateTime(value))
             return "";
-        if (options.reference !== undefined && !isValidDateTime(options.reference))
+        // Each option is read once (GetOption).
+        const referenceOption = options.reference;
+        if (referenceOption !== undefined && !isValidDateTime(referenceOption))
             return "";
         try {
             const target = Temporal.PlainDateTime.from(value);
-            const reference = options.reference
-                ? Temporal.PlainDateTime.from(options.reference)
+            const reference = referenceOption
+                ? Temporal.PlainDateTime.from(referenceOption)
                 : Temporal.Now.plainDateTimeISO();
             const diff = target.since(reference);
             // month/year are calendrical — relativeTo needs a PlainDate

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

@@ -1,19 +1,32 @@
 import type { RelativeTimeFormatOptions, RelativeTimeUnit } from "../../types/index.js";
+/**
+ * Options for `formatRelativeTime`: the reference time, the display unit, the rounding and the
+ * wording.
+ */
 export interface FormatRelativeTimeOptions extends RelativeTimeFormatOptions {
-    largestUnit?: RelativeTimeUnit;
+    /**
+     * The unit the distance is written in, whatever its size: `"second"`, `"minute"` or `"hour"`,
+     * singular or plural. Any other value returns `""`, a date unit such as `"day"` included: a time
+     * has no date, and Temporal throws RangeError for a unit outside the units of the type. Omitted,
+     * the unit is picked from the distance: second under a minute, minute under an hour and hour
+     * beyond.
+     *
+     * @defaultValue None. The unit is picked from the distance.
+     */
+    largestUnit?: RelativeTimeUnit | `${RelativeTimeUnit}s`;
 }
 /**
  * Format the relative time between a plain time and a reference time.
  *
  * - 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.
+ * - `largestUnit` is one of those three units, singular or plural. Any other value returns `""`.
  * - `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, or a preference list of tags (ECMA-402)
- * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
+ * @param options How the distance is measured, rounded and worded
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeTime("14:30:00", "en-US", { style: "short", reference: "16:30:00" }) // "2 hr. ago"

package/dist/plain/format/formatRelativeTime.js

@@ -1,6 +1,15 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { normalizeDateTime, resolveRelativeRounding } from "../../internal/index.js";
+import { formatRelativeAmount } from "../../internal/formatRelativeDuration.js";
 import { isValidTime } from "../validate/index.js";
+import { resolveRelativeUnit } from "../../internal/resolveRelativeUnit.js";
+import { isObject } from "../../internal/isObject.js";
+// Temporal's time unit group down to the second: the units a PlainTime difference may be written
+// in, less the sub-second units, which Intl.RelativeTimeFormat does not have.
+const TIME_UNITS = [
+    "hour",
+    "minute",
+    "second",
+];
 const AUTO_UNITS = [
     { unit: "second", maxSeconds: 60 },
     { unit: "minute", maxSeconds: 3_600 },
@@ -11,13 +20,13 @@ 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.
+ * - `largestUnit` is one of those three units, singular or plural. Any other value returns `""`.
  * - `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, or a preference list of tags (ECMA-402)
- * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
+ * @param options How the distance is measured, rounded and worded
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeTime("14:30:00", "en-US", { style: "short", reference: "16:30:00" }) // "2 hr. ago"
@@ -30,27 +39,27 @@ export function formatRelativeTime(value, locale, options = {}) {
     try {
         // Temporal GetOptionsObject: options must be an object or omitted; null and other primitives are
         // invalid input.
-        if (options === null || typeof options !== "object")
+        if (!isObject(options))
             return "";
         if (!isValidTime(value))
             return "";
-        if (options.reference !== undefined && !isValidTime(options.reference))
+        // Each option is read once (GetOption).
+        const referenceOption = options.reference;
+        if (referenceOption !== undefined && !isValidTime(referenceOption))
             return "";
         try {
+            const forcedUnit = resolveRelativeUnit(options.largestUnit, TIME_UNITS);
+            const roundingMethod = options.roundingMethod;
             const target = Temporal.PlainTime.from(value);
-            const reference = options.reference
-                ? Temporal.PlainTime.from(options.reference)
+            const reference = referenceOption
+                ? Temporal.PlainTime.from(referenceOption)
                 : Temporal.Now.plainTimeISO();
             const diff = target.since(reference);
             const absSeconds = Math.abs(diff.total("second"));
-            const unit = options.largestUnit === undefined
+            const unit = forcedUnit === 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));
+                : forcedUnit;
+            return formatRelativeAmount(diff.total(unit), unit, locale, options, roundingMethod);
         }
         catch {
             return "";

package/dist/plain/format/{formatSql.d.ts → formatSqlDateTime.d.ts}

@@ -3,7 +3,7 @@
  * `YYYY-MM-DD HH:MM:SS[.fff]` form of standard SQL `TIMESTAMP` and MySQL/SQLite `DATETIME`
  * columns.
  *
- * - **Grammar:** SQL-92 §5.3 `<timestamp string>` and the ODBC `ts` escape, which `parseSql`
+ * - **Grammar:** SQL-92 §5.3 `<timestamp string>` and the ODBC `ts` escape, which `parseSqlDateTime`
  *   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.
@@ -16,10 +16,10 @@
  * @param value plain ISO 8601 datetime string (e.g. "2024-03-15T14:30:00")
  * @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") // ""
+ * @example formatSqlDateTime("2024-03-15T14:30:00") // "2024-03-15 14:30:00"
+ * @example formatSqlDateTime("2024-03-15T14:30") // "2024-03-15 14:30:00"
+ * @example formatSqlDateTime("2024-03-15T14:30:00.500") // "2024-03-15 14:30:00.5"
+ * @example formatSqlDateTime("0000-01-01T00:00:00") // "" (year outside 0001–9999)
+ * @example formatSqlDateTime("invalid") // ""
  */
-export declare function formatSql(value: string): string;
+export declare function formatSqlDateTime(value: string): string;

package/dist/plain/format/{formatSql.js → formatSqlDateTime.js}

@@ -5,7 +5,7 @@ import { isValidDateTime } from "../validate/index.js";
  * `YYYY-MM-DD HH:MM:SS[.fff]` form of standard SQL `TIMESTAMP` and MySQL/SQLite `DATETIME`
  * columns.
  *
- * - **Grammar:** SQL-92 §5.3 `<timestamp string>` and the ODBC `ts` escape, which `parseSql`
+ * - **Grammar:** SQL-92 §5.3 `<timestamp string>` and the ODBC `ts` escape, which `parseSqlDateTime`
  *   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.
@@ -18,13 +18,13 @@ import { isValidDateTime } from "../validate/index.js";
  * @param value plain ISO 8601 datetime string (e.g. "2024-03-15T14:30:00")
  * @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") // ""
+ * @example formatSqlDateTime("2024-03-15T14:30:00") // "2024-03-15 14:30:00"
+ * @example formatSqlDateTime("2024-03-15T14:30") // "2024-03-15 14:30:00"
+ * @example formatSqlDateTime("2024-03-15T14:30:00.500") // "2024-03-15 14:30:00.5"
+ * @example formatSqlDateTime("0000-01-01T00:00:00") // "" (year outside 0001–9999)
+ * @example formatSqlDateTime("invalid") // ""
  */
-export function formatSql(value) {
+export function formatSqlDateTime(value) {
     if (!isValidDateTime(value))
         return "";
     try {

package/dist/plain/format/formatTime.js

@@ -2,6 +2,7 @@ import { Temporal } from "@js-temporal/polyfill";
 import { normalizeDateTime } from "../../internal/index.js";
 import { plainTimeFormatOptions } from "../../internal/plainFormatOptions.js";
 import { isValidTime } from "../validate/index.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
 /**
  * Return a localized string for a PlainTime ISO input using Intl options.
  *
@@ -42,8 +43,9 @@ export function formatTime(value, locale, options) {
         // (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 ?? {});
+        const read = readDateTimeFormatOptions(options);
+        new Intl.DateTimeFormat(locale, read);
+        const resolved = plainTimeFormatOptions(read);
         if (resolved === null) {
             return "";
         }

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

@@ -8,5 +8,5 @@ export * from "./formatDateToParts.js";
 export * from "./formatRelativeDate.js";
 export * from "./formatRelativeDateTime.js";
 export * from "./formatRelativeTime.js";
-export * from "./formatSql.js";
+export * from "./formatSqlDateTime.js";
 export * from "./formatTime.js";

package/dist/plain/format/index.js

@@ -8,5 +8,5 @@ export * from "./formatDateToParts.js";
 export * from "./formatRelativeDate.js";
 export * from "./formatRelativeDateTime.js";
 export * from "./formatRelativeTime.js";
-export * from "./formatSql.js";
+export * from "./formatSqlDateTime.js";
 export * from "./formatTime.js";

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

@@ -8,6 +8,8 @@ export type { NowUnit };
  * - `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.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param unit unit to extract from current local time
  * @returns string representation of the requested unit or "" on invalid

package/dist/plain/get/getNowUnit.js

@@ -15,6 +15,8 @@ function isValidPlainNowUnit(unit) {
  * - `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.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param unit unit to extract from current local time
  * @returns string representation of the requested unit or "" on invalid

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

@@ -3,6 +3,8 @@
  *
  * - Uses Temporal.Now.zonedDateTimeISO to get current year in system timezone.
  * - Returns zero-padded string (e.g., "2024").
+ * - A year outside 0000–9999 is written with a sign and six digits (`+010000`, `-000005`), as
+ *   Temporal writes it at the head of a date.
  * - Returns "" when system timezone is unavailable.
  *
  * @returns current year string (zero-padded) or "" on invalid

package/dist/plain/get/getYear.js

@@ -1,10 +1,13 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { getSystemTimeZone } from "../../zoned/get/getSystemTimeZone.js";
+import { isoYearString } from "../../internal/isoYearString.js";
 /**
  * Return the current year as a zero-padded string in the system timeZone.
  *
  * - Uses Temporal.Now.zonedDateTimeISO to get current year in system timezone.
  * - Returns zero-padded string (e.g., "2024").
+ * - A year outside 0000–9999 is written with a sign and six digits (`+010000`, `-000005`), as
+ *   Temporal writes it at the head of a date.
  * - Returns "" when system timezone is unavailable.
  *
  * @returns current year string (zero-padded) or "" on invalid
@@ -17,9 +20,7 @@ export function getYear() {
     if (!timeZone)
         return "";
     try {
-        return Temporal.Now.zonedDateTimeISO(timeZone)
-            .year.toString()
-            .padStart(4, "0");
+        return isoYearString(Temporal.Now.zonedDateTimeISO(timeZone).year);
     }
     catch {
         return "";

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

@@ -32,6 +32,15 @@
  * @example intervalDifferenceDate("invalid", "2024-12-31", "2024-06-01", "2024-07-01") // []
  */
 export declare function intervalDifferenceDate(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    /**
+     * The date the interval begins on, as an ISO 8601 date (`YYYY-MM-DD`). It keeps a calendar
+     * annotation such as `[u-ca=hebrew]` when the inputs carry one.
+     */
     start: string;
+    /**
+     * The first date after the interval, in the same format as `start`. It is exclusive: the interval
+     * holds everything from `start` up to but not including this value. It is always later than
+     * `start`.
+     */
     end: string;
 }>;

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

@@ -25,6 +25,15 @@
  * @example intervalDifferenceDateTime("invalid", "2024-12-31T17:00:00", "2024-06-01T12:00:00", "2024-07-01T13:00:00") // []
  */
 export declare function intervalDifferenceDateTime(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    /**
+     * The date-time the interval begins at, as an ISO 8601 date-time string with no offset or time
+     * zone.
+     */
     start: string;
+    /**
+     * The first date-time after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: string;
 }>;

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

@@ -27,6 +27,15 @@
  * @example intervalDifferenceTime("invalid", "17:00:00", "12:00:00", "13:00:00") // []
  */
 export declare function intervalDifferenceTime(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    /**
+     * The clock time the interval begins at, as an ISO 8601 time string with no date, offset or time
+     * zone.
+     */
     start: string;
+    /**
+     * The first clock time after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: string;
 }>;