@trackunit/date-and-time-utils 0.0.48 → 0.0.49

package/index.cjs.js

@@ -77,7 +77,7 @@ const timeZonesAvailable = !intlEnumerator.shouldPolyfill()
  * const formattedDate = formatDateUtil(date, format, timeZone, locale);
  * Output: "5/10/23, 12:00:00 AM EDT"
  */
-const formatDateUtil = (date, format, timeZone, locale) => {
+const formatDateUtil = (date, format, timeZone, locale, hourCycle) => {
     var _a, _b, _c, _d, _e, _f;
     const dateObj = timeZone ? toZonedDateTimeUtil(date, timeZone) : toTemporalUtil(toDateUtil(date));
     if ((format === null || format === void 0 ? void 0 : format.selectFormat) === "dateOnly") {
@@ -88,21 +88,25 @@ const formatDateUtil = (date, format, timeZone, locale) => {
         }
         return dateObj.toLocaleString(locale, {
             dateStyle: (_b = format.dateFormat) !== null && _b !== void 0 ? _b : "medium",
+            hourCycle: hourCycle !== null && hourCycle !== void 0 ? hourCycle : "h12",
         });
     }
     if ((format === null || format === void 0 ? void 0 : format.selectFormat) === "timeOnly") {
         if (dateObj instanceof polyfill.Temporal.ZonedDateTime) {
             return dateObj.toPlainTime().toLocaleString(locale, {
                 timeStyle: (_c = format.timeFormat) !== null && _c !== void 0 ? _c : "short",
+                hourCycle: hourCycle !== null && hourCycle !== void 0 ? hourCycle : "h12",
             });
         }
         return dateObj.toLocaleString(locale, {
             timeStyle: (_d = format.timeFormat) !== null && _d !== void 0 ? _d : "short",
+            hourCycle: hourCycle !== null && hourCycle !== void 0 ? hourCycle : "h12",
         });
     }
     return dateObj.toLocaleString(locale, {
         dateStyle: (_e = format === null || format === void 0 ? void 0 : format.dateFormat) !== null && _e !== void 0 ? _e : "medium",
         timeStyle: (_f = format === null || format === void 0 ? void 0 : format.timeFormat) !== null && _f !== void 0 ? _f : "short",
+        hourCycle: hourCycle !== null && hourCycle !== void 0 ? hourCycle : "h12",
     });
 };
 /**
@@ -412,7 +416,7 @@ const startOfDayUtil = (date, timeZone) => {
  * Output: Temporal.ZonedDateTime { year: 2023, month: 5, day: 10, hour: 23, minute: 59, second: 59, millisecond: 999, microsecond: 0, nanosecond: 0, timeZone: Temporal.TimeZone { id: "America/New_York" }, calendar: Temporal.Calendar { id: "iso8601" } }
  */
 const endOfDayUtil = (date, timeZone) => {
-    const day = toZonedDateTimeUtil(date, timeZone).startOfDay().subtract({ seconds: 1 });
+    const day = toZonedDateTimeUtil(date, timeZone).startOfDay().subtract({ milliseconds: 1 });
     return addDaysUtil(day, 1);
 };
 /**
@@ -442,10 +446,10 @@ const startOfWeekUtil = (date, timeZone) => {
  * const dateString = "2023-05-10T10:30:00.000Z"
  * const date = new Date(dateString);
  * const result = startOfWeekUtil(date);
- * Output: Temporal.ZonedDateTime { year: 2023, month: 5, day: 14, hour: 0, minute: 0, second: 0, millisecond: 0, microsecond: 0, nanosecond: 0, timeZone: Temporal.TimeZone { id: "America/New_York" }, calendar: Temporal.Calendar { id: "iso8601" } }
+ * Output: Temporal.ZonedDateTime { year: 2023, month: 5, day: 14, hour: 23, minute: 59, second: 59, millisecond: 999, microsecond: 0, nanosecond: 0, timeZone: Temporal.TimeZone { id: "America/New_York" }, calendar: Temporal.Calendar { id: "iso8601" } }
  */
 const endOfWeekUtil = (date, timeZone) => {
-    const day = toZonedDateTimeUtil(date, timeZone).startOfDay();
+    const day = endOfDayUtil(toZonedDateTimeUtil(date, timeZone));
     const currentDay = day.dayOfWeek;
     const totalDays = day.daysInWeek;
     return addDaysUtil(day, totalDays - currentDay);
@@ -477,14 +481,47 @@ const startOfMonthUtil = (date, timeZone) => {
  * const dateString = "2023-05-10"
  * const date = new Date(dateString);
  * const result = endOfMonthUtil(date);
- * Output: Temporal.ZonedDateTime { year: 2023, month: 5, day: 31, hour: 0, minute: 0, second: 0, millisecond: 0, microsecond: 0, nanosecond: 0, timeZone: Temporal.TimeZone { id: "America/New_York" }, calendar: Temporal.Calendar { id: "iso8601" } }
+ * Output: Temporal.ZonedDateTime { year: 2023, month: 5, day: 31, hour: 23, minute: 59, second: 59, millisecond: 999, microsecond: 0, nanosecond: 0, timeZone: Temporal.TimeZone { id: "America/New_York" }, calendar: Temporal.Calendar { id: "iso8601" } }
  */
 const endOfMonthUtil = (date, timeZone) => {
-    const day = toZonedDateTimeUtil(date, timeZone).startOfDay();
+    const day = endOfDayUtil(toZonedDateTimeUtil(date, timeZone));
     const currentDay = day.day;
     const totalDays = day.daysInMonth;
     return addDaysUtil(day, totalDays - currentDay);
 };
+/**
+ * Calculates the difference in seconds between two dates.
+ *
+ * @param {TemporalDate} from - The starting date.
+ * @param {TemporalDate} to - The ending date.
+ * @returns {number} The difference in seconds between the two dates.
+ * @example
+ * const dateString = "2023-05-10T10:30:00.000Z"
+ * const fromDate = new Date(dateString);
+ * const toDate = new Date(dateString);
+ * const result = differenceInSecondsUtil(fromDate, toDate);
+ * Output: 0 (if fromDate and toDate are the same)
+ * @example
+ * const dateString1 = "2023-05-10T10:30:00.000Z"
+ * const dateString2 = "2023-05-10T10:35:00.000Z"
+ * const fromDate = new Date(dateString1);
+ * const toDate = new Date(dateString2);
+ * const result = differenceInSecondsUtil(fromDate, toDate);
+ * Output: 5
+ */
+const differenceInSecondsUtil = (from, to) => {
+    let until = new polyfill.Temporal.Duration();
+    try {
+        until = toZonedDateTimeUtil(from).toPlainTime().until(toZonedDateTimeUtil(to).toPlainTime(), {
+            largestUnit: "seconds",
+        });
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.warn("Error: ", error);
+    }
+    return until.seconds;
+};
 /**
  * Calculates the difference in minutes between two dates.
  *
@@ -620,6 +657,40 @@ const differenceInWeeksUtil = (from, to) => {
     }
     return until.weeks;
 };
+/**
+ * Calculates the difference in years between two dates.
+ *
+ * @param {TemporalDate} from - The starting date.
+ * @param {TemporalDate} to - The ending date.
+ * @returns {number} The difference in years between the two dates.
+ * @example
+ * const dateString1 = "2023-05-10"
+ * const dateString2 = "2023-05-12"
+ * const fromDate = new Date(dateString1);
+ * const toDate = new Date(dateString2);
+ * const result = differenceInYearsUtil(fromDate, toDate);
+ * Output: 0 (if fromDate and toDate are in the same year)
+ * @example
+ * const dateString1 = "2023-05-10"
+ * const dateString2 = "2025-05-18"
+ * const fromDate = new Date(dateString1);
+ * const toDate = new Date(dateString2);
+ * const result = differenceInWeeksUtil(fromDate, toDate);
+ * Output: 2
+ */
+const differenceInYearsUtil = (from, to) => {
+    let until = new polyfill.Temporal.Duration();
+    try {
+        until = toZonedDateTimeUtil(from).toPlainDate().until(toZonedDateTimeUtil(to).toPlainDate(), {
+            largestUnit: "year",
+        });
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.warn("Error: ", error);
+    }
+    return until.years;
+};
 /**
  * Calculates the difference in months between two dates.
  *
@@ -1064,7 +1135,7 @@ const getDurationFormat = (duration, locale, format) => {
  * convert a number to a type
  *
  * @param {number} number - 230.45
- * @param {TemporalTimeTypes} unit - "days | "hours" | minutes
+ * @param {TemporalTimeTypes} unit - "days | "hours" | "minutes" | "seconds"
  * @param {Temporal.TimeUnit} roundAt - smallest unit to show
  */
 const toDuration = (number, unit, roundAt) => {
@@ -1079,6 +1150,8 @@ const toDuration = (number, unit, roundAt) => {
             return polyfill.Temporal.Duration.from(durationBuilder(number, "minutes")).round({
                 smallestUnit: roundAt !== null && roundAt !== void 0 ? roundAt : "seconds",
             });
+        case "seconds":
+            return polyfill.Temporal.Duration.from(durationBuilder(number, "seconds")).round({ smallestUnit: roundAt !== null && roundAt !== void 0 ? roundAt : "seconds" });
         default:
             throw new Error("Not a valid unit", { cause: unit });
     }
@@ -1088,7 +1161,7 @@ const defaultDuration = { days: 0, hours: 0, minutes: 0, seconds: 0 };
  * Build a duration string
  *
  * @param number - number to convert
- * @param unit - "days | "hours" | minutes
+ * @param unit - "days | "hours" | "minutes" | "seconds"
  */
 const durationBuilder = (number, unit) => {
     const isSigned = Math.sign(number) === -1;
@@ -1112,6 +1185,11 @@ const durationBuilder = (number, unit) => {
                 return `${sign}PT${unsignedNumber}M`;
             }
             return `${sign}PT${minutes}M${seconds}S`;
+        case "seconds":
+            if (isInt) {
+                return `${sign}PT${unsignedNumber}S`;
+            }
+            return `${sign}PT${seconds}S`;
         default:
             return `PT0S`;
     }
@@ -1120,7 +1198,7 @@ const durationBuilder = (number, unit) => {
  * Calculate time in days, hours, minutes, and seconds
  *
  * @param {number} number - number to convert
- * @param {TemporalTimeTypes} unit - "days | "hours" | minutes
+ * @param {TemporalTimeTypes} unit - "days | "hours" | "minutes" | "seconds"
  */
 const calculateTime = (number, unit) => {
     switch (unit) {
@@ -1365,6 +1443,143 @@ const daysUtil = (format, locale) => {
     }
     return days;
 };
+/**
+ * Returns the UTC date-time for the given time zone.
+ *
+ * @param {Date} from - The date to convert to UTC.
+ * @param {string} timeZoneId - The time zone of the input date.
+ */
+const getUTCFromTimeZonedUtil = (from, timeZoneId) => {
+    const zonedDateTime = toZonedDateTimeUtil(from, timeZoneId);
+    return toDateUtil(zonedDateTime.toInstant().toZonedDateTimeISO("UTC"));
+};
+/**
+ * @name getWeekUtil
+ * @summary Get the local week index of the given date.
+ * @description
+ * Get the local week index of the given date using Temporal.
+ * The exact calculation depends on the values of `weekStartsOn` (the index of the first day of the week)
+ * and `firstWeekContainsDate` (the day in January, which is always in the first week of the week-numbering year).
+ * @param {Temporal.PlainDate | Date | string} date - The given date (can be either Temporal.PlainDate, a native Date, or an ISO date string).
+ * @param {GetWeekUtilOptions} [options] - Optional settings for the week calculation.
+ * @returns {number} - The week number of the year.
+ * @example
+ * // Which week of the local week numbering year is 2 January 2005 with default options?
+ * const result = getWeekUtil(new Date(2005, 0, 2))
+ * //=> 2
+ * @example
+ * // Which week of the local week numbering year is 2 January 2005, if Monday is the first day of the week,
+ * // and the first week of the year always contains 4 January?
+ * const result = getWeekUtil("2005-01-02T00:00:00.000Z", {
+ *   weekStartsOn: 1,
+ *   firstWeekContainsDate: 4
+ * })
+ * //=> 53
+ */
+const getWeekUtil = (date, options) => {
+    const _date = convertToPlainDate(date);
+    const { weekStartsOn = 0, firstWeekContainsDate = 1 } = options || {};
+    const startOfCurrentWeek = startOfWeek(_date, weekStartsOn);
+    const startOfWeekYear = startOfWeek(polyfill.Temporal.PlainDate.from({
+        year: _date.year,
+        month: 1,
+        day: firstWeekContainsDate,
+    }), weekStartsOn);
+    const diffInDays = startOfCurrentWeek.since(startOfWeekYear).total({ unit: "days" });
+    return Math.floor(diffInDays / 7) + 1;
+};
+/**
+ * @name convertMillisecondsUtil
+ * @summary Convert milliseconds using Temporal.
+ * @description
+ * Convert milliseconds to the specified unit using Temporal.
+ * @param {number} milliseconds - The number of milliseconds to convert.
+ * @returns {number} - The converted value.
+ * @example
+ * const result = convertMillisecondsUtil(60000, "minute")
+ * //=> 1
+ * @example
+ * const result = convertMillisecondsUtil(120000, "second")
+ * //=> 120
+ * @example
+ * const result = convertMillisecondsUtil(3600000, "hour")
+ * //=> 1
+ */
+const convertMillisecondsUtil = (milliseconds, unit) => {
+    return polyfill.Temporal.Duration.from({ milliseconds }).total({ unit });
+};
+/**
+ * @name convertSecondsUtil
+ * @summary Convert seconds using Temporal.
+ * @description
+ * Convert seconds to the specified unit using Temporal.
+ * @param {number} seconds - The number of seconds to convert.
+ * @returns {number} - The converted value.
+ * @example
+ * const result = convertSecondsUtil(60, "minute")
+ * //=> 1
+ * @example
+ * const result = convertSecondsUtil(120, "second")
+ * //=> 120
+ */
+const convertSecondsUtil = (seconds, unit) => {
+    return polyfill.Temporal.Duration.from({ seconds }).total({ unit });
+};
+/**
+ * @name convertMinutesUtil
+ * @summary Convert seconds using Temporal.
+ * @description
+ * Convert minutes to the specified unit using Temporal.
+ * @param {number} minutes - The number of minutes to convert.
+ * @returns {number} - The converted value.
+ * @example
+ * const result = convertMinutesUtil(60, "minute")
+ * //=> 1
+ * @example
+ * const result = convertMinutesUtil(120, "second")
+ * //=> 120
+ */
+const convertMinutesUtil = (minutes, unit) => {
+    return polyfill.Temporal.Duration.from({ minutes }).total({ unit });
+};
+/**
+ * @name convertHoursUtil
+ * @summary Convert hours using Temporal.
+ * @description
+ * Convert hours to the specified unit using Temporal.
+ * @param {number} hours - The number of hours to convert.
+ * @returns {number} - The converted value.
+ * @example
+ * const result = convertHoursUtil(24, "day")
+ * //=> 1
+ * @example
+ * const result = convertHoursUtil(48, "hour")
+ * //=> 48
+ */
+const convertHoursUtil = (hours, unit) => {
+    return polyfill.Temporal.Duration.from({ hours }).total({ unit });
+};
+const convertToPlainDate = (date) => {
+    if (date instanceof polyfill.Temporal.PlainDate) {
+        return date;
+    }
+    if (typeof date === "string") {
+        return polyfill.Temporal.PlainDate.from(date);
+    }
+    if (date instanceof Date) {
+        const dateString = date.toISOString().split("T")[0];
+        if (!dateString) {
+            throw new Error("Invalid Date object. Cannot convert to Temporal.PlainDate.");
+        }
+        return polyfill.Temporal.PlainDate.from(dateString);
+    }
+    throw new Error("Unsupported date format. Please provide a Temporal.PlainDate, Date, or ISO string.");
+};
+const startOfWeek = (date, weekStartsOn) => {
+    const dayOfWeek = date.dayOfWeek;
+    const diff = (dayOfWeek - weekStartsOn + 7) % 7;
+    return date.subtract({ days: diff });
+};
 
 exports.addDaysUtil = addDaysUtil;
 exports.addHoursUtil = addHoursUtil;
@@ -1372,13 +1587,19 @@ exports.addMinutesUtil = addMinutesUtil;
 exports.addMonthsUtil = addMonthsUtil;
 exports.addWeeksUtil = addWeeksUtil;
 exports.addYearsUtil = addYearsUtil;
+exports.convertHoursUtil = convertHoursUtil;
+exports.convertMillisecondsUtil = convertMillisecondsUtil;
+exports.convertMinutesUtil = convertMinutesUtil;
+exports.convertSecondsUtil = convertSecondsUtil;
 exports.dayNameUtil = dayNameUtil;
 exports.daysUtil = daysUtil;
 exports.differenceInDaysUtil = differenceInDaysUtil;
 exports.differenceInHoursUtil = differenceInHoursUtil;
 exports.differenceInMinutesUtil = differenceInMinutesUtil;
 exports.differenceInMonthsUtil = differenceInMonthsUtil;
+exports.differenceInSecondsUtil = differenceInSecondsUtil;
 exports.differenceInWeeksUtil = differenceInWeeksUtil;
+exports.differenceInYearsUtil = differenceInYearsUtil;
 exports.endOfDayUtil = endOfDayUtil;
 exports.endOfHourUtil = endOfHourUtil;
 exports.endOfMinuteUtil = endOfMinuteUtil;
@@ -1389,6 +1610,8 @@ exports.formatRangeUtil = formatRangeUtil;
 exports.getDurationFormat = getDurationFormat;
 exports.getTimeZone = getTimeZone;
 exports.getTimeZoneOffset = getTimeZoneOffset;
+exports.getUTCFromTimeZonedUtil = getUTCFromTimeZonedUtil;
+exports.getWeekUtil = getWeekUtil;
 exports.isBetweenUtil = isBetweenUtil;
 exports.isEqualUtil = isEqualUtil;
 exports.isFutureUtil = isFutureUtil;

package/index.esm.js

@@ -75,7 +75,7 @@ const timeZonesAvailable = !shouldPolyfill()
  * const formattedDate = formatDateUtil(date, format, timeZone, locale);
  * Output: "5/10/23, 12:00:00 AM EDT"
  */
-const formatDateUtil = (date, format, timeZone, locale) => {
+const formatDateUtil = (date, format, timeZone, locale, hourCycle) => {
     var _a, _b, _c, _d, _e, _f;
     const dateObj = timeZone ? toZonedDateTimeUtil(date, timeZone) : toTemporalUtil(toDateUtil(date));
     if ((format === null || format === void 0 ? void 0 : format.selectFormat) === "dateOnly") {
@@ -86,21 +86,25 @@ const formatDateUtil = (date, format, timeZone, locale) => {
         }
         return dateObj.toLocaleString(locale, {
             dateStyle: (_b = format.dateFormat) !== null && _b !== void 0 ? _b : "medium",
+            hourCycle: hourCycle !== null && hourCycle !== void 0 ? hourCycle : "h12",
         });
     }
     if ((format === null || format === void 0 ? void 0 : format.selectFormat) === "timeOnly") {
         if (dateObj instanceof Temporal.ZonedDateTime) {
             return dateObj.toPlainTime().toLocaleString(locale, {
                 timeStyle: (_c = format.timeFormat) !== null && _c !== void 0 ? _c : "short",
+                hourCycle: hourCycle !== null && hourCycle !== void 0 ? hourCycle : "h12",
             });
         }
         return dateObj.toLocaleString(locale, {
             timeStyle: (_d = format.timeFormat) !== null && _d !== void 0 ? _d : "short",
+            hourCycle: hourCycle !== null && hourCycle !== void 0 ? hourCycle : "h12",
         });
     }
     return dateObj.toLocaleString(locale, {
         dateStyle: (_e = format === null || format === void 0 ? void 0 : format.dateFormat) !== null && _e !== void 0 ? _e : "medium",
         timeStyle: (_f = format === null || format === void 0 ? void 0 : format.timeFormat) !== null && _f !== void 0 ? _f : "short",
+        hourCycle: hourCycle !== null && hourCycle !== void 0 ? hourCycle : "h12",
     });
 };
 /**
@@ -410,7 +414,7 @@ const startOfDayUtil = (date, timeZone) => {
  * Output: Temporal.ZonedDateTime { year: 2023, month: 5, day: 10, hour: 23, minute: 59, second: 59, millisecond: 999, microsecond: 0, nanosecond: 0, timeZone: Temporal.TimeZone { id: "America/New_York" }, calendar: Temporal.Calendar { id: "iso8601" } }
  */
 const endOfDayUtil = (date, timeZone) => {
-    const day = toZonedDateTimeUtil(date, timeZone).startOfDay().subtract({ seconds: 1 });
+    const day = toZonedDateTimeUtil(date, timeZone).startOfDay().subtract({ milliseconds: 1 });
     return addDaysUtil(day, 1);
 };
 /**
@@ -440,10 +444,10 @@ const startOfWeekUtil = (date, timeZone) => {
  * const dateString = "2023-05-10T10:30:00.000Z"
  * const date = new Date(dateString);
  * const result = startOfWeekUtil(date);
- * Output: Temporal.ZonedDateTime { year: 2023, month: 5, day: 14, hour: 0, minute: 0, second: 0, millisecond: 0, microsecond: 0, nanosecond: 0, timeZone: Temporal.TimeZone { id: "America/New_York" }, calendar: Temporal.Calendar { id: "iso8601" } }
+ * Output: Temporal.ZonedDateTime { year: 2023, month: 5, day: 14, hour: 23, minute: 59, second: 59, millisecond: 999, microsecond: 0, nanosecond: 0, timeZone: Temporal.TimeZone { id: "America/New_York" }, calendar: Temporal.Calendar { id: "iso8601" } }
  */
 const endOfWeekUtil = (date, timeZone) => {
-    const day = toZonedDateTimeUtil(date, timeZone).startOfDay();
+    const day = endOfDayUtil(toZonedDateTimeUtil(date, timeZone));
     const currentDay = day.dayOfWeek;
     const totalDays = day.daysInWeek;
     return addDaysUtil(day, totalDays - currentDay);
@@ -475,14 +479,47 @@ const startOfMonthUtil = (date, timeZone) => {
  * const dateString = "2023-05-10"
  * const date = new Date(dateString);
  * const result = endOfMonthUtil(date);
- * Output: Temporal.ZonedDateTime { year: 2023, month: 5, day: 31, hour: 0, minute: 0, second: 0, millisecond: 0, microsecond: 0, nanosecond: 0, timeZone: Temporal.TimeZone { id: "America/New_York" }, calendar: Temporal.Calendar { id: "iso8601" } }
+ * Output: Temporal.ZonedDateTime { year: 2023, month: 5, day: 31, hour: 23, minute: 59, second: 59, millisecond: 999, microsecond: 0, nanosecond: 0, timeZone: Temporal.TimeZone { id: "America/New_York" }, calendar: Temporal.Calendar { id: "iso8601" } }
  */
 const endOfMonthUtil = (date, timeZone) => {
-    const day = toZonedDateTimeUtil(date, timeZone).startOfDay();
+    const day = endOfDayUtil(toZonedDateTimeUtil(date, timeZone));
     const currentDay = day.day;
     const totalDays = day.daysInMonth;
     return addDaysUtil(day, totalDays - currentDay);
 };
+/**
+ * Calculates the difference in seconds between two dates.
+ *
+ * @param {TemporalDate} from - The starting date.
+ * @param {TemporalDate} to - The ending date.
+ * @returns {number} The difference in seconds between the two dates.
+ * @example
+ * const dateString = "2023-05-10T10:30:00.000Z"
+ * const fromDate = new Date(dateString);
+ * const toDate = new Date(dateString);
+ * const result = differenceInSecondsUtil(fromDate, toDate);
+ * Output: 0 (if fromDate and toDate are the same)
+ * @example
+ * const dateString1 = "2023-05-10T10:30:00.000Z"
+ * const dateString2 = "2023-05-10T10:35:00.000Z"
+ * const fromDate = new Date(dateString1);
+ * const toDate = new Date(dateString2);
+ * const result = differenceInSecondsUtil(fromDate, toDate);
+ * Output: 5
+ */
+const differenceInSecondsUtil = (from, to) => {
+    let until = new Temporal.Duration();
+    try {
+        until = toZonedDateTimeUtil(from).toPlainTime().until(toZonedDateTimeUtil(to).toPlainTime(), {
+            largestUnit: "seconds",
+        });
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.warn("Error: ", error);
+    }
+    return until.seconds;
+};
 /**
  * Calculates the difference in minutes between two dates.
  *
@@ -618,6 +655,40 @@ const differenceInWeeksUtil = (from, to) => {
     }
     return until.weeks;
 };
+/**
+ * Calculates the difference in years between two dates.
+ *
+ * @param {TemporalDate} from - The starting date.
+ * @param {TemporalDate} to - The ending date.
+ * @returns {number} The difference in years between the two dates.
+ * @example
+ * const dateString1 = "2023-05-10"
+ * const dateString2 = "2023-05-12"
+ * const fromDate = new Date(dateString1);
+ * const toDate = new Date(dateString2);
+ * const result = differenceInYearsUtil(fromDate, toDate);
+ * Output: 0 (if fromDate and toDate are in the same year)
+ * @example
+ * const dateString1 = "2023-05-10"
+ * const dateString2 = "2025-05-18"
+ * const fromDate = new Date(dateString1);
+ * const toDate = new Date(dateString2);
+ * const result = differenceInWeeksUtil(fromDate, toDate);
+ * Output: 2
+ */
+const differenceInYearsUtil = (from, to) => {
+    let until = new Temporal.Duration();
+    try {
+        until = toZonedDateTimeUtil(from).toPlainDate().until(toZonedDateTimeUtil(to).toPlainDate(), {
+            largestUnit: "year",
+        });
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.warn("Error: ", error);
+    }
+    return until.years;
+};
 /**
  * Calculates the difference in months between two dates.
  *
@@ -1062,7 +1133,7 @@ const getDurationFormat = (duration, locale, format) => {
  * convert a number to a type
  *
  * @param {number} number - 230.45
- * @param {TemporalTimeTypes} unit - "days | "hours" | minutes
+ * @param {TemporalTimeTypes} unit - "days | "hours" | "minutes" | "seconds"
  * @param {Temporal.TimeUnit} roundAt - smallest unit to show
  */
 const toDuration = (number, unit, roundAt) => {
@@ -1077,6 +1148,8 @@ const toDuration = (number, unit, roundAt) => {
             return Temporal.Duration.from(durationBuilder(number, "minutes")).round({
                 smallestUnit: roundAt !== null && roundAt !== void 0 ? roundAt : "seconds",
             });
+        case "seconds":
+            return Temporal.Duration.from(durationBuilder(number, "seconds")).round({ smallestUnit: roundAt !== null && roundAt !== void 0 ? roundAt : "seconds" });
         default:
             throw new Error("Not a valid unit", { cause: unit });
     }
@@ -1086,7 +1159,7 @@ const defaultDuration = { days: 0, hours: 0, minutes: 0, seconds: 0 };
  * Build a duration string
  *
  * @param number - number to convert
- * @param unit - "days | "hours" | minutes
+ * @param unit - "days | "hours" | "minutes" | "seconds"
  */
 const durationBuilder = (number, unit) => {
     const isSigned = Math.sign(number) === -1;
@@ -1110,6 +1183,11 @@ const durationBuilder = (number, unit) => {
                 return `${sign}PT${unsignedNumber}M`;
             }
             return `${sign}PT${minutes}M${seconds}S`;
+        case "seconds":
+            if (isInt) {
+                return `${sign}PT${unsignedNumber}S`;
+            }
+            return `${sign}PT${seconds}S`;
         default:
             return `PT0S`;
     }
@@ -1118,7 +1196,7 @@ const durationBuilder = (number, unit) => {
  * Calculate time in days, hours, minutes, and seconds
  *
  * @param {number} number - number to convert
- * @param {TemporalTimeTypes} unit - "days | "hours" | minutes
+ * @param {TemporalTimeTypes} unit - "days | "hours" | "minutes" | "seconds"
  */
 const calculateTime = (number, unit) => {
     switch (unit) {
@@ -1363,5 +1441,142 @@ const daysUtil = (format, locale) => {
     }
     return days;
 };
+/**
+ * Returns the UTC date-time for the given time zone.
+ *
+ * @param {Date} from - The date to convert to UTC.
+ * @param {string} timeZoneId - The time zone of the input date.
+ */
+const getUTCFromTimeZonedUtil = (from, timeZoneId) => {
+    const zonedDateTime = toZonedDateTimeUtil(from, timeZoneId);
+    return toDateUtil(zonedDateTime.toInstant().toZonedDateTimeISO("UTC"));
+};
+/**
+ * @name getWeekUtil
+ * @summary Get the local week index of the given date.
+ * @description
+ * Get the local week index of the given date using Temporal.
+ * The exact calculation depends on the values of `weekStartsOn` (the index of the first day of the week)
+ * and `firstWeekContainsDate` (the day in January, which is always in the first week of the week-numbering year).
+ * @param {Temporal.PlainDate | Date | string} date - The given date (can be either Temporal.PlainDate, a native Date, or an ISO date string).
+ * @param {GetWeekUtilOptions} [options] - Optional settings for the week calculation.
+ * @returns {number} - The week number of the year.
+ * @example
+ * // Which week of the local week numbering year is 2 January 2005 with default options?
+ * const result = getWeekUtil(new Date(2005, 0, 2))
+ * //=> 2
+ * @example
+ * // Which week of the local week numbering year is 2 January 2005, if Monday is the first day of the week,
+ * // and the first week of the year always contains 4 January?
+ * const result = getWeekUtil("2005-01-02T00:00:00.000Z", {
+ *   weekStartsOn: 1,
+ *   firstWeekContainsDate: 4
+ * })
+ * //=> 53
+ */
+const getWeekUtil = (date, options) => {
+    const _date = convertToPlainDate(date);
+    const { weekStartsOn = 0, firstWeekContainsDate = 1 } = options || {};
+    const startOfCurrentWeek = startOfWeek(_date, weekStartsOn);
+    const startOfWeekYear = startOfWeek(Temporal.PlainDate.from({
+        year: _date.year,
+        month: 1,
+        day: firstWeekContainsDate,
+    }), weekStartsOn);
+    const diffInDays = startOfCurrentWeek.since(startOfWeekYear).total({ unit: "days" });
+    return Math.floor(diffInDays / 7) + 1;
+};
+/**
+ * @name convertMillisecondsUtil
+ * @summary Convert milliseconds using Temporal.
+ * @description
+ * Convert milliseconds to the specified unit using Temporal.
+ * @param {number} milliseconds - The number of milliseconds to convert.
+ * @returns {number} - The converted value.
+ * @example
+ * const result = convertMillisecondsUtil(60000, "minute")
+ * //=> 1
+ * @example
+ * const result = convertMillisecondsUtil(120000, "second")
+ * //=> 120
+ * @example
+ * const result = convertMillisecondsUtil(3600000, "hour")
+ * //=> 1
+ */
+const convertMillisecondsUtil = (milliseconds, unit) => {
+    return Temporal.Duration.from({ milliseconds }).total({ unit });
+};
+/**
+ * @name convertSecondsUtil
+ * @summary Convert seconds using Temporal.
+ * @description
+ * Convert seconds to the specified unit using Temporal.
+ * @param {number} seconds - The number of seconds to convert.
+ * @returns {number} - The converted value.
+ * @example
+ * const result = convertSecondsUtil(60, "minute")
+ * //=> 1
+ * @example
+ * const result = convertSecondsUtil(120, "second")
+ * //=> 120
+ */
+const convertSecondsUtil = (seconds, unit) => {
+    return Temporal.Duration.from({ seconds }).total({ unit });
+};
+/**
+ * @name convertMinutesUtil
+ * @summary Convert seconds using Temporal.
+ * @description
+ * Convert minutes to the specified unit using Temporal.
+ * @param {number} minutes - The number of minutes to convert.
+ * @returns {number} - The converted value.
+ * @example
+ * const result = convertMinutesUtil(60, "minute")
+ * //=> 1
+ * @example
+ * const result = convertMinutesUtil(120, "second")
+ * //=> 120
+ */
+const convertMinutesUtil = (minutes, unit) => {
+    return Temporal.Duration.from({ minutes }).total({ unit });
+};
+/**
+ * @name convertHoursUtil
+ * @summary Convert hours using Temporal.
+ * @description
+ * Convert hours to the specified unit using Temporal.
+ * @param {number} hours - The number of hours to convert.
+ * @returns {number} - The converted value.
+ * @example
+ * const result = convertHoursUtil(24, "day")
+ * //=> 1
+ * @example
+ * const result = convertHoursUtil(48, "hour")
+ * //=> 48
+ */
+const convertHoursUtil = (hours, unit) => {
+    return Temporal.Duration.from({ hours }).total({ unit });
+};
+const convertToPlainDate = (date) => {
+    if (date instanceof Temporal.PlainDate) {
+        return date;
+    }
+    if (typeof date === "string") {
+        return Temporal.PlainDate.from(date);
+    }
+    if (date instanceof Date) {
+        const dateString = date.toISOString().split("T")[0];
+        if (!dateString) {
+            throw new Error("Invalid Date object. Cannot convert to Temporal.PlainDate.");
+        }
+        return Temporal.PlainDate.from(dateString);
+    }
+    throw new Error("Unsupported date format. Please provide a Temporal.PlainDate, Date, or ISO string.");
+};
+const startOfWeek = (date, weekStartsOn) => {
+    const dayOfWeek = date.dayOfWeek;
+    const diff = (dayOfWeek - weekStartsOn + 7) % 7;
+    return date.subtract({ days: diff });
+};
 
-export { addDaysUtil, addHoursUtil, addMinutesUtil, addMonthsUtil, addWeeksUtil, addYearsUtil, dayNameUtil, daysUtil, differenceInDaysUtil, differenceInHoursUtil, differenceInMinutesUtil, differenceInMonthsUtil, differenceInWeeksUtil, endOfDayUtil, endOfHourUtil, endOfMinuteUtil, endOfMonthUtil, endOfWeekUtil, formatDateUtil, formatRangeUtil, getDurationFormat, getTimeZone, getTimeZoneOffset, isBetweenUtil, isEqualUtil, isFutureUtil, isPastUtil, isSameDayUtil, isSameMonthUtil, isSameWeekUtil, isSameYearUtil, isTodayUtil, monthNameUtil, monthsUtil, 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, getTimeZone, getTimeZoneOffset, getUTCFromTimeZonedUtil, getWeekUtil, isBetweenUtil, isEqualUtil, isFutureUtil, isPastUtil, isSameDayUtil, isSameMonthUtil, isSameWeekUtil, isSameYearUtil, isTodayUtil, monthNameUtil, monthsUtil, startOfDayUtil, startOfHourUtil, startOfMinuteUtil, startOfMonthUtil, startOfWeekUtil, subtractDaysUtil, subtractHoursUtil, subtractMinutesUtil, subtractMonthsUtil, subtractWeeksUtil, subtractYearsUtil, timeSinceAuto, timeSinceInDays, timeSinceInHours, timeSinceInMinutes, timeSinceInMonths, timeSinceInSeconds, timeSinceInYears, timeZonesAvailable, toDateUtil, toDuration, toInstantUtil, toTemporalUtil, toZonedDateTimeUtil };

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@trackunit/date-and-time-utils",
-  "version": "0.0.48",
+  "version": "0.0.49",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=20.x"
   },
   "dependencies": {
-    "@formatjs/intl-enumerator": "^1.4.1",
+    "@formatjs/intl-enumerator": "^1.8.1",
     "@js-temporal/polyfill": "^0.4.4",
-    "@formatjs/intl-durationformat": "^0.2.2"
+    "@formatjs/intl-durationformat": "^0.6.1"
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",

package/src/DateAndTimeUtils.d.ts

@@ -2,8 +2,9 @@ import "@formatjs/intl-durationformat/polyfill";
 import { Temporal } from "@js-temporal/polyfill";
 export type TemporalDate = Temporal.Instant | Temporal.ZonedDateTime | Date;
 type TemporalFormatTypes = Intl.DateTimeFormatOptions;
-type TemporalTimeTypes = Extract<Intl.RelativeTimeFormatUnit, "days" | "hours" | "minutes">;
+type TemporalTimeTypes = Extract<Intl.RelativeTimeFormatUnit, "days" | "hours" | "minutes" | "seconds">;
 type TemporalFormatSelector = "dateOnly" | "timeOnly";
+type HourCycle = "h12" | "h23";
 export type TemporalFormatStyle = Intl.ListFormatStyle;
 export interface DateRange {
     start: Date;
@@ -78,7 +79,7 @@ export declare const timeZonesAvailable: string[];
  * 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, hourCycle?: HourCycle) => string;
 /**
  * Formats a date range.
  *
@@ -369,7 +370,7 @@ export declare const startOfWeekUtil: (date: TemporalDate, timeZone?: string) =>
  * const dateString = "2023-05-10T10:30:00.000Z"
  * const date = new Date(dateString);
  * const result = startOfWeekUtil(date);
- * Output: Temporal.ZonedDateTime { year: 2023, month: 5, day: 14, hour: 0, minute: 0, second: 0, millisecond: 0, microsecond: 0, nanosecond: 0, timeZone: Temporal.TimeZone { id: "America/New_York" }, calendar: Temporal.Calendar { id: "iso8601" } }
+ * Output: Temporal.ZonedDateTime { year: 2023, month: 5, day: 14, hour: 23, minute: 59, second: 59, millisecond: 999, microsecond: 0, nanosecond: 0, timeZone: Temporal.TimeZone { id: "America/New_York" }, calendar: Temporal.Calendar { id: "iso8601" } }
  */
 export declare const endOfWeekUtil: (date: TemporalDate, timeZone?: string) => Temporal.ZonedDateTime;
 /**
@@ -395,9 +396,30 @@ export declare const startOfMonthUtil: (date: TemporalDate, timeZone?: string) =
  * const dateString = "2023-05-10"
  * const date = new Date(dateString);
  * const result = endOfMonthUtil(date);
- * Output: Temporal.ZonedDateTime { year: 2023, month: 5, day: 31, hour: 0, minute: 0, second: 0, millisecond: 0, microsecond: 0, nanosecond: 0, timeZone: Temporal.TimeZone { id: "America/New_York" }, calendar: Temporal.Calendar { id: "iso8601" } }
+ * Output: Temporal.ZonedDateTime { year: 2023, month: 5, day: 31, hour: 23, minute: 59, second: 59, millisecond: 999, microsecond: 0, nanosecond: 0, timeZone: Temporal.TimeZone { id: "America/New_York" }, calendar: Temporal.Calendar { id: "iso8601" } }
  */
 export declare const endOfMonthUtil: (date: TemporalDate, timeZone?: string) => Temporal.ZonedDateTime;
+/**
+ * Calculates the difference in seconds between two dates.
+ *
+ * @param {TemporalDate} from - The starting date.
+ * @param {TemporalDate} to - The ending date.
+ * @returns {number} The difference in seconds between the two dates.
+ * @example
+ * const dateString = "2023-05-10T10:30:00.000Z"
+ * const fromDate = new Date(dateString);
+ * const toDate = new Date(dateString);
+ * const result = differenceInSecondsUtil(fromDate, toDate);
+ * Output: 0 (if fromDate and toDate are the same)
+ * @example
+ * const dateString1 = "2023-05-10T10:30:00.000Z"
+ * const dateString2 = "2023-05-10T10:35:00.000Z"
+ * const fromDate = new Date(dateString1);
+ * const toDate = new Date(dateString2);
+ * const result = differenceInSecondsUtil(fromDate, toDate);
+ * Output: 5
+ */
+export declare const differenceInSecondsUtil: (from: TemporalDate, to: TemporalDate) => number;
 /**
  * Calculates the difference in minutes between two dates.
  *
@@ -485,6 +507,28 @@ export declare const differenceInDaysUtil: (from: TemporalDate, to: TemporalDate
  * Output: 1
  */
 export declare const differenceInWeeksUtil: (from: TemporalDate, to: TemporalDate) => number;
+/**
+ * Calculates the difference in years between two dates.
+ *
+ * @param {TemporalDate} from - The starting date.
+ * @param {TemporalDate} to - The ending date.
+ * @returns {number} The difference in years between the two dates.
+ * @example
+ * const dateString1 = "2023-05-10"
+ * const dateString2 = "2023-05-12"
+ * const fromDate = new Date(dateString1);
+ * const toDate = new Date(dateString2);
+ * const result = differenceInYearsUtil(fromDate, toDate);
+ * Output: 0 (if fromDate and toDate are in the same year)
+ * @example
+ * const dateString1 = "2023-05-10"
+ * const dateString2 = "2025-05-18"
+ * const fromDate = new Date(dateString1);
+ * const toDate = new Date(dateString2);
+ * const result = differenceInWeeksUtil(fromDate, toDate);
+ * Output: 2
+ */
+export declare const differenceInYearsUtil: (from: TemporalDate, to: TemporalDate) => number;
 /**
  * Calculates the difference in months between two dates.
  *
@@ -754,7 +798,7 @@ export declare const getDurationFormat: (duration: Intl.Duration, locale?: strin
  * convert a number to a type
  *
  * @param {number} number - 230.45
- * @param {TemporalTimeTypes} unit - "days | "hours" | minutes
+ * @param {TemporalTimeTypes} unit - "days | "hours" | "minutes" | "seconds"
  * @param {Temporal.TimeUnit} roundAt - smallest unit to show
  */
 export declare const toDuration: (number: number, unit: TemporalTimeTypes, roundAt?: Extract<Temporal.TimeUnit, "hour" | "minute" | "second">) => Intl.Duration;
@@ -873,4 +917,103 @@ export declare const dayNameUtil: (date: TemporalDate, format: TemporalFormatSty
  * @param {string} locale - The locale to use for formatting. If not provided, the system's default locale will be used.
  */
 export declare const daysUtil: (format?: TemporalFormatStyle, locale?: string) => string[];
+/**
+ * Returns the UTC date-time for the given time zone.
+ *
+ * @param {Date} from - The date to convert to UTC.
+ * @param {string} timeZoneId - The time zone of the input date.
+ */
+export declare const getUTCFromTimeZonedUtil: (from: Date, timeZoneId: string) => Date;
+interface GetWeekUtilOptions {
+    weekStartsOn?: number;
+    firstWeekContainsDate?: number;
+    locale?: string;
+}
+/**
+ * @name getWeekUtil
+ * @summary Get the local week index of the given date.
+ * @description
+ * Get the local week index of the given date using Temporal.
+ * The exact calculation depends on the values of `weekStartsOn` (the index of the first day of the week)
+ * and `firstWeekContainsDate` (the day in January, which is always in the first week of the week-numbering year).
+ * @param {Temporal.PlainDate | Date | string} date - The given date (can be either Temporal.PlainDate, a native Date, or an ISO date string).
+ * @param {GetWeekUtilOptions} [options] - Optional settings for the week calculation.
+ * @returns {number} - The week number of the year.
+ * @example
+ * // Which week of the local week numbering year is 2 January 2005 with default options?
+ * const result = getWeekUtil(new Date(2005, 0, 2))
+ * //=> 2
+ * @example
+ * // Which week of the local week numbering year is 2 January 2005, if Monday is the first day of the week,
+ * // and the first week of the year always contains 4 January?
+ * const result = getWeekUtil("2005-01-02T00:00:00.000Z", {
+ *   weekStartsOn: 1,
+ *   firstWeekContainsDate: 4
+ * })
+ * //=> 53
+ */
+export declare const getWeekUtil: (date: Temporal.PlainDate | Date | string, options?: GetWeekUtilOptions) => number;
+/**
+ * @name convertMillisecondsUtil
+ * @summary Convert milliseconds using Temporal.
+ * @description
+ * Convert milliseconds to the specified unit using Temporal.
+ * @param {number} milliseconds - The number of milliseconds to convert.
+ * @returns {number} - The converted value.
+ * @example
+ * const result = convertMillisecondsUtil(60000, "minute")
+ * //=> 1
+ * @example
+ * const result = convertMillisecondsUtil(120000, "second")
+ * //=> 120
+ * @example
+ * const result = convertMillisecondsUtil(3600000, "hour")
+ * //=> 1
+ */
+export declare const convertMillisecondsUtil: (milliseconds: number, unit: Extract<Temporal.TimeUnit, "hour" | "minute" | "second" | "millisecond">) => number;
+/**
+ * @name convertSecondsUtil
+ * @summary Convert seconds using Temporal.
+ * @description
+ * Convert seconds to the specified unit using Temporal.
+ * @param {number} seconds - The number of seconds to convert.
+ * @returns {number} - The converted value.
+ * @example
+ * const result = convertSecondsUtil(60, "minute")
+ * //=> 1
+ * @example
+ * const result = convertSecondsUtil(120, "second")
+ * //=> 120
+ */
+export declare const convertSecondsUtil: (seconds: number, unit: Extract<Temporal.TimeUnit, "hour" | "minute" | "second" | "millisecond">) => number;
+/**
+ * @name convertMinutesUtil
+ * @summary Convert seconds using Temporal.
+ * @description
+ * Convert minutes to the specified unit using Temporal.
+ * @param {number} minutes - The number of minutes to convert.
+ * @returns {number} - The converted value.
+ * @example
+ * const result = convertMinutesUtil(60, "minute")
+ * //=> 1
+ * @example
+ * const result = convertMinutesUtil(120, "second")
+ * //=> 120
+ */
+export declare const convertMinutesUtil: (minutes: number, unit: Extract<Temporal.TimeUnit, "hour" | "minute" | "second" | "millisecond">) => number;
+/**
+ * @name convertHoursUtil
+ * @summary Convert hours using Temporal.
+ * @description
+ * Convert hours to the specified unit using Temporal.
+ * @param {number} hours - The number of hours to convert.
+ * @returns {number} - The converted value.
+ * @example
+ * const result = convertHoursUtil(24, "day")
+ * //=> 1
+ * @example
+ * const result = convertHoursUtil(48, "hour")
+ * //=> 48
+ */
+export declare const convertHoursUtil: (hours: number, unit: Extract<Temporal.TimeUnit, "hour" | "minute" | "second" | "millisecond">) => number;
 export {};