@trackunit/date-and-time-utils 1.13.25-alpha-9d327375fc1.0 → 1.13.28

package/index.cjs.js

@@ -35,9 +35,35 @@ const timeZonesAvailable = Intl.supportedValuesOf("timeZone");
 const LOCALES_WITH_23h_CYCLE = ["da", "de", "jp"];
 const DEFAULT_HOUR_CYCLE = "h12";
 /**
- * Return the most probable hour cycle based on the locale
+ * Maps a user "time format" preference onto an `Intl` hour cycle.
+ *
+ * Returns `undefined` for "language default" (or no preference) so callers fall back to the
+ * locale-derived hour cycle. A 12-hour preference resolves to `h12` and 24-hour to `h23`.
+ *
+ * @param timeFormat - The user's time format preference (`"LANGUAGE_DEFAULT" | "TWELVE_HOUR" | "TWENTY_FOUR_HOUR"`).
+ * @returns {Intl.LocaleHourCycleKey | undefined} The forced hour cycle, or `undefined` to let the locale decide.
  */
-const getHourCycle = (locale) => {
+const timeFormatToHourCycle = (timeFormat) => {
+    switch (timeFormat) {
+        case "TWELVE_HOUR":
+            return "h12";
+        case "TWENTY_FOUR_HOUR":
+            return "h23";
+        default:
+            return undefined;
+    }
+};
+/**
+ * Return the most probable hour cycle based on the locale.
+ *
+ * @param locale - The locale used to derive the hour cycle.
+ * @param hourCycleOverride - When provided, takes precedence over the locale-derived hour cycle.
+ *   Used to honor an explicit user time-format preference (12H/24H).
+ */
+const getHourCycle = (locale, hourCycleOverride) => {
+    if (hourCycleOverride) {
+        return hourCycleOverride;
+    }
     if (!locale) {
         return DEFAULT_HOUR_CYCLE;
     }
@@ -63,6 +89,8 @@ const getHourCycle = (locale) => {
  * @param {TemporalFormat} [format] - The format options for the date and/or time. If not provided, default format options will be used.
  * @param {string} [timeZone] - The time zone to use for formatting. If not provided, the system's default time zone will be used.
  * @param {string} [locale] - The locale to use for formatting. If not provided, the system's default locale will be used.
+ * @param {Intl.LocaleHourCycleKey} [hourCycleOverride] - Forces a specific hour cycle (e.g. `h12`/`h23`) regardless of locale.
+ *   Used to honor an explicit user time-format preference. When omitted, the locale decides.
  * @returns {string} The formatted date string.
  * @example
  * const dateString = "2023-05-10"
@@ -96,8 +124,8 @@ const getHourCycle = (locale) => {
  * const formattedDate = formatDateUtil(date, format, timeZone, locale);
  * Output: "5/10/23, 12:00:00 AM EDT"
  */
-const formatDateUtil = (date, format, timeZone, locale) => {
-    const hourCycle = getHourCycle(locale);
+const formatDateUtil = (date, format, timeZone, locale, hourCycleOverride) => {
+    const hourCycle = getHourCycle(locale, hourCycleOverride);
     const dateObj = timeZone ? toZonedDateTimeUtil(date, timeZone) : toTemporalUtil(toDateUtil(date));
     if (format?.selectFormat === "dateOnly") {
         if (dateObj instanceof polyfill.Temporal.ZonedDateTime) {
@@ -1684,6 +1712,7 @@ exports.subtractMinutesUtil = subtractMinutesUtil;
 exports.subtractMonthsUtil = subtractMonthsUtil;
 exports.subtractWeeksUtil = subtractWeeksUtil;
 exports.subtractYearsUtil = subtractYearsUtil;
+exports.timeFormatToHourCycle = timeFormatToHourCycle;
 exports.timeSinceAuto = timeSinceAuto;
 exports.timeSinceInDays = timeSinceInDays;
 exports.timeSinceInHours = timeSinceInHours;

package/index.esm.js

@@ -34,9 +34,35 @@ const timeZonesAvailable = Intl.supportedValuesOf("timeZone");
 const LOCALES_WITH_23h_CYCLE = ["da", "de", "jp"];
 const DEFAULT_HOUR_CYCLE = "h12";
 /**
- * Return the most probable hour cycle based on the locale
+ * Maps a user "time format" preference onto an `Intl` hour cycle.
+ *
+ * Returns `undefined` for "language default" (or no preference) so callers fall back to the
+ * locale-derived hour cycle. A 12-hour preference resolves to `h12` and 24-hour to `h23`.
+ *
+ * @param timeFormat - The user's time format preference (`"LANGUAGE_DEFAULT" | "TWELVE_HOUR" | "TWENTY_FOUR_HOUR"`).
+ * @returns {Intl.LocaleHourCycleKey | undefined} The forced hour cycle, or `undefined` to let the locale decide.
  */
-const getHourCycle = (locale) => {
+const timeFormatToHourCycle = (timeFormat) => {
+    switch (timeFormat) {
+        case "TWELVE_HOUR":
+            return "h12";
+        case "TWENTY_FOUR_HOUR":
+            return "h23";
+        default:
+            return undefined;
+    }
+};
+/**
+ * Return the most probable hour cycle based on the locale.
+ *
+ * @param locale - The locale used to derive the hour cycle.
+ * @param hourCycleOverride - When provided, takes precedence over the locale-derived hour cycle.
+ *   Used to honor an explicit user time-format preference (12H/24H).
+ */
+const getHourCycle = (locale, hourCycleOverride) => {
+    if (hourCycleOverride) {
+        return hourCycleOverride;
+    }
     if (!locale) {
         return DEFAULT_HOUR_CYCLE;
     }
@@ -62,6 +88,8 @@ const getHourCycle = (locale) => {
  * @param {TemporalFormat} [format] - The format options for the date and/or time. If not provided, default format options will be used.
  * @param {string} [timeZone] - The time zone to use for formatting. If not provided, the system's default time zone will be used.
  * @param {string} [locale] - The locale to use for formatting. If not provided, the system's default locale will be used.
+ * @param {Intl.LocaleHourCycleKey} [hourCycleOverride] - Forces a specific hour cycle (e.g. `h12`/`h23`) regardless of locale.
+ *   Used to honor an explicit user time-format preference. When omitted, the locale decides.
  * @returns {string} The formatted date string.
  * @example
  * const dateString = "2023-05-10"
@@ -95,8 +123,8 @@ const getHourCycle = (locale) => {
  * const formattedDate = formatDateUtil(date, format, timeZone, locale);
  * Output: "5/10/23, 12:00:00 AM EDT"
  */
-const formatDateUtil = (date, format, timeZone, locale) => {
-    const hourCycle = getHourCycle(locale);
+const formatDateUtil = (date, format, timeZone, locale, hourCycleOverride) => {
+    const hourCycle = getHourCycle(locale, hourCycleOverride);
     const dateObj = timeZone ? toZonedDateTimeUtil(date, timeZone) : toTemporalUtil(toDateUtil(date));
     if (format?.selectFormat === "dateOnly") {
         if (dateObj instanceof Temporal.ZonedDateTime) {
@@ -1623,4 +1651,4 @@ const parseValidDate = (date) => {
     return null;
 };
 
-export { addDaysUtil, addHoursUtil, addMinutesUtil, addMonthsUtil, addWeeksUtil, addYearsUtil, convertHoursUtil, convertMillisecondsUtil, convertMinutesUtil, convertSecondsUtil, dayNameUtil, daysUtil, differenceInDaysUtil, differenceInHoursUtil, differenceInMinutesUtil, differenceInMonthsUtil, differenceInSecondsUtil, differenceInWeeksUtil, differenceInYearsUtil, endOfDayUtil, endOfHourUtil, endOfMinuteUtil, endOfMonthUtil, endOfWeekUtil, formatDateUtil, formatRangeUtil, getDurationFormat, getHourCycle, getTimeZone, getTimeZoneOffset, getUTCFromTimeZonedUtil, getWeekUtil, isBetweenUtil, isEqualUtil, isFutureUtil, isPastUtil, isSameDayUtil, isSameMonthUtil, isSameWeekUtil, isSameYearUtil, isTodayUtil, isValidDate, monthNameUtil, monthsUtil, parseValidDate, startOfDayUtil, startOfHourUtil, startOfMinuteUtil, startOfMonthUtil, startOfWeekUtil, subtractDaysUtil, subtractHoursUtil, subtractMinutesUtil, subtractMonthsUtil, subtractWeeksUtil, subtractYearsUtil, timeSinceAuto, timeSinceInDays, timeSinceInHours, timeSinceInMinutes, timeSinceInMonths, timeSinceInSeconds, timeSinceInYears, timeZonesAvailable, toDateUtil, toDuration, toInstantUtil, toTemporalUtil, toZonedDateTimeUtil };
+export { addDaysUtil, addHoursUtil, addMinutesUtil, addMonthsUtil, addWeeksUtil, addYearsUtil, convertHoursUtil, convertMillisecondsUtil, convertMinutesUtil, convertSecondsUtil, dayNameUtil, daysUtil, differenceInDaysUtil, differenceInHoursUtil, differenceInMinutesUtil, differenceInMonthsUtil, differenceInSecondsUtil, differenceInWeeksUtil, differenceInYearsUtil, endOfDayUtil, endOfHourUtil, endOfMinuteUtil, endOfMonthUtil, endOfWeekUtil, formatDateUtil, formatRangeUtil, getDurationFormat, getHourCycle, getTimeZone, getTimeZoneOffset, getUTCFromTimeZonedUtil, getWeekUtil, isBetweenUtil, isEqualUtil, isFutureUtil, isPastUtil, isSameDayUtil, isSameMonthUtil, isSameWeekUtil, isSameYearUtil, isTodayUtil, isValidDate, monthNameUtil, monthsUtil, parseValidDate, startOfDayUtil, startOfHourUtil, startOfMinuteUtil, startOfMonthUtil, startOfWeekUtil, subtractDaysUtil, subtractHoursUtil, subtractMinutesUtil, subtractMonthsUtil, subtractWeeksUtil, subtractYearsUtil, timeFormatToHourCycle, timeSinceAuto, timeSinceInDays, timeSinceInHours, timeSinceInMinutes, timeSinceInMonths, timeSinceInSeconds, timeSinceInYears, timeZonesAvailable, toDateUtil, toDuration, toInstantUtil, toTemporalUtil, toZonedDateTimeUtil };

package/package.json

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

package/src/DateAndTimeUtils.d.ts

@@ -40,9 +40,23 @@ export declare const getTimeZoneOffset: (timeZone: string) => string;
  */
 export declare const timeZonesAvailable: string[];
 /**
- * Return the most probable hour cycle based on the locale
+ * Maps a user "time format" preference onto an `Intl` hour cycle.
+ *
+ * Returns `undefined` for "language default" (or no preference) so callers fall back to the
+ * locale-derived hour cycle. A 12-hour preference resolves to `h12` and 24-hour to `h23`.
+ *
+ * @param timeFormat - The user's time format preference (`"LANGUAGE_DEFAULT" | "TWELVE_HOUR" | "TWENTY_FOUR_HOUR"`).
+ * @returns {Intl.LocaleHourCycleKey | undefined} The forced hour cycle, or `undefined` to let the locale decide.
+ */
+export declare const timeFormatToHourCycle: (timeFormat?: "LANGUAGE_DEFAULT" | "TWELVE_HOUR" | "TWENTY_FOUR_HOUR" | null) => Intl.LocaleHourCycleKey | undefined;
+/**
+ * Return the most probable hour cycle based on the locale.
+ *
+ * @param locale - The locale used to derive the hour cycle.
+ * @param hourCycleOverride - When provided, takes precedence over the locale-derived hour cycle.
+ *   Used to honor an explicit user time-format preference (12H/24H).
  */
-export declare const getHourCycle: (locale?: string) => Intl.LocaleHourCycleKey;
+export declare const getHourCycle: (locale?: string, hourCycleOverride?: Intl.LocaleHourCycleKey) => Intl.LocaleHourCycleKey;
 /**
  * Formats a temporal date according to the specified format, time zone, and locale.
  *
@@ -50,6 +64,8 @@ export declare const getHourCycle: (locale?: string) => Intl.LocaleHourCycleKey;
  * @param {TemporalFormat} [format] - The format options for the date and/or time. If not provided, default format options will be used.
  * @param {string} [timeZone] - The time zone to use for formatting. If not provided, the system's default time zone will be used.
  * @param {string} [locale] - The locale to use for formatting. If not provided, the system's default locale will be used.
+ * @param {Intl.LocaleHourCycleKey} [hourCycleOverride] - Forces a specific hour cycle (e.g. `h12`/`h23`) regardless of locale.
+ *   Used to honor an explicit user time-format preference. When omitted, the locale decides.
  * @returns {string} The formatted date string.
  * @example
  * const dateString = "2023-05-10"
@@ -83,7 +99,7 @@ export declare const getHourCycle: (locale?: string) => Intl.LocaleHourCycleKey;
  * const formattedDate = formatDateUtil(date, format, timeZone, locale);
  * Output: "5/10/23, 12:00:00 AM EDT"
  */
-export declare const formatDateUtil: (date: TemporalDate, format?: TemporalFormat, timeZone?: string, locale?: string) => string;
+export declare const formatDateUtil: (date: TemporalDate, format?: TemporalFormat, timeZone?: string, locale?: string, hourCycleOverride?: Intl.LocaleHourCycleKey) => string;
 /**
  * Formats a date range.
  *