@catbee/utils 2.0.1 → 2.0.3

package/date/index.cjs

@@ -28,16 +28,105 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // src/date/date.utils.ts
+var DATE_FORMAT_PRESETS = {
+  short: {
+    year: "2-digit",
+    month: "numeric",
+    day: "numeric",
+    hour: "numeric",
+    minute: "numeric",
+    hour12: true
+  },
+  medium: {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "numeric",
+    second: "numeric",
+    hour12: true
+  },
+  long: {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+    hour: "numeric",
+    minute: "numeric",
+    second: "numeric",
+    hour12: true,
+    timeZoneName: "short"
+  },
+  full: {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+    weekday: "long",
+    hour: "numeric",
+    minute: "numeric",
+    second: "numeric",
+    hour12: true,
+    timeZoneName: "long"
+  },
+  shortDate: {
+    year: "2-digit",
+    month: "numeric",
+    day: "numeric"
+  },
+  mediumDate: {
+    year: "numeric",
+    month: "short",
+    day: "numeric"
+  },
+  longDate: {
+    year: "numeric",
+    month: "long",
+    day: "numeric"
+  },
+  fullDate: {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+    weekday: "long"
+  },
+  shortTime: {
+    hour: "numeric",
+    minute: "numeric",
+    hour12: true
+  },
+  mediumTime: {
+    hour: "numeric",
+    minute: "numeric",
+    second: "numeric",
+    hour12: true
+  },
+  longTime: {
+    hour: "numeric",
+    minute: "numeric",
+    second: "numeric",
+    hour12: true,
+    timeZoneName: "short"
+  },
+  fullTime: {
+    hour: "numeric",
+    minute: "numeric",
+    second: "numeric",
+    hour12: true,
+    timeZoneName: "long"
+  }
+};
 function formatDate(date, options = {}) {
   const { format = "yyyy-MM-dd", locale, timeZone } = options;
   const d = date instanceof Date ? date : new Date(date);
-  if (format === "yyyy-MM-dd") {
+  if (format === "yyyy-MM-dd" && !timeZone) {
     const yyyy = d.getFullYear();
     const mm = String(d.getMonth() + 1).padStart(2, "0");
     const dd = String(d.getDate()).padStart(2, "0");
     return `${yyyy}-${mm}-${dd}`;
   }
-  if (format === "yyyy-MM-dd HH:mm:ss") {
+  if (format === "yyyy-MM-dd" && timeZone) {
+    return formatDateInTimeZone(d, timeZone, "yyyy-MM-dd");
+  }
+  if (format === "yyyy-MM-dd HH:mm:ss" && !timeZone) {
     const yyyy = d.getFullYear();
     const mm = String(d.getMonth() + 1).padStart(2, "0");
     const dd = String(d.getDate()).padStart(2, "0");
@@ -46,9 +135,18 @@ function formatDate(date, options = {}) {
     const SS = String(d.getSeconds()).padStart(2, "0");
     return `${yyyy}-${mm}-${dd} ${HH}:${MM}:${SS}`;
   }
+  if (format === "yyyy-MM-dd HH:mm:ss" && timeZone) {
+    return formatDateInTimeZone(d, timeZone, "yyyy-MM-dd HH:mm:ss");
+  }
   if (format === "relative") {
     return formatRelativeTime(date);
   }
+  if (Object.hasOwn(DATE_FORMAT_PRESETS, format)) {
+    return new Intl.DateTimeFormat(locale, {
+      ...DATE_FORMAT_PRESETS[format],
+      timeZone
+    }).format(d);
+  }
   return new Intl.DateTimeFormat(locale, {
     timeZone,
     year: format.includes("yyyy") || format.includes("y") ? "numeric" : void 0,
@@ -83,18 +181,12 @@ function formatRelativeTime(date, now = /* @__PURE__ */ new Date(), locale) {
 }
 __name(formatRelativeTime, "formatRelativeTime");
 function parseDate(input, fallback) {
-  if (typeof input === "number") {
-    return new Date(input);
-  }
-  try {
-    const date = new Date(input);
-    if (Number.isNaN(date.getTime())) {
-      return fallback || null;
-    }
-    return date;
-  } catch {
-    return fallback || null;
+  if (typeof input === "number") return new Date(input);
+  if (!/^\d{4}-\d{2}-\d{2}/.test(input)) {
+    return fallback ?? null;
   }
+  const date = new Date(input.includes("T") ? input : input + "T00:00:00");
+  return Number.isNaN(date.getTime()) ? fallback ?? null : date;
 }
 __name(parseDate, "parseDate");
 function dateDiff(date1, date2 = /* @__PURE__ */ new Date(), unit = "days") {
@@ -110,8 +202,11 @@ function dateDiff(date1, date2 = /* @__PURE__ */ new Date(), unit = "days") {
       return diffMs / (1e3 * 60);
     case "hours":
       return diffMs / (1e3 * 60 * 60);
-    case "days":
-      return diffMs / (1e3 * 60 * 60 * 24);
+    case "days": {
+      const n1 = new Date(d1.getFullYear(), d1.getMonth(), d1.getDate());
+      const n2 = new Date(d2.getFullYear(), d2.getMonth(), d2.getDate());
+      return Math.round((n1.getTime() - n2.getTime()) / (1e3 * 60 * 60 * 24));
+    }
     case "months":
       return (d1.getFullYear() - d2.getFullYear()) * 12 + d1.getMonth() - d2.getMonth();
     case "years":
@@ -121,114 +216,131 @@ function dateDiff(date1, date2 = /* @__PURE__ */ new Date(), unit = "days") {
   }
 }
 __name(dateDiff, "dateDiff");
-function addToDate(date, amount, unit) {
-  const d = date instanceof Date ? new Date(date) : new Date(date);
-  switch (unit) {
-    case "milliseconds":
-      d.setMilliseconds(d.getMilliseconds() + amount);
-      break;
-    case "seconds":
-      d.setSeconds(d.getSeconds() + amount);
-      break;
-    case "minutes":
-      d.setMinutes(d.getMinutes() + amount);
-      break;
-    case "hours":
-      d.setHours(d.getHours() + amount);
-      break;
-    case "days":
-      d.setDate(d.getDate() + amount);
-      break;
-    case "months": {
-      const origDate = d.getDate();
-      const origMonth = d.getMonth();
-      d.setDate(1);
-      d.setMonth(origMonth + amount);
-      const lastDay = new Date(d.getFullYear(), d.getMonth() + 1, 0).getDate();
-      d.setDate(Math.min(origDate, lastDay));
-      break;
+function dateDiffDaysTZ(d1, d2, tz) {
+  const p1 = getTimeZoneParts(d1, tz);
+  const p2 = getTimeZoneParts(d2, tz);
+  const a = Date.UTC(p1.year, p1.month - 1, p1.day);
+  const b = Date.UTC(p2.year, p2.month - 1, p2.day);
+  return Math.round((a - b) / 864e5);
+}
+__name(dateDiffDaysTZ, "dateDiffDaysTZ");
+function addToDate(date, amount, unit, options) {
+  const d = new Date(date);
+  if (unit === "milliseconds") return new Date(d.getTime() + amount);
+  if (unit === "seconds") return new Date(d.getTime() + amount * 1e3);
+  if (unit === "minutes") return new Date(d.getTime() + amount * 6e4);
+  if (unit === "hours") return new Date(d.getTime() + amount * 36e5);
+  const tz = options?.timeZone;
+  if (!tz) {
+    if (unit === "days") return addDays(d, amount);
+    if (unit === "months") {
+      const targetMonth = d.getMonth() + amount;
+      const targetYear = d.getFullYear() + Math.floor(targetMonth / 12);
+      const normalizedMonth = (targetMonth % 12 + 12) % 12;
+      const day = d.getDate();
+      const lastDay = new Date(targetYear, normalizedMonth + 1, 0).getDate();
+      const clampedDay = Math.min(day, lastDay);
+      return new Date(targetYear, normalizedMonth, clampedDay, d.getHours(), d.getMinutes(), d.getSeconds(), d.getMilliseconds());
     }
-    case "years":
-      d.setFullYear(d.getFullYear() + amount);
-      break;
-    default:
-      throw new Error(`Unsupported unit: ${unit}`);
-  }
-  return d;
+    if (unit === "years") {
+      const targetYear = d.getFullYear() + amount;
+      const month = d.getMonth();
+      const day = d.getDate();
+      const lastDay = new Date(targetYear, month + 1, 0).getDate();
+      const clampedDay = Math.min(day, lastDay);
+      return new Date(targetYear, month, clampedDay, d.getHours(), d.getMinutes(), d.getSeconds(), d.getMilliseconds());
+    }
+    throw new Error(`Unsupported unit: ${unit}`);
+  }
+  const parts = getTimeZoneParts(d, tz);
+  const ms = d.getMilliseconds();
+  const result = {
+    ...parts,
+    day: parts.day,
+    month: parts.month,
+    year: parts.year,
+    millisecond: ms
+  };
+  if (unit === "days") result.day += amount;
+  if (unit === "months") {
+    result.month += amount;
+    result.year += Math.floor((result.month - 1) / 12);
+    result.month = ((result.month - 1) % 12 + 12) % 12 + 1;
+    const lastDay = new Date(Date.UTC(result.year, result.month, 0)).getUTCDate();
+    result.day = Math.min(result.day, lastDay);
+  }
+  if (unit === "years") {
+    result.year += amount;
+    const lastDay = new Date(Date.UTC(result.year, result.month, 0)).getUTCDate();
+    result.day = Math.min(result.day, lastDay);
+  }
+  return zonedTimeToUtc(result, tz);
 }
 __name(addToDate, "addToDate");
+function zonedTimeToUtc(parts, timeZone) {
+  const utcGuess = new Date(Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour ?? 0, parts.minute ?? 0, parts.second ?? 0));
+  const offset1 = getTimezoneOffset(timeZone, utcGuess);
+  const adjusted = new Date(utcGuess.getTime() - offset1 * 6e4);
+  const offset2 = getTimezoneOffset(timeZone, adjusted);
+  const result = offset1 !== offset2 ? new Date(utcGuess.getTime() - offset2 * 6e4) : adjusted;
+  if (parts.millisecond !== void 0) {
+    result.setMilliseconds(parts.millisecond);
+  }
+  return result;
+}
+__name(zonedTimeToUtc, "zonedTimeToUtc");
 function startOf(date, unit) {
-  const d = date instanceof Date ? new Date(date) : new Date(date);
+  const d = new Date(date);
   switch (unit) {
     case "second":
-      d.setMilliseconds(0);
-      break;
+      return new Date(d.getFullYear(), d.getMonth(), d.getDate(), d.getHours(), d.getMinutes(), d.getSeconds(), 0);
     case "minute":
-      d.setSeconds(0, 0);
-      break;
+      return new Date(d.getFullYear(), d.getMonth(), d.getDate(), d.getHours(), d.getMinutes(), 0, 0);
     case "hour":
-      d.setMinutes(0, 0, 0);
-      break;
+      return new Date(d.getFullYear(), d.getMonth(), d.getDate(), d.getHours(), 0, 0, 0);
     case "day":
-      d.setHours(0, 0, 0, 0);
-      break;
-    case "week":
-      d.setHours(0, 0, 0, 0);
-      d.setDate(d.getDate() - d.getDay());
-      break;
+      return new Date(d.getFullYear(), d.getMonth(), d.getDate());
+    case "week": {
+      const day = d.getDay();
+      const diff = -day;
+      return new Date(d.getFullYear(), d.getMonth(), d.getDate() + diff);
+    }
     case "month":
-      d.setDate(1);
-      d.setHours(0, 0, 0, 0);
-      break;
+      return new Date(d.getFullYear(), d.getMonth(), 1);
     case "quarter":
-      d.setMonth(Math.floor(d.getMonth() / 3) * 3, 1);
-      d.setHours(0, 0, 0, 0);
-      break;
+      return new Date(d.getFullYear(), Math.floor(d.getMonth() / 3) * 3, 1);
     case "year":
-      d.setMonth(0, 1);
-      d.setHours(0, 0, 0, 0);
-      break;
+      return new Date(d.getFullYear(), 0, 1);
     default:
       throw new Error(`Unsupported unit: ${unit}`);
   }
-  return d;
 }
 __name(startOf, "startOf");
 function endOf(date, unit) {
-  const d = date instanceof Date ? new Date(date) : new Date(date);
+  const d = new Date(date);
   switch (unit) {
     case "second":
-      d.setMilliseconds(999);
-      break;
+      return new Date(d.getFullYear(), d.getMonth(), d.getDate(), d.getHours(), d.getMinutes(), d.getSeconds(), 999);
     case "minute":
-      d.setSeconds(59, 999);
-      break;
+      return new Date(d.getFullYear(), d.getMonth(), d.getDate(), d.getHours(), d.getMinutes(), 59, 999);
     case "hour":
-      d.setMinutes(59, 59, 999);
-      break;
+      return new Date(d.getFullYear(), d.getMonth(), d.getDate(), d.getHours(), 59, 59, 999);
     case "day":
-      d.setHours(23, 59, 59, 999);
-      break;
-    case "week":
-      d.setDate(d.getDate() - d.getDay() + 6);
-      d.setHours(23, 59, 59, 999);
-      break;
+      return new Date(d.getFullYear(), d.getMonth(), d.getDate(), 23, 59, 59, 999);
+    case "week": {
+      const day = d.getDay();
+      const diff = 6 - day;
+      return new Date(d.getFullYear(), d.getMonth(), d.getDate() + diff, 23, 59, 59, 999);
+    }
     case "month":
-      d.setMonth(d.getMonth() + 1, 0);
-      d.setHours(23, 59, 59, 999);
-      break;
+      return new Date(d.getFullYear(), d.getMonth() + 1, 0, 23, 59, 59, 999);
     case "quarter":
-      d.setMonth(Math.floor(d.getMonth() / 3) * 3 + 3, 0);
-      d.setHours(23, 59, 59, 999);
-      break;
+      return new Date(d.getFullYear(), Math.floor(d.getMonth() / 3) * 3 + 3, 0, 23, 59, 59, 999);
     case "year":
-      d.setMonth(11, 31);
-      d.setHours(23, 59, 59, 999);
-      break;
+      return new Date(d.getFullYear(), 11, 31, 23, 59, 59, 999);
     default:
       throw new Error(`Unsupported unit: ${unit}`);
   }
-  return d;
 }
 __name(endOf, "endOf");
 function isBetween(date, start, end, inclusive = true) {
@@ -347,19 +459,19 @@ function isPast(date) {
 }
 __name(isPast, "isPast");
 function addDays(date, days) {
-  const d = new Date(date instanceof Date ? date : new Date(date));
+  const d = new Date(date);
   d.setDate(d.getDate() + days);
   return d;
 }
 __name(addDays, "addDays");
 function addMonths(date, months) {
-  const d = new Date(date instanceof Date ? date : new Date(date));
+  const d = new Date(date);
   d.setMonth(d.getMonth() + months);
   return d;
 }
 __name(addMonths, "addMonths");
 function addYears(date, years) {
-  const d = new Date(date instanceof Date ? date : new Date(date));
+  const d = new Date(date);
   d.setFullYear(d.getFullYear() + years);
   return d;
 }
@@ -370,13 +482,99 @@ function quarterOf(date) {
 }
 __name(quarterOf, "quarterOf");
 function weekOfYear(date) {
-  const d = new Date(date instanceof Date ? date : new Date(date));
-  d.setHours(0, 0, 0, 0);
-  d.setDate(d.getDate() + 4 - (d.getDay() || 7));
-  const yearStart = new Date(d.getFullYear(), 0, 1);
-  return Math.ceil(((d.getTime() - yearStart.getTime()) / 864e5 + 1) / 7);
+  const d = date instanceof Date ? date : new Date(date);
+  const target = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+  target.setUTCDate(target.getUTCDate() + 4 - (target.getUTCDay() || 7));
+  const yearStart = Date.UTC(target.getUTCFullYear(), 0, 1);
+  return Math.ceil(((target.getTime() - yearStart) / 864e5 + 1) / 7);
 }
 __name(weekOfYear, "weekOfYear");
+function getTimezoneOffset(timeZone, date = /* @__PURE__ */ new Date()) {
+  const d = date instanceof Date ? date : new Date(date);
+  const parts = getTimeZoneParts(d, timeZone);
+  const tzDate = new Date(Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second));
+  return Math.round((tzDate.getTime() - d.getTime()) / 6e4);
+}
+__name(getTimezoneOffset, "getTimezoneOffset");
+function toTimeZone(date, timeZone) {
+  const d = date instanceof Date ? date : new Date(date);
+  const parts = getTimeZoneParts(d, timeZone);
+  return {
+    year: parts.year,
+    month: parts.month,
+    day: parts.day,
+    hour: parts.hour,
+    minute: parts.minute,
+    second: parts.second,
+    millisecond: d.getMilliseconds()
+  };
+}
+__name(toTimeZone, "toTimeZone");
+function formatDateInTimeZone(date, timeZone, format = "yyyy-MM-dd HH:mm:ss", locale) {
+  const d = date instanceof Date ? date : new Date(date);
+  const parts = getTimeZoneParts(d, timeZone);
+  if (format === "yyyy-MM-dd") {
+    return `${parts.year}-${String(parts.month).padStart(2, "0")}-${String(parts.day).padStart(2, "0")}`;
+  }
+  if (format === "yyyy-MM-dd HH:mm:ss") {
+    return `${parts.year}-${String(parts.month).padStart(2, "0")}-${String(parts.day).padStart(2, "0")} ${String(parts.hour).padStart(2, "0")}:${String(parts.minute).padStart(2, "0")}:${String(parts.second).padStart(2, "0")}`;
+  }
+  return new Intl.DateTimeFormat(locale, {
+    timeZone,
+    year: format.includes("yyyy") || format.includes("y") ? "numeric" : void 0,
+    month: format.includes("MM") || format.includes("M") ? "numeric" : void 0,
+    day: format.includes("dd") || format.includes("d") ? "numeric" : void 0,
+    hour: format.includes("HH") || format.includes("H") ? "numeric" : void 0,
+    minute: format.includes("mm") || format.includes("m") ? "numeric" : void 0,
+    second: format.includes("ss") || format.includes("s") ? "numeric" : void 0,
+    hour12: !format.includes("HH") && !format.includes("H")
+  }).format(d);
+}
+__name(formatDateInTimeZone, "formatDateInTimeZone");
+function isDST(timeZone, date = /* @__PURE__ */ new Date()) {
+  const d = date instanceof Date ? date : new Date(date);
+  const year = d.getUTCFullYear();
+  const jan = getTimezoneOffset(timeZone, new Date(Date.UTC(year, 0, 15, 12, 0, 0)));
+  const jul = getTimezoneOffset(timeZone, new Date(Date.UTC(year, 6, 15, 12, 0, 0)));
+  const standardOffset = Math.min(jan, jul);
+  return getTimezoneOffset(timeZone, d) > standardOffset;
+}
+__name(isDST, "isDST");
+function getTimezoneAbbreviation(timeZone, date = /* @__PURE__ */ new Date(), locale = "en-US") {
+  const d = date instanceof Date ? date : new Date(date);
+  const parts = new Intl.DateTimeFormat(locale, {
+    timeZone,
+    timeZoneName: "short"
+  }).formatToParts(d);
+  return parts.find((p) => p.type === "timeZoneName")?.value ?? "";
+}
+__name(getTimezoneAbbreviation, "getTimezoneAbbreviation");
+function getTimeZoneParts(date, timeZone) {
+  const fmt = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "numeric",
+    day: "numeric",
+    hour: "numeric",
+    minute: "numeric",
+    second: "numeric",
+    hour12: false
+  });
+  const parts = fmt.formatToParts(date);
+  const get = /* @__PURE__ */ __name((type) => {
+    const val = parts.find((p) => p.type === type)?.value ?? "0";
+    return parseInt(val, 10);
+  }, "get");
+  return {
+    year: get("year"),
+    month: get("month"),
+    day: get("day"),
+    hour: get("hour") === 24 ? 0 : get("hour"),
+    minute: get("minute"),
+    second: get("second")
+  };
+}
+__name(getTimeZoneParts, "getTimeZoneParts");
 
 // src/date/date.builder.ts
 var DateBuilder = class _DateBuilder {
@@ -942,6 +1140,43 @@ var DateBuilder = class _DateBuilder {
   toString() {
     return this.date.toString();
   }
+  // ========== Timezone Methods ==========
+  /**
+  * Format the date in a specific timezone.
+  * @param timeZone - IANA timezone identifier (e.g., 'America/New_York')
+  * @param format - Format pattern (default: 'yyyy-MM-dd HH:mm:ss')
+  */
+  formatInTimeZone(timeZone, format = "yyyy-MM-dd HH:mm:ss") {
+    return formatDateInTimeZone(this.date, timeZone, format);
+  }
+  /**
+  * Get the wall-clock components in a specific timezone.
+  * @param timeZone - IANA timezone identifier
+  */
+  toTimeZone(timeZone) {
+    return toTimeZone(this.date, timeZone);
+  }
+  /**
+  * Get the UTC offset in minutes for a specific timezone at this date's instant.
+  * @param timeZone - IANA timezone identifier
+  */
+  getTimezoneOffset(timeZone) {
+    return getTimezoneOffset(timeZone, this.date);
+  }
+  /**
+  * Check if the specified timezone is observing DST at this date's instant.
+  * @param timeZone - IANA timezone identifier
+  */
+  isDST(timeZone) {
+    return isDST(timeZone, this.date);
+  }
+  /**
+  * Get the timezone abbreviation (e.g., 'EST', 'EDT') for a specific timezone.
+  * @param timeZone - IANA timezone identifier
+  */
+  getTimezoneAbbreviation(timeZone) {
+    return getTimezoneAbbreviation(timeZone, this.date);
+  }
 };
 
 exports.DateBuilder = DateBuilder;
@@ -950,13 +1185,18 @@ exports.addMonths = addMonths;
 exports.addToDate = addToDate;
 exports.addYears = addYears;
 exports.dateDiff = dateDiff;
+exports.dateDiffDaysTZ = dateDiffDaysTZ;
 exports.daysInMonth = daysInMonth;
 exports.endOf = endOf;
 exports.formatDate = formatDate;
+exports.formatDateInTimeZone = formatDateInTimeZone;
 exports.formatDuration = formatDuration;
 exports.formatRelativeTime = formatRelativeTime;
 exports.getDateFromDuration = getDateFromDuration;
+exports.getTimezoneAbbreviation = getTimezoneAbbreviation;
+exports.getTimezoneOffset = getTimezoneOffset;
 exports.isBetween = isBetween;
+exports.isDST = isDST;
 exports.isFuture = isFuture;
 exports.isLeapYear = isLeapYear;
 exports.isPast = isPast;
@@ -966,4 +1206,5 @@ exports.parseDate = parseDate;
 exports.parseDuration = parseDuration;
 exports.quarterOf = quarterOf;
 exports.startOf = startOf;
+exports.toTimeZone = toTimeZone;
 exports.weekOfYear = weekOfYear;