@trackunit/date-and-time-utils 1.14.4-alpha-d0f54ff2967.0 → 1.14.5

package/index.cjs.js

@@ -911,6 +911,76 @@ const isEqualUtil = (from, to) => {
         .round({ smallestUnit: "seconds" })
         .equals(toZonedDateTimeUtil(to).round({ smallestUnit: "seconds" }));
 };
+const localeScriptCache = new Map();
+const localeScript = (locale) => {
+    const key = locale ?? "";
+    if (localeScriptCache.has(key))
+        return localeScriptCache.get(key);
+    let script;
+    try {
+        script = new Intl.Locale(locale ?? new Intl.NumberFormat().resolvedOptions().locale).maximize().script;
+    }
+    catch {
+        script = undefined;
+    }
+    localeScriptCache.set(key, script);
+    return script;
+};
+/**
+ * True when `Intl.NumberFormat` narrow for `locale`/`unit` renders in Latin script on a
+ * non-Latin-script locale — the symptom of a missing `units-narrow` slot silently
+ * inheriting from CLDR `root`. Detected directly on the formatter's output; this avoids
+ * any dependency on the ECMA-402 `DefaultLocale`, which would be the case if we tried to
+ * address `root` through `Intl` (there is no way: `Intl.NumberFormat("root")` throws, and
+ * `Intl.NumberFormat("und")` resolves via `LookupMatcher` to the runtime's default
+ * locale, not to CLDR root).
+ *
+ * Latin-script locales short-circuit to `false`: even if their narrow slot is empty and
+ * inherits from root, the fallback is still in the right script, so the output is not
+ * meaningfully delocalised.
+ */
+const narrowUnitIsDelocalisedCache = new Map();
+const narrowUnitIsDelocalised = (locale, unit) => {
+    const key = (locale ?? "") + "|" + unit;
+    const cached = narrowUnitIsDelocalisedCache.get(key);
+    if (cached !== undefined)
+        return cached;
+    if (localeScript(locale) === "Latn") {
+        narrowUnitIsDelocalisedCache.set(key, false);
+        return false;
+    }
+    const out = new Intl.NumberFormat(locale, { style: "unit", unit, unitDisplay: "narrow" }).format(1);
+    const delocalised = /[A-Za-z]/.test(out);
+    narrowUnitIsDelocalisedCache.set(key, delocalised);
+    return delocalised;
+};
+/**
+ * Formats a signed unit value using the Trackunit style axis.
+ * - `narrow-compact` past values → `Intl.NumberFormat` unit narrow (no affix), but only if
+ *   the locale actually has native narrow data (i.e. not a silent root/Latin fallback);
+ *   otherwise routes through `Intl.RelativeTimeFormat` narrow to preserve script.
+ * - `narrow-compact` future values → `Intl.RelativeTimeFormat` narrow (retains the CLDR-native
+ *   leading affix — the API has no way to strip it).
+ * - No style specified → `Intl.RelativeTimeFormat` long (the default).
+ */
+const formatRelativeUnit = (value, unit, locale, style) => {
+    if (style === "narrow-compact") {
+        if (value <= 0) {
+            const singularUnit = unit.endsWith("s") ? unit.slice(0, -1) : unit;
+            if (!narrowUnitIsDelocalised(locale, singularUnit)) {
+                return new Intl.NumberFormat(locale, {
+                    style: "unit",
+                    unit: singularUnit,
+                    unitDisplay: "narrow",
+                }).format(Math.abs(value));
+            }
+            // Non-Latin script whose units-narrow output would render in Latin (CLDR root
+            // fallback) — route through `RelativeTimeFormat` narrow to preserve script.
+        }
+        return getRelativeTimeFormat(locale, "narrow").format(value, unit);
+    }
+    return getRelativeTimeFormat(locale).format(value, unit);
+};
 /**
  * Calculates the time duration between two TemporalDate objects and returns a human-readable string representation of the duration.
  *
@@ -918,6 +988,12 @@ const isEqualUtil = (from, to) => {
  * @param {TemporalDate} to - The ending date.
  * @param {string} [timeZone] - The time zone to use for the calculations. Defaults to the local time zone.
  * @param {string} [locale] - The locale to use for formatting the duration. Defaults to the user's locale.
+ * @param {TuRelativeTimeStyle} [style] - Optional width override. Pass `"narrow-compact"` to render
+ *   past values without any past-tense affix (`"2d"` in en, `"2j"` in fr) while future values retain
+ *   the CLDR-native leading affix (`"in 2d"` in en). Non-Latin-script locales without native CLDR
+ *   narrow data fall back to `RelativeTimeFormat` narrow to preserve script, which keeps the affix
+ *   (`"2日前"` in ja) — see {@link TuRelativeTimeStyle} for the CLDR-table-sourcing details.
+ *   Omit `style` to get the default long form (`"2 days ago"` in en, `"vor 2 Tagen"` in de).
  * @returns {string|Error} - The formatted duration string or an Error object if the duration is not valid.
  * @example
  * const startDate = "2023-05-1010:30:00.000Z"
@@ -937,8 +1013,14 @@ const isEqualUtil = (from, to) => {
  *
  * const result = timeSinceAuto(startDate, endDate, 'America/New_York', 'en-US');
  * Output:  "1 year ago"
+ * @example
+ * const startDate = "2023-05-10"
+ * const endDate = "2023-05-18"
+ *
+ * const result = timeSinceAuto(startDate, endDate, 'America/New_York', 'en-US', 'narrow-compact');
+ * Output:  "8d"
  */
-const timeSinceAuto = (from, to, timeZone, locale) => {
+const timeSinceAuto = (from, to, timeZone, locale, style) => {
     let since;
     try {
         since = toZonedDateTimeUtil(from, timeZone)
@@ -955,25 +1037,25 @@ const timeSinceAuto = (from, to, timeZone, locale) => {
     }
     const duration = polyfill.Temporal.Duration.from(since);
     if (duration.blank) {
-        return getRelativeTimeFormat(locale).format(-1, "seconds");
+        return formatRelativeUnit(-1, "seconds", locale, style);
     }
     if (duration.years !== 0) {
-        return getRelativeTimeFormat(locale).format(duration.years, "years");
+        return formatRelativeUnit(duration.years, "years", locale, style);
     }
     if (duration.months !== 0) {
-        return getRelativeTimeFormat(locale).format(duration.months, "months");
+        return formatRelativeUnit(duration.months, "months", locale, style);
     }
     if (duration.days !== 0) {
-        return getRelativeTimeFormat(locale).format(duration.days, "days");
+        return formatRelativeUnit(duration.days, "days", locale, style);
     }
     if (duration.hours !== 0) {
-        return getRelativeTimeFormat(locale).format(duration.hours, "hours");
+        return formatRelativeUnit(duration.hours, "hours", locale, style);
     }
     if (duration.minutes !== 0) {
-        return getRelativeTimeFormat(locale).format(duration.minutes, "minutes");
+        return formatRelativeUnit(duration.minutes, "minutes", locale, style);
     }
     if (duration.seconds !== 0) {
-        return getRelativeTimeFormat(locale).format(duration.seconds, "seconds");
+        return formatRelativeUnit(duration.seconds, "seconds", locale, style);
     }
     // eslint-disable-next-line no-console
     console.warn(new Error("Not a valid duration", { cause: duration }));
@@ -994,7 +1076,7 @@ const timeSinceAuto = (from, to, timeZone, locale) => {
  * const result = timeSinceInSeconds(startDate, endDate, 'America/New_York', 'en-US');
  * Output: "480 seconds ago"
  */
-const timeSinceInSeconds = (from, to, timeZone, locale) => {
+const timeSinceInSeconds = (from, to, timeZone, locale, style) => {
     let since = new polyfill.Temporal.Duration();
     try {
         since = toZonedDateTimeUtil(from, timeZone).since(toZonedDateTimeUtil(to, timeZone), {
@@ -1006,7 +1088,7 @@ const timeSinceInSeconds = (from, to, timeZone, locale) => {
         console.warn("Error: ", error);
     }
     const duration = polyfill.Temporal.Duration.from(since);
-    return getRelativeTimeFormat(locale).format(duration.seconds, "seconds");
+    return formatRelativeUnit(duration.seconds, "seconds", locale, style);
 };
 /**
  * Calculates the time duration between two TemporalDate objects and returns the duration in minutes as a formatted string.
@@ -1023,7 +1105,7 @@ const timeSinceInSeconds = (from, to, timeZone, locale) => {
  * const result = timeSinceInSeconds(startDate, endDate, 'America/New_York', 'en-US');
  * Output: "8 minutes ago"
  */
-const timeSinceInMinutes = (from, to, timeZone, locale) => {
+const timeSinceInMinutes = (from, to, timeZone, locale, style) => {
     let since = new polyfill.Temporal.Duration();
     try {
         since = toZonedDateTimeUtil(from, timeZone).since(toZonedDateTimeUtil(to, timeZone), {
@@ -1035,7 +1117,7 @@ const timeSinceInMinutes = (from, to, timeZone, locale) => {
         console.warn("Error: ", error);
     }
     const duration = polyfill.Temporal.Duration.from(since);
-    return getRelativeTimeFormat(locale).format(duration.minutes, "minutes");
+    return formatRelativeUnit(duration.minutes, "minutes", locale, style);
 };
 /**
  * Calculates the time duration between two TemporalDate objects and returns the duration in hours as a formatted string.
@@ -1052,7 +1134,7 @@ const timeSinceInMinutes = (from, to, timeZone, locale) => {
  * const result = timeSinceInHours(startDate, endDate);
  * Output: "3 hours ago"
  */
-const timeSinceInHours = (from, to, timeZone, locale) => {
+const timeSinceInHours = (from, to, timeZone, locale, style) => {
     let since = new polyfill.Temporal.Duration();
     try {
         since = toZonedDateTimeUtil(from, timeZone).since(toZonedDateTimeUtil(to, timeZone), {
@@ -1064,7 +1146,7 @@ const timeSinceInHours = (from, to, timeZone, locale) => {
         console.warn("Error: ", error);
     }
     const duration = polyfill.Temporal.Duration.from(since);
-    return getRelativeTimeFormat(locale).format(duration.hours, "hours");
+    return formatRelativeUnit(duration.hours, "hours", locale, style);
 };
 /**
  * Calculates the time duration between two TemporalDate objects and returns the duration in days as a formatted string.
@@ -1087,7 +1169,7 @@ const timeSinceInHours = (from, to, timeZone, locale) => {
  * const result = timeSinceInDays(startDate, endDate, 'America/New_York', 'en-US');
  * Output: "6 days ago"
  */
-const timeSinceInDays = (from, to, timeZone, locale) => {
+const timeSinceInDays = (from, to, timeZone, locale, style) => {
     let since = new polyfill.Temporal.Duration();
     try {
         since = toZonedDateTimeUtil(from, timeZone).since(toZonedDateTimeUtil(to, timeZone), {
@@ -1099,7 +1181,7 @@ const timeSinceInDays = (from, to, timeZone, locale) => {
         console.warn("Error: ", error);
     }
     const duration = polyfill.Temporal.Duration.from(since);
-    return getRelativeTimeFormat(locale).format(Math.ceil(duration.hours / 24.0), "days");
+    return formatRelativeUnit(Math.ceil(duration.hours / 24.0), "days", locale, style);
 };
 /**
  * Calculates the time duration between two TemporalDate objects and returns the duration in months as a formatted string.
@@ -1109,6 +1191,11 @@ const timeSinceInDays = (from, to, timeZone, locale) => {
  * @param {string} [timeZone] - The time zone to use for the calculations. Defaults to the local time zone.
  * @param {string} [locale] - The locale to use for formatting the duration. Defaults to the user's locale.
  * @returns {string} - The formatted duration in months.
+ * @remarks When both `from` and `to` fall in a leap year, the function falls back to
+ *   `timeSinceInDays` and returns the raw day count for the whole span. Callers relying on a
+ *   specific unit — especially with `style="narrow-compact"`, where the unit is visible —
+ *   should be aware that the output can be an arbitrarily large day count (e.g. `"60d"` for a
+ *   two-month gap) instead of months on those inputs.
  * @example
  * const startDate = "2023-05-10"
  * const endDate = "2023-07-11"
@@ -1116,10 +1203,10 @@ const timeSinceInDays = (from, to, timeZone, locale) => {
  * const result = timeSinceInMonths(startDate, endDate, 'America/New_York', 'en-US');
  * Output: "2 months ago"
  */
-const timeSinceInMonths = (from, to, timeZone, locale) => {
+const timeSinceInMonths = (from, to, timeZone, locale, style) => {
     const isLeapYear = toZonedDateTimeUtil(from, timeZone).inLeapYear && toZonedDateTimeUtil(to, timeZone).inLeapYear;
     if (isLeapYear) {
-        return timeSinceInDays(from, to, timeZone, locale);
+        return timeSinceInDays(from, to, timeZone, locale, style);
     }
     let since = new polyfill.Temporal.Duration();
     try {
@@ -1132,7 +1219,7 @@ const timeSinceInMonths = (from, to, timeZone, locale) => {
         console.warn("Error: ", error);
     }
     const duration = polyfill.Temporal.Duration.from(since);
-    return getRelativeTimeFormat(locale).format(duration.months, "months");
+    return formatRelativeUnit(duration.months, "months", locale, style);
 };
 /**
  * Calculates the time duration between two TemporalDate objects and returns the duration in years as a formatted string.
@@ -1142,6 +1229,11 @@ const timeSinceInMonths = (from, to, timeZone, locale) => {
  * @param {string} [timeZone] - The time zone to use for the calculations. Defaults to the local time zone.
  * @param {string} [locale] - The locale to use for formatting the duration. Defaults to the user's locale.
  * @returns {string} - The formatted duration in years.
+ * @remarks When both `from` and `to` fall in a leap year, the function falls back to
+ *   `timeSinceInDays` and returns the raw day count for the whole span. Callers relying on a
+ *   specific unit — especially with `style="narrow-compact"`, where the unit is visible —
+ *   should be aware that the output can be an arbitrarily large day count (e.g. `"1462d"` for
+ *   a ~4-year gap between two leap-year endpoints) instead of years on those inputs.
  * @example
  * const startDate = "2023-05-10"
  * const endDate = "2024-05-11"
@@ -1149,10 +1241,10 @@ const timeSinceInMonths = (from, to, timeZone, locale) => {
  * const result = timeSinceInYears(startDate, endDate, 'America/New_York', 'en-US');
  * Output: "1 year ago"
  */
-const timeSinceInYears = (from, to, timeZone, locale) => {
+const timeSinceInYears = (from, to, timeZone, locale, style) => {
     const isLeapYear = toZonedDateTimeUtil(from, timeZone).inLeapYear && toZonedDateTimeUtil(to, timeZone).inLeapYear;
     if (isLeapYear) {
-        return timeSinceInDays(from, to, timeZone, locale);
+        return timeSinceInDays(from, to, timeZone, locale, style);
     }
     let since = new polyfill.Temporal.Duration();
     try {
@@ -1165,9 +1257,9 @@ const timeSinceInYears = (from, to, timeZone, locale) => {
         console.warn("Error: ", error);
     }
     const duration = polyfill.Temporal.Duration.from(since);
-    return getRelativeTimeFormat(locale).format(duration.years, "years");
+    return formatRelativeUnit(duration.years, "years", locale, style);
 };
-const getRelativeTimeFormat = (locale) => new Intl.RelativeTimeFormat(locale, { style: "long", numeric: "always" });
+const getRelativeTimeFormat = (locale, style = "long") => new Intl.RelativeTimeFormat(locale, { style, numeric: "always" });
 /**
  * Get duration in human-readable form
  *

package/index.esm.js

@@ -910,6 +910,76 @@ const isEqualUtil = (from, to) => {
         .round({ smallestUnit: "seconds" })
         .equals(toZonedDateTimeUtil(to).round({ smallestUnit: "seconds" }));
 };
+const localeScriptCache = new Map();
+const localeScript = (locale) => {
+    const key = locale ?? "";
+    if (localeScriptCache.has(key))
+        return localeScriptCache.get(key);
+    let script;
+    try {
+        script = new Intl.Locale(locale ?? new Intl.NumberFormat().resolvedOptions().locale).maximize().script;
+    }
+    catch {
+        script = undefined;
+    }
+    localeScriptCache.set(key, script);
+    return script;
+};
+/**
+ * True when `Intl.NumberFormat` narrow for `locale`/`unit` renders in Latin script on a
+ * non-Latin-script locale — the symptom of a missing `units-narrow` slot silently
+ * inheriting from CLDR `root`. Detected directly on the formatter's output; this avoids
+ * any dependency on the ECMA-402 `DefaultLocale`, which would be the case if we tried to
+ * address `root` through `Intl` (there is no way: `Intl.NumberFormat("root")` throws, and
+ * `Intl.NumberFormat("und")` resolves via `LookupMatcher` to the runtime's default
+ * locale, not to CLDR root).
+ *
+ * Latin-script locales short-circuit to `false`: even if their narrow slot is empty and
+ * inherits from root, the fallback is still in the right script, so the output is not
+ * meaningfully delocalised.
+ */
+const narrowUnitIsDelocalisedCache = new Map();
+const narrowUnitIsDelocalised = (locale, unit) => {
+    const key = (locale ?? "") + "|" + unit;
+    const cached = narrowUnitIsDelocalisedCache.get(key);
+    if (cached !== undefined)
+        return cached;
+    if (localeScript(locale) === "Latn") {
+        narrowUnitIsDelocalisedCache.set(key, false);
+        return false;
+    }
+    const out = new Intl.NumberFormat(locale, { style: "unit", unit, unitDisplay: "narrow" }).format(1);
+    const delocalised = /[A-Za-z]/.test(out);
+    narrowUnitIsDelocalisedCache.set(key, delocalised);
+    return delocalised;
+};
+/**
+ * Formats a signed unit value using the Trackunit style axis.
+ * - `narrow-compact` past values → `Intl.NumberFormat` unit narrow (no affix), but only if
+ *   the locale actually has native narrow data (i.e. not a silent root/Latin fallback);
+ *   otherwise routes through `Intl.RelativeTimeFormat` narrow to preserve script.
+ * - `narrow-compact` future values → `Intl.RelativeTimeFormat` narrow (retains the CLDR-native
+ *   leading affix — the API has no way to strip it).
+ * - No style specified → `Intl.RelativeTimeFormat` long (the default).
+ */
+const formatRelativeUnit = (value, unit, locale, style) => {
+    if (style === "narrow-compact") {
+        if (value <= 0) {
+            const singularUnit = unit.endsWith("s") ? unit.slice(0, -1) : unit;
+            if (!narrowUnitIsDelocalised(locale, singularUnit)) {
+                return new Intl.NumberFormat(locale, {
+                    style: "unit",
+                    unit: singularUnit,
+                    unitDisplay: "narrow",
+                }).format(Math.abs(value));
+            }
+            // Non-Latin script whose units-narrow output would render in Latin (CLDR root
+            // fallback) — route through `RelativeTimeFormat` narrow to preserve script.
+        }
+        return getRelativeTimeFormat(locale, "narrow").format(value, unit);
+    }
+    return getRelativeTimeFormat(locale).format(value, unit);
+};
 /**
  * Calculates the time duration between two TemporalDate objects and returns a human-readable string representation of the duration.
  *
@@ -917,6 +987,12 @@ const isEqualUtil = (from, to) => {
  * @param {TemporalDate} to - The ending date.
  * @param {string} [timeZone] - The time zone to use for the calculations. Defaults to the local time zone.
  * @param {string} [locale] - The locale to use for formatting the duration. Defaults to the user's locale.
+ * @param {TuRelativeTimeStyle} [style] - Optional width override. Pass `"narrow-compact"` to render
+ *   past values without any past-tense affix (`"2d"` in en, `"2j"` in fr) while future values retain
+ *   the CLDR-native leading affix (`"in 2d"` in en). Non-Latin-script locales without native CLDR
+ *   narrow data fall back to `RelativeTimeFormat` narrow to preserve script, which keeps the affix
+ *   (`"2日前"` in ja) — see {@link TuRelativeTimeStyle} for the CLDR-table-sourcing details.
+ *   Omit `style` to get the default long form (`"2 days ago"` in en, `"vor 2 Tagen"` in de).
  * @returns {string|Error} - The formatted duration string or an Error object if the duration is not valid.
  * @example
  * const startDate = "2023-05-1010:30:00.000Z"
@@ -936,8 +1012,14 @@ const isEqualUtil = (from, to) => {
  *
  * const result = timeSinceAuto(startDate, endDate, 'America/New_York', 'en-US');
  * Output:  "1 year ago"
+ * @example
+ * const startDate = "2023-05-10"
+ * const endDate = "2023-05-18"
+ *
+ * const result = timeSinceAuto(startDate, endDate, 'America/New_York', 'en-US', 'narrow-compact');
+ * Output:  "8d"
  */
-const timeSinceAuto = (from, to, timeZone, locale) => {
+const timeSinceAuto = (from, to, timeZone, locale, style) => {
     let since;
     try {
         since = toZonedDateTimeUtil(from, timeZone)
@@ -954,25 +1036,25 @@ const timeSinceAuto = (from, to, timeZone, locale) => {
     }
     const duration = Temporal.Duration.from(since);
     if (duration.blank) {
-        return getRelativeTimeFormat(locale).format(-1, "seconds");
+        return formatRelativeUnit(-1, "seconds", locale, style);
     }
     if (duration.years !== 0) {
-        return getRelativeTimeFormat(locale).format(duration.years, "years");
+        return formatRelativeUnit(duration.years, "years", locale, style);
     }
     if (duration.months !== 0) {
-        return getRelativeTimeFormat(locale).format(duration.months, "months");
+        return formatRelativeUnit(duration.months, "months", locale, style);
     }
     if (duration.days !== 0) {
-        return getRelativeTimeFormat(locale).format(duration.days, "days");
+        return formatRelativeUnit(duration.days, "days", locale, style);
     }
     if (duration.hours !== 0) {
-        return getRelativeTimeFormat(locale).format(duration.hours, "hours");
+        return formatRelativeUnit(duration.hours, "hours", locale, style);
     }
     if (duration.minutes !== 0) {
-        return getRelativeTimeFormat(locale).format(duration.minutes, "minutes");
+        return formatRelativeUnit(duration.minutes, "minutes", locale, style);
     }
     if (duration.seconds !== 0) {
-        return getRelativeTimeFormat(locale).format(duration.seconds, "seconds");
+        return formatRelativeUnit(duration.seconds, "seconds", locale, style);
     }
     // eslint-disable-next-line no-console
     console.warn(new Error("Not a valid duration", { cause: duration }));
@@ -993,7 +1075,7 @@ const timeSinceAuto = (from, to, timeZone, locale) => {
  * const result = timeSinceInSeconds(startDate, endDate, 'America/New_York', 'en-US');
  * Output: "480 seconds ago"
  */
-const timeSinceInSeconds = (from, to, timeZone, locale) => {
+const timeSinceInSeconds = (from, to, timeZone, locale, style) => {
     let since = new Temporal.Duration();
     try {
         since = toZonedDateTimeUtil(from, timeZone).since(toZonedDateTimeUtil(to, timeZone), {
@@ -1005,7 +1087,7 @@ const timeSinceInSeconds = (from, to, timeZone, locale) => {
         console.warn("Error: ", error);
     }
     const duration = Temporal.Duration.from(since);
-    return getRelativeTimeFormat(locale).format(duration.seconds, "seconds");
+    return formatRelativeUnit(duration.seconds, "seconds", locale, style);
 };
 /**
  * Calculates the time duration between two TemporalDate objects and returns the duration in minutes as a formatted string.
@@ -1022,7 +1104,7 @@ const timeSinceInSeconds = (from, to, timeZone, locale) => {
  * const result = timeSinceInSeconds(startDate, endDate, 'America/New_York', 'en-US');
  * Output: "8 minutes ago"
  */
-const timeSinceInMinutes = (from, to, timeZone, locale) => {
+const timeSinceInMinutes = (from, to, timeZone, locale, style) => {
     let since = new Temporal.Duration();
     try {
         since = toZonedDateTimeUtil(from, timeZone).since(toZonedDateTimeUtil(to, timeZone), {
@@ -1034,7 +1116,7 @@ const timeSinceInMinutes = (from, to, timeZone, locale) => {
         console.warn("Error: ", error);
     }
     const duration = Temporal.Duration.from(since);
-    return getRelativeTimeFormat(locale).format(duration.minutes, "minutes");
+    return formatRelativeUnit(duration.minutes, "minutes", locale, style);
 };
 /**
  * Calculates the time duration between two TemporalDate objects and returns the duration in hours as a formatted string.
@@ -1051,7 +1133,7 @@ const timeSinceInMinutes = (from, to, timeZone, locale) => {
  * const result = timeSinceInHours(startDate, endDate);
  * Output: "3 hours ago"
  */
-const timeSinceInHours = (from, to, timeZone, locale) => {
+const timeSinceInHours = (from, to, timeZone, locale, style) => {
     let since = new Temporal.Duration();
     try {
         since = toZonedDateTimeUtil(from, timeZone).since(toZonedDateTimeUtil(to, timeZone), {
@@ -1063,7 +1145,7 @@ const timeSinceInHours = (from, to, timeZone, locale) => {
         console.warn("Error: ", error);
     }
     const duration = Temporal.Duration.from(since);
-    return getRelativeTimeFormat(locale).format(duration.hours, "hours");
+    return formatRelativeUnit(duration.hours, "hours", locale, style);
 };
 /**
  * Calculates the time duration between two TemporalDate objects and returns the duration in days as a formatted string.
@@ -1086,7 +1168,7 @@ const timeSinceInHours = (from, to, timeZone, locale) => {
  * const result = timeSinceInDays(startDate, endDate, 'America/New_York', 'en-US');
  * Output: "6 days ago"
  */
-const timeSinceInDays = (from, to, timeZone, locale) => {
+const timeSinceInDays = (from, to, timeZone, locale, style) => {
     let since = new Temporal.Duration();
     try {
         since = toZonedDateTimeUtil(from, timeZone).since(toZonedDateTimeUtil(to, timeZone), {
@@ -1098,7 +1180,7 @@ const timeSinceInDays = (from, to, timeZone, locale) => {
         console.warn("Error: ", error);
     }
     const duration = Temporal.Duration.from(since);
-    return getRelativeTimeFormat(locale).format(Math.ceil(duration.hours / 24.0), "days");
+    return formatRelativeUnit(Math.ceil(duration.hours / 24.0), "days", locale, style);
 };
 /**
  * Calculates the time duration between two TemporalDate objects and returns the duration in months as a formatted string.
@@ -1108,6 +1190,11 @@ const timeSinceInDays = (from, to, timeZone, locale) => {
  * @param {string} [timeZone] - The time zone to use for the calculations. Defaults to the local time zone.
  * @param {string} [locale] - The locale to use for formatting the duration. Defaults to the user's locale.
  * @returns {string} - The formatted duration in months.
+ * @remarks When both `from` and `to` fall in a leap year, the function falls back to
+ *   `timeSinceInDays` and returns the raw day count for the whole span. Callers relying on a
+ *   specific unit — especially with `style="narrow-compact"`, where the unit is visible —
+ *   should be aware that the output can be an arbitrarily large day count (e.g. `"60d"` for a
+ *   two-month gap) instead of months on those inputs.
  * @example
  * const startDate = "2023-05-10"
  * const endDate = "2023-07-11"
@@ -1115,10 +1202,10 @@ const timeSinceInDays = (from, to, timeZone, locale) => {
  * const result = timeSinceInMonths(startDate, endDate, 'America/New_York', 'en-US');
  * Output: "2 months ago"
  */
-const timeSinceInMonths = (from, to, timeZone, locale) => {
+const timeSinceInMonths = (from, to, timeZone, locale, style) => {
     const isLeapYear = toZonedDateTimeUtil(from, timeZone).inLeapYear && toZonedDateTimeUtil(to, timeZone).inLeapYear;
     if (isLeapYear) {
-        return timeSinceInDays(from, to, timeZone, locale);
+        return timeSinceInDays(from, to, timeZone, locale, style);
     }
     let since = new Temporal.Duration();
     try {
@@ -1131,7 +1218,7 @@ const timeSinceInMonths = (from, to, timeZone, locale) => {
         console.warn("Error: ", error);
     }
     const duration = Temporal.Duration.from(since);
-    return getRelativeTimeFormat(locale).format(duration.months, "months");
+    return formatRelativeUnit(duration.months, "months", locale, style);
 };
 /**
  * Calculates the time duration between two TemporalDate objects and returns the duration in years as a formatted string.
@@ -1141,6 +1228,11 @@ const timeSinceInMonths = (from, to, timeZone, locale) => {
  * @param {string} [timeZone] - The time zone to use for the calculations. Defaults to the local time zone.
  * @param {string} [locale] - The locale to use for formatting the duration. Defaults to the user's locale.
  * @returns {string} - The formatted duration in years.
+ * @remarks When both `from` and `to` fall in a leap year, the function falls back to
+ *   `timeSinceInDays` and returns the raw day count for the whole span. Callers relying on a
+ *   specific unit — especially with `style="narrow-compact"`, where the unit is visible —
+ *   should be aware that the output can be an arbitrarily large day count (e.g. `"1462d"` for
+ *   a ~4-year gap between two leap-year endpoints) instead of years on those inputs.
  * @example
  * const startDate = "2023-05-10"
  * const endDate = "2024-05-11"
@@ -1148,10 +1240,10 @@ const timeSinceInMonths = (from, to, timeZone, locale) => {
  * const result = timeSinceInYears(startDate, endDate, 'America/New_York', 'en-US');
  * Output: "1 year ago"
  */
-const timeSinceInYears = (from, to, timeZone, locale) => {
+const timeSinceInYears = (from, to, timeZone, locale, style) => {
     const isLeapYear = toZonedDateTimeUtil(from, timeZone).inLeapYear && toZonedDateTimeUtil(to, timeZone).inLeapYear;
     if (isLeapYear) {
-        return timeSinceInDays(from, to, timeZone, locale);
+        return timeSinceInDays(from, to, timeZone, locale, style);
     }
     let since = new Temporal.Duration();
     try {
@@ -1164,9 +1256,9 @@ const timeSinceInYears = (from, to, timeZone, locale) => {
         console.warn("Error: ", error);
     }
     const duration = Temporal.Duration.from(since);
-    return getRelativeTimeFormat(locale).format(duration.years, "years");
+    return formatRelativeUnit(duration.years, "years", locale, style);
 };
-const getRelativeTimeFormat = (locale) => new Intl.RelativeTimeFormat(locale, { style: "long", numeric: "always" });
+const getRelativeTimeFormat = (locale, style = "long") => new Intl.RelativeTimeFormat(locale, { style, numeric: "always" });
 /**
  * Get duration in human-readable form
  *

package/migrations/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../../../../libs/date-and-time/utils/migrations/entry.ts"],"names":[],"mappings":"","sourcesContent":["export {};\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/date-and-time-utils",
-  "version": "1.14.4-alpha-d0f54ff2967.0",
+  "version": "1.14.5",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {

package/src/DateAndTimeUtils.d.ts

@@ -683,6 +683,43 @@ export declare const isSameYearUtil: (date: TemporalDate) => boolean;
  * Output: true
  */
 export declare const isEqualUtil: (from: TemporalDate, to: TemporalDate) => boolean;
+/**
+ * Trackunit-owned relative-time style axis. The single supported value is `"narrow-compact"` —
+ * the shortest possible locale-native output for past durations. When `style` is omitted, the
+ * default `Intl.RelativeTimeFormat` long output is used (e.g. `"2 days ago"` in en).
+ *
+ * Past values are pulled from CLDR's `units-narrow` table via `Intl.NumberFormat`
+ * `style: "unit"`, which omits any past-tense affix by design (it's a measurement-quantity
+ * API — "5 kg", "12 mi"). Future values continue to come from `Intl.RelativeTimeFormat`
+ * narrow, which retains the future affix ("in") because CLDR treats it as grammar rather
+ * than an appendable string.
+ *
+ * ### Cross-locale fallback
+ * CLDR does not populate `units-narrow` for every locale — notably Japanese (`ja`) has no
+ * narrow entries at all, and several other locales lack entries for some units (e.g.
+ * Spanish `day`/`month`, Swedish and Norwegian `day`/`minute`/…). Missing slots inherit
+ * from CLDR `root`, which renders in Latin (`"2d"`, `"2y"`, …). For Latin-script locales
+ * that's cosmetic — the fallback is still in the right script — but for non-Latin locales
+ * it silently delocalises the output. To avoid that, when the target locale's script is
+ * non-Latin *and* the `NumberFormat` narrow output actually contains Latin letters, this
+ * style transparently falls through to `RelativeTimeFormat` narrow for that (locale, unit)
+ * combination. That path keeps the past-tense affix, which is unavoidable there, but the
+ * affix is short in the affected locales (e.g. Japanese `"2日前"`) and correct localization
+ * beats aggressive compaction.
+ *
+ * ### Known CLDR quirks
+ * Because past/future paths read from *different* CLDR tables, the symbol for a given unit
+ * may differ between them in a given locale (e.g. English past-month renders as `"3m"` from
+ * `units-narrow`, while future-month renders as `"in 3mo"` from `dateFields-narrow`, which
+ * CLDR disambiguates against `minute`). Both are the source-of-truth CLDR narrow displays
+ * for their respective APIs — this is by design in CLDR, not something we rewrite in JS.
+ *
+ * ### When to use `"narrow-compact"`
+ * When the surrounding UI already makes "past" obvious for negative durations — for example
+ * a "last seen" icon or a hover title that repeats the phrase in full. Otherwise omit `style`
+ * so the default long form is used, which is unambiguous in isolation.
+ */
+export type TuRelativeTimeStyle = "narrow-compact";
 /**
  * Calculates the time duration between two TemporalDate objects and returns a human-readable string representation of the duration.
  *
@@ -690,6 +727,12 @@ export declare const isEqualUtil: (from: TemporalDate, to: TemporalDate) => bool
  * @param {TemporalDate} to - The ending date.
  * @param {string} [timeZone] - The time zone to use for the calculations. Defaults to the local time zone.
  * @param {string} [locale] - The locale to use for formatting the duration. Defaults to the user's locale.
+ * @param {TuRelativeTimeStyle} [style] - Optional width override. Pass `"narrow-compact"` to render
+ *   past values without any past-tense affix (`"2d"` in en, `"2j"` in fr) while future values retain
+ *   the CLDR-native leading affix (`"in 2d"` in en). Non-Latin-script locales without native CLDR
+ *   narrow data fall back to `RelativeTimeFormat` narrow to preserve script, which keeps the affix
+ *   (`"2日前"` in ja) — see {@link TuRelativeTimeStyle} for the CLDR-table-sourcing details.
+ *   Omit `style` to get the default long form (`"2 days ago"` in en, `"vor 2 Tagen"` in de).
  * @returns {string|Error} - The formatted duration string or an Error object if the duration is not valid.
  * @example
  * const startDate = "2023-05-1010:30:00.000Z"
@@ -709,8 +752,14 @@ export declare const isEqualUtil: (from: TemporalDate, to: TemporalDate) => bool
  *
  * const result = timeSinceAuto(startDate, endDate, 'America/New_York', 'en-US');
  * Output:  "1 year ago"
+ * @example
+ * const startDate = "2023-05-10"
+ * const endDate = "2023-05-18"
+ *
+ * const result = timeSinceAuto(startDate, endDate, 'America/New_York', 'en-US', 'narrow-compact');
+ * Output:  "8d"
  */
-export declare const timeSinceAuto: (from: TemporalDate, to: TemporalDate, timeZone?: string, locale?: string) => string;
+export declare const timeSinceAuto: (from: TemporalDate, to: TemporalDate, timeZone?: string, locale?: string, style?: TuRelativeTimeStyle) => string;
 /**
  * Calculates the time duration between two TemporalDate objects and returns the duration in seconds as a formatted string.
  *
@@ -726,7 +775,7 @@ export declare const timeSinceAuto: (from: TemporalDate, to: TemporalDate, timeZ
  * const result = timeSinceInSeconds(startDate, endDate, 'America/New_York', 'en-US');
  * Output: "480 seconds ago"
  */
-export declare const timeSinceInSeconds: (from: TemporalDate, to: TemporalDate, timeZone?: string, locale?: string) => string;
+export declare const timeSinceInSeconds: (from: TemporalDate, to: TemporalDate, timeZone?: string, locale?: string, style?: TuRelativeTimeStyle) => string;
 /**
  * Calculates the time duration between two TemporalDate objects and returns the duration in minutes as a formatted string.
  *
@@ -742,7 +791,7 @@ export declare const timeSinceInSeconds: (from: TemporalDate, to: TemporalDate,
  * const result = timeSinceInSeconds(startDate, endDate, 'America/New_York', 'en-US');
  * Output: "8 minutes ago"
  */
-export declare const timeSinceInMinutes: (from: TemporalDate, to: TemporalDate, timeZone?: string, locale?: string) => string;
+export declare const timeSinceInMinutes: (from: TemporalDate, to: TemporalDate, timeZone?: string, locale?: string, style?: TuRelativeTimeStyle) => string;
 /**
  * Calculates the time duration between two TemporalDate objects and returns the duration in hours as a formatted string.
  *
@@ -758,7 +807,7 @@ export declare const timeSinceInMinutes: (from: TemporalDate, to: TemporalDate,
  * const result = timeSinceInHours(startDate, endDate);
  * Output: "3 hours ago"
  */
-export declare const timeSinceInHours: (from: TemporalDate, to: TemporalDate, timeZone?: string, locale?: string) => string;
+export declare const timeSinceInHours: (from: TemporalDate, to: TemporalDate, timeZone?: string, locale?: string, style?: TuRelativeTimeStyle) => string;
 /**
  * Calculates the time duration between two TemporalDate objects and returns the duration in days as a formatted string.
  *
@@ -780,7 +829,7 @@ export declare const timeSinceInHours: (from: TemporalDate, to: TemporalDate, ti
  * const result = timeSinceInDays(startDate, endDate, 'America/New_York', 'en-US');
  * Output: "6 days ago"
  */
-export declare const timeSinceInDays: (from: TemporalDate, to: TemporalDate, timeZone?: string, locale?: string) => string;
+export declare const timeSinceInDays: (from: TemporalDate, to: TemporalDate, timeZone?: string, locale?: string, style?: TuRelativeTimeStyle) => string;
 /**
  * Calculates the time duration between two TemporalDate objects and returns the duration in months as a formatted string.
  *
@@ -789,6 +838,11 @@ export declare const timeSinceInDays: (from: TemporalDate, to: TemporalDate, tim
  * @param {string} [timeZone] - The time zone to use for the calculations. Defaults to the local time zone.
  * @param {string} [locale] - The locale to use for formatting the duration. Defaults to the user's locale.
  * @returns {string} - The formatted duration in months.
+ * @remarks When both `from` and `to` fall in a leap year, the function falls back to
+ *   `timeSinceInDays` and returns the raw day count for the whole span. Callers relying on a
+ *   specific unit — especially with `style="narrow-compact"`, where the unit is visible —
+ *   should be aware that the output can be an arbitrarily large day count (e.g. `"60d"` for a
+ *   two-month gap) instead of months on those inputs.
  * @example
  * const startDate = "2023-05-10"
  * const endDate = "2023-07-11"
@@ -796,7 +850,7 @@ export declare const timeSinceInDays: (from: TemporalDate, to: TemporalDate, tim
  * const result = timeSinceInMonths(startDate, endDate, 'America/New_York', 'en-US');
  * Output: "2 months ago"
  */
-export declare const timeSinceInMonths: (from: TemporalDate, to: TemporalDate, timeZone?: string, locale?: string) => string;
+export declare const timeSinceInMonths: (from: TemporalDate, to: TemporalDate, timeZone?: string, locale?: string, style?: TuRelativeTimeStyle) => string;
 /**
  * Calculates the time duration between two TemporalDate objects and returns the duration in years as a formatted string.
  *
@@ -805,6 +859,11 @@ export declare const timeSinceInMonths: (from: TemporalDate, to: TemporalDate, t
  * @param {string} [timeZone] - The time zone to use for the calculations. Defaults to the local time zone.
  * @param {string} [locale] - The locale to use for formatting the duration. Defaults to the user's locale.
  * @returns {string} - The formatted duration in years.
+ * @remarks When both `from` and `to` fall in a leap year, the function falls back to
+ *   `timeSinceInDays` and returns the raw day count for the whole span. Callers relying on a
+ *   specific unit — especially with `style="narrow-compact"`, where the unit is visible —
+ *   should be aware that the output can be an arbitrarily large day count (e.g. `"1462d"` for
+ *   a ~4-year gap between two leap-year endpoints) instead of years on those inputs.
  * @example
  * const startDate = "2023-05-10"
  * const endDate = "2024-05-11"
@@ -812,7 +871,7 @@ export declare const timeSinceInMonths: (from: TemporalDate, to: TemporalDate, t
  * const result = timeSinceInYears(startDate, endDate, 'America/New_York', 'en-US');
  * Output: "1 year ago"
  */
-export declare const timeSinceInYears: (from: TemporalDate, to: TemporalDate, timeZone?: string, locale?: string) => string;
+export declare const timeSinceInYears: (from: TemporalDate, to: TemporalDate, timeZone?: string, locale?: string, style?: TuRelativeTimeStyle) => string;
 /**
  * Get duration in human-readable form
  *