@trackunit/date-and-time-utils 1.11.101 → 1.11.102

package/index.cjs.js

@@ -137,6 +137,24 @@ const formatDateUtil = (date, format, timeZone, locale) => {
  * @returns {string} A formatted string representing the date range.
  */
 const formatRangeUtil = (range, locale, format) => Intl.DateTimeFormat(locale, format).formatRange(range.start ?? new Date(), range.end ?? new Date());
+/**
+ * Formats a {@link TemporalDate} as a short locale-aware calendar day (medium `dateStyle` via
+ * {@link formatDateUtil}).
+ *
+ * @param date - The date to format. `undefined` and invalid Dates yield `""`.
+ * @param locale - Optional locale. Falls back to the system locale when omitted.
+ * @returns {string} A short date such as `"Mar 7, 2025"` in English.
+ * @example
+ * formatShortDateUtil(new Date(2025, 2, 7), "en"); // → "Mar 7, 2025"
+ * formatShortDateUtil(undefined, "en");            // → ""
+ */
+const formatShortDateUtil = (date, locale) => {
+    if (!date)
+        return "";
+    if (date instanceof Date && Number.isNaN(date.getTime()))
+        return "";
+    return formatDateUtil(date, { selectFormat: "dateOnly", dateFormat: "medium" }, undefined, locale);
+};
 /**
  * Subtracts a specified number of minutes from a date.
  *
@@ -1623,11 +1641,116 @@ const parseValidDate = (date) => {
     }
     return null;
 };
+const YYYY_MM_DD_REGEX = /^(\d{4})-(\d{2})-(\d{2})$/;
+/**
+ * Parses a strict `YYYY-MM-DD` string into a `Temporal.PlainDate`.
+ * Returns `null` for any other format or for an invalid calendar day (e.g. `2025-02-30`).
+ *
+ * @param value - The string to parse.
+ * @returns {TemporalPlainDate | null} The parsed calendar day or null.
+ */
+const parseYYYYMMDDToPlainDate = (value) => {
+    const match = YYYY_MM_DD_REGEX.exec(value);
+    if (!match)
+        return null;
+    try {
+        return polyfill.Temporal.PlainDate.from({ year: Number(match[1]), month: Number(match[2]), day: Number(match[3]) }, { overflow: "reject" });
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Converts a {@link TemporalDate} to the `Temporal.PlainDate` representing its calendar day.
+ *
+ * Returns `null` when the input is `undefined` or an invalid `Date`. Delegates to
+ * {@link toZonedDateTimeUtil} so the calendar day matches the rest of this file's conventions
+ * (system time zone for `Date` / `Instant`, the zoned value's own time zone for `ZonedDateTime`).
+ *
+ * @param date - The date to convert.
+ * @returns {TemporalPlainDate | null} The calendar day or null.
+ */
+const calendarDayOf = (date) => {
+    if (!date)
+        return null;
+    if (date instanceof Date && Number.isNaN(date.getTime()))
+        return null;
+    return toZonedDateTimeUtil(date).toPlainDate();
+};
+/**
+ * Parses a strict `YYYY-MM-DD` string into a {@link Date} at local midnight.
+ *
+ * Unlike `new Date("2025-03-07")` (which parses as UTC midnight and can shift calendar day when
+ * displayed in a non-UTC zone), this returns a Date anchored to the local calendar day.
+ *
+ * @param value - The string to parse.
+ * @returns {Date | null} The local-midnight Date or null when the input is not a valid YYYY-MM-DD.
+ * @example
+ * parseYYYYMMDDUtil("2025-03-07"); // → Date at local midnight on 7 March 2025
+ * parseYYYYMMDDUtil("2025-02-30"); // → null
+ * parseYYYYMMDDUtil("03/07/2025"); // → null
+ */
+const parseYYYYMMDDUtil = (value) => {
+    const plain = parseYYYYMMDDToPlainDate(value);
+    if (!plain)
+        return null;
+    return new Date(plain.year, plain.month - 1, plain.day);
+};
+/**
+ * Converts a {@link TemporalDate} to a canonical `YYYY-MM-DD` string for its calendar day.
+ *
+ * Time-zone safe replacement for the `date.toISOString().split("T")[0]` pattern which returns
+ * the UTC calendar day instead of the user's local day.
+ *
+ * @param date - The date to convert. `undefined` and invalid Dates yield `""`.
+ * @returns {string} `YYYY-MM-DD` or empty string.
+ * @example
+ * dateToYYYYMMDDUtil(new Date(2025, 2, 7)); // → "2025-03-07"
+ * dateToYYYYMMDDUtil(undefined);            // → ""
+ * dateToYYYYMMDDUtil(new Date("invalid"));  // → ""
+ */
+const dateToYYYYMMDDUtil = (date) => {
+    const plain = calendarDayOf(date);
+    if (!plain)
+        return "";
+    return plain.toString();
+};
+/**
+ * Converts a strict `YYYY-MM-DD` string to the ISO timestamp at UTC midnight for that calendar day.
+ *
+ * @param value - A `YYYY-MM-DD` string.
+ * @returns {string | null} ISO timestamp at UTC midnight, or null when the input is not a valid `YYYY-MM-DD`.
+ * @example
+ * YYYYMMDDToUTCMidnightISOUtil("2025-03-07"); // → "2025-03-07T00:00:00.000Z"
+ * YYYYMMDDToUTCMidnightISOUtil("not-a-date"); // → null
+ */
+const YYYYMMDDToUTCMidnightISOUtil = (value) => {
+    const plain = parseYYYYMMDDToPlainDate(value);
+    if (!plain)
+        return null;
+    return plain.toZonedDateTime("UTC").toInstant().toString({ smallestUnit: "millisecond" });
+};
+/**
+ * Converts a {@link TemporalDate} to the ISO timestamp at UTC midnight for its calendar day.
+ *
+ * @param date - The date to convert. `undefined` and invalid Dates yield `""`.
+ * @returns {string} ISO timestamp at UTC midnight, or empty string for an invalid Date.
+ * @example
+ * dateToUTCMidnightISOUtil(new Date(2025, 2, 7));        // → "2025-03-07T00:00:00.000Z"
+ * dateToUTCMidnightISOUtil(new Date(2025, 2, 7, 14, 30)); // → "2025-03-07T00:00:00.000Z"
+ */
+const dateToUTCMidnightISOUtil = (date) => {
+    const plain = calendarDayOf(date);
+    if (!plain)
+        return "";
+    return plain.toZonedDateTime("UTC").toInstant().toString({ smallestUnit: "millisecond" });
+};
 
 Object.defineProperty(exports, "Temporal", {
   enumerable: true,
   get: function () { return polyfill.Temporal; }
 });
+exports.YYYYMMDDToUTCMidnightISOUtil = YYYYMMDDToUTCMidnightISOUtil;
 exports.addDaysUtil = addDaysUtil;
 exports.addHoursUtil = addHoursUtil;
 exports.addMinutesUtil = addMinutesUtil;
@@ -1638,6 +1761,8 @@ exports.convertHoursUtil = convertHoursUtil;
 exports.convertMillisecondsUtil = convertMillisecondsUtil;
 exports.convertMinutesUtil = convertMinutesUtil;
 exports.convertSecondsUtil = convertSecondsUtil;
+exports.dateToUTCMidnightISOUtil = dateToUTCMidnightISOUtil;
+exports.dateToYYYYMMDDUtil = dateToYYYYMMDDUtil;
 exports.dayNameUtil = dayNameUtil;
 exports.daysUtil = daysUtil;
 exports.differenceInDaysUtil = differenceInDaysUtil;
@@ -1654,6 +1779,7 @@ exports.endOfMonthUtil = endOfMonthUtil;
 exports.endOfWeekUtil = endOfWeekUtil;
 exports.formatDateUtil = formatDateUtil;
 exports.formatRangeUtil = formatRangeUtil;
+exports.formatShortDateUtil = formatShortDateUtil;
 exports.getDurationFormat = getDurationFormat;
 exports.getHourCycle = getHourCycle;
 exports.getTimeZone = getTimeZone;
@@ -1673,6 +1799,7 @@ exports.isValidDate = isValidDate;
 exports.monthNameUtil = monthNameUtil;
 exports.monthsUtil = monthsUtil;
 exports.parseValidDate = parseValidDate;
+exports.parseYYYYMMDDUtil = parseYYYYMMDDUtil;
 exports.startOfDayUtil = startOfDayUtil;
 exports.startOfHourUtil = startOfHourUtil;
 exports.startOfMinuteUtil = startOfMinuteUtil;

package/index.esm.js

@@ -136,6 +136,24 @@ const formatDateUtil = (date, format, timeZone, locale) => {
  * @returns {string} A formatted string representing the date range.
  */
 const formatRangeUtil = (range, locale, format) => Intl.DateTimeFormat(locale, format).formatRange(range.start ?? new Date(), range.end ?? new Date());
+/**
+ * Formats a {@link TemporalDate} as a short locale-aware calendar day (medium `dateStyle` via
+ * {@link formatDateUtil}).
+ *
+ * @param date - The date to format. `undefined` and invalid Dates yield `""`.
+ * @param locale - Optional locale. Falls back to the system locale when omitted.
+ * @returns {string} A short date such as `"Mar 7, 2025"` in English.
+ * @example
+ * formatShortDateUtil(new Date(2025, 2, 7), "en"); // → "Mar 7, 2025"
+ * formatShortDateUtil(undefined, "en");            // → ""
+ */
+const formatShortDateUtil = (date, locale) => {
+    if (!date)
+        return "";
+    if (date instanceof Date && Number.isNaN(date.getTime()))
+        return "";
+    return formatDateUtil(date, { selectFormat: "dateOnly", dateFormat: "medium" }, undefined, locale);
+};
 /**
  * Subtracts a specified number of minutes from a date.
  *
@@ -1622,5 +1640,109 @@ const parseValidDate = (date) => {
     }
     return null;
 };
+const YYYY_MM_DD_REGEX = /^(\d{4})-(\d{2})-(\d{2})$/;
+/**
+ * Parses a strict `YYYY-MM-DD` string into a `Temporal.PlainDate`.
+ * Returns `null` for any other format or for an invalid calendar day (e.g. `2025-02-30`).
+ *
+ * @param value - The string to parse.
+ * @returns {TemporalPlainDate | null} The parsed calendar day or null.
+ */
+const parseYYYYMMDDToPlainDate = (value) => {
+    const match = YYYY_MM_DD_REGEX.exec(value);
+    if (!match)
+        return null;
+    try {
+        return Temporal.PlainDate.from({ year: Number(match[1]), month: Number(match[2]), day: Number(match[3]) }, { overflow: "reject" });
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Converts a {@link TemporalDate} to the `Temporal.PlainDate` representing its calendar day.
+ *
+ * Returns `null` when the input is `undefined` or an invalid `Date`. Delegates to
+ * {@link toZonedDateTimeUtil} so the calendar day matches the rest of this file's conventions
+ * (system time zone for `Date` / `Instant`, the zoned value's own time zone for `ZonedDateTime`).
+ *
+ * @param date - The date to convert.
+ * @returns {TemporalPlainDate | null} The calendar day or null.
+ */
+const calendarDayOf = (date) => {
+    if (!date)
+        return null;
+    if (date instanceof Date && Number.isNaN(date.getTime()))
+        return null;
+    return toZonedDateTimeUtil(date).toPlainDate();
+};
+/**
+ * Parses a strict `YYYY-MM-DD` string into a {@link Date} at local midnight.
+ *
+ * Unlike `new Date("2025-03-07")` (which parses as UTC midnight and can shift calendar day when
+ * displayed in a non-UTC zone), this returns a Date anchored to the local calendar day.
+ *
+ * @param value - The string to parse.
+ * @returns {Date | null} The local-midnight Date or null when the input is not a valid YYYY-MM-DD.
+ * @example
+ * parseYYYYMMDDUtil("2025-03-07"); // → Date at local midnight on 7 March 2025
+ * parseYYYYMMDDUtil("2025-02-30"); // → null
+ * parseYYYYMMDDUtil("03/07/2025"); // → null
+ */
+const parseYYYYMMDDUtil = (value) => {
+    const plain = parseYYYYMMDDToPlainDate(value);
+    if (!plain)
+        return null;
+    return new Date(plain.year, plain.month - 1, plain.day);
+};
+/**
+ * Converts a {@link TemporalDate} to a canonical `YYYY-MM-DD` string for its calendar day.
+ *
+ * Time-zone safe replacement for the `date.toISOString().split("T")[0]` pattern which returns
+ * the UTC calendar day instead of the user's local day.
+ *
+ * @param date - The date to convert. `undefined` and invalid Dates yield `""`.
+ * @returns {string} `YYYY-MM-DD` or empty string.
+ * @example
+ * dateToYYYYMMDDUtil(new Date(2025, 2, 7)); // → "2025-03-07"
+ * dateToYYYYMMDDUtil(undefined);            // → ""
+ * dateToYYYYMMDDUtil(new Date("invalid"));  // → ""
+ */
+const dateToYYYYMMDDUtil = (date) => {
+    const plain = calendarDayOf(date);
+    if (!plain)
+        return "";
+    return plain.toString();
+};
+/**
+ * Converts a strict `YYYY-MM-DD` string to the ISO timestamp at UTC midnight for that calendar day.
+ *
+ * @param value - A `YYYY-MM-DD` string.
+ * @returns {string | null} ISO timestamp at UTC midnight, or null when the input is not a valid `YYYY-MM-DD`.
+ * @example
+ * YYYYMMDDToUTCMidnightISOUtil("2025-03-07"); // → "2025-03-07T00:00:00.000Z"
+ * YYYYMMDDToUTCMidnightISOUtil("not-a-date"); // → null
+ */
+const YYYYMMDDToUTCMidnightISOUtil = (value) => {
+    const plain = parseYYYYMMDDToPlainDate(value);
+    if (!plain)
+        return null;
+    return plain.toZonedDateTime("UTC").toInstant().toString({ smallestUnit: "millisecond" });
+};
+/**
+ * Converts a {@link TemporalDate} to the ISO timestamp at UTC midnight for its calendar day.
+ *
+ * @param date - The date to convert. `undefined` and invalid Dates yield `""`.
+ * @returns {string} ISO timestamp at UTC midnight, or empty string for an invalid Date.
+ * @example
+ * dateToUTCMidnightISOUtil(new Date(2025, 2, 7));        // → "2025-03-07T00:00:00.000Z"
+ * dateToUTCMidnightISOUtil(new Date(2025, 2, 7, 14, 30)); // → "2025-03-07T00:00:00.000Z"
+ */
+const dateToUTCMidnightISOUtil = (date) => {
+    const plain = calendarDayOf(date);
+    if (!plain)
+        return "";
+    return plain.toZonedDateTime("UTC").toInstant().toString({ smallestUnit: "millisecond" });
+};
 
-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 { YYYYMMDDToUTCMidnightISOUtil, addDaysUtil, addHoursUtil, addMinutesUtil, addMonthsUtil, addWeeksUtil, addYearsUtil, convertHoursUtil, convertMillisecondsUtil, convertMinutesUtil, convertSecondsUtil, dateToUTCMidnightISOUtil, dateToYYYYMMDDUtil, dayNameUtil, daysUtil, differenceInDaysUtil, differenceInHoursUtil, differenceInMinutesUtil, differenceInMonthsUtil, differenceInSecondsUtil, differenceInWeeksUtil, differenceInYearsUtil, endOfDayUtil, endOfHourUtil, endOfMinuteUtil, endOfMonthUtil, endOfWeekUtil, formatDateUtil, formatRangeUtil, formatShortDateUtil, getDurationFormat, getHourCycle, getTimeZone, getTimeZoneOffset, getUTCFromTimeZonedUtil, getWeekUtil, isBetweenUtil, isEqualUtil, isFutureUtil, isPastUtil, isSameDayUtil, isSameMonthUtil, isSameWeekUtil, isSameYearUtil, isTodayUtil, isValidDate, monthNameUtil, monthsUtil, parseValidDate, parseYYYYMMDDUtil, 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,6 +1,6 @@
 {
   "name": "@trackunit/date-and-time-utils",
-  "version": "1.11.101",
+  "version": "1.11.102",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {

package/src/DateAndTimeUtils.d.ts

@@ -93,6 +93,18 @@ export declare const formatDateUtil: (date: TemporalDate, format?: TemporalForma
  * @returns {string} A formatted string representing the date range.
  */
 export declare const formatRangeUtil: (range: DateRange, locale: string, format?: TemporalFormatTypes) => string;
+/**
+ * Formats a {@link TemporalDate} as a short locale-aware calendar day (medium `dateStyle` via
+ * {@link formatDateUtil}).
+ *
+ * @param date - The date to format. `undefined` and invalid Dates yield `""`.
+ * @param locale - Optional locale. Falls back to the system locale when omitted.
+ * @returns {string} A short date such as `"Mar 7, 2025"` in English.
+ * @example
+ * formatShortDateUtil(new Date(2025, 2, 7), "en"); // → "Mar 7, 2025"
+ * formatShortDateUtil(undefined, "en");            // → ""
+ */
+export declare const formatShortDateUtil: (date: TemporalDate | undefined, locale?: string) => string;
 /**
  * Subtracts a specified number of minutes from a date.
  *
@@ -1038,4 +1050,52 @@ export declare const isValidDate: (date: Date | string | number) => boolean;
  * @returns {Date | null} - The parsed date or null if the date is invalid.
  */
 export declare const parseValidDate: (date: Date | string | number) => Date | null;
+/**
+ * Parses a strict `YYYY-MM-DD` string into a {@link Date} at local midnight.
+ *
+ * Unlike `new Date("2025-03-07")` (which parses as UTC midnight and can shift calendar day when
+ * displayed in a non-UTC zone), this returns a Date anchored to the local calendar day.
+ *
+ * @param value - The string to parse.
+ * @returns {Date | null} The local-midnight Date or null when the input is not a valid YYYY-MM-DD.
+ * @example
+ * parseYYYYMMDDUtil("2025-03-07"); // → Date at local midnight on 7 March 2025
+ * parseYYYYMMDDUtil("2025-02-30"); // → null
+ * parseYYYYMMDDUtil("03/07/2025"); // → null
+ */
+export declare const parseYYYYMMDDUtil: (value: string) => Date | null;
+/**
+ * Converts a {@link TemporalDate} to a canonical `YYYY-MM-DD` string for its calendar day.
+ *
+ * Time-zone safe replacement for the `date.toISOString().split("T")[0]` pattern which returns
+ * the UTC calendar day instead of the user's local day.
+ *
+ * @param date - The date to convert. `undefined` and invalid Dates yield `""`.
+ * @returns {string} `YYYY-MM-DD` or empty string.
+ * @example
+ * dateToYYYYMMDDUtil(new Date(2025, 2, 7)); // → "2025-03-07"
+ * dateToYYYYMMDDUtil(undefined);            // → ""
+ * dateToYYYYMMDDUtil(new Date("invalid"));  // → ""
+ */
+export declare const dateToYYYYMMDDUtil: (date: TemporalDate | undefined) => string;
+/**
+ * Converts a strict `YYYY-MM-DD` string to the ISO timestamp at UTC midnight for that calendar day.
+ *
+ * @param value - A `YYYY-MM-DD` string.
+ * @returns {string | null} ISO timestamp at UTC midnight, or null when the input is not a valid `YYYY-MM-DD`.
+ * @example
+ * YYYYMMDDToUTCMidnightISOUtil("2025-03-07"); // → "2025-03-07T00:00:00.000Z"
+ * YYYYMMDDToUTCMidnightISOUtil("not-a-date"); // → null
+ */
+export declare const YYYYMMDDToUTCMidnightISOUtil: (value: string) => string | null;
+/**
+ * Converts a {@link TemporalDate} to the ISO timestamp at UTC midnight for its calendar day.
+ *
+ * @param date - The date to convert. `undefined` and invalid Dates yield `""`.
+ * @returns {string} ISO timestamp at UTC midnight, or empty string for an invalid Date.
+ * @example
+ * dateToUTCMidnightISOUtil(new Date(2025, 2, 7));        // → "2025-03-07T00:00:00.000Z"
+ * dateToUTCMidnightISOUtil(new Date(2025, 2, 7, 14, 30)); // → "2025-03-07T00:00:00.000Z"
+ */
+export declare const dateToUTCMidnightISOUtil: (date: TemporalDate | undefined) => string;
 export {};