@prairielearn/formatter 1.3.14 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @prairielearn/formatter
 
+## 1.4.1
+
+### Patch Changes
+
+- 678b48a: Upgrade all JavaScript dependencies
+
+## 1.4.0
+
+### Minor Changes
+
+- 74b5cac: Add friendly date formatters and tests, and additional supporting utilities
+
 ## 1.3.14
 
 ### Patch Changes

package/dist/date.d.ts

@@ -35,3 +35,73 @@ export declare function formatDateYMDHM(date: Date, timeZone: string): string;
  * @returns Human-readable string representing the time zone.
  */
 export declare function formatTz(timeZone: string): string;
+/**
+ * Format a date to a human-readable string like '14:27:00 (CDT)'.
+ *
+ * @param date The date to format.
+ * @param timeZone The time zone to use for formatting.
+ * @param param2.includeTz Whether to include the time zone in the output (default true).
+ * @returns Human-readable string representing the date.
+ */
+export declare function formatDateHMS(date: Date, timeZone: string, { includeTz }?: {
+    includeTz?: boolean;
+}): string;
+/**
+ * Format a date to a human-readable string like '18:23' or 'May 2, 07:12',
+ * where the precision is determined by the range.
+ *
+ * @param date The date to format.
+ * @param rangeStart The start of the range.
+ * @param rangeEnd The end of the range.
+ * @param timeZone The time zone to use for formatting.
+ * @returns Human-readable string representing the date.
+ */
+export declare function formatDateWithinRange(date: Date, rangeStart: Date, rangeEnd: Date, timeZone: string): string;
+/**
+ * Format a date to a string like:
+ * - 'today, 3pm'
+ * - 'tomorrow, 10:30am'
+ * - 'yesterday, 11:45pm'
+ * - 'Mon, Mar 20, 8:15am' (if within 180 days of the base date)
+ * - 'Wed, Jan 1, 2020, 12pm'
+ * - `today, 3pm (CDT)` (if `includeTz` is true)
+ * - `3pm today` (if `timeFirst` is true)
+ * - 'today' (if `dateOnly` is true)
+ *
+ * If using this within a sentence like `... at ${formatDateFriendlyString()}`,
+ * use `timeFirst: true` to improve readability.
+ *
+ * @param date The date to format.
+ * @param timezone The time zone to use for formatting.
+ * @param param.baseDate The base date to use for comparison (default is the current date).
+ * @param param.includeTz Whether to include the time zone in the output (default true).
+ * @param param.timeFirst If true, the time is shown before the date (default false).
+ * @param param.dateOnly If true, only the date is shown (default false).
+ * @param param.timeOnly If true, only the time is shown (default false).
+ * @returns Human-readable string representing the date and time.
+ */
+export declare function formatDateFriendly(date: Date, timezone: string, { baseDate, includeTz, timeFirst, dateOnly, timeOnly, }?: {
+    baseDate?: Date;
+    includeTz?: boolean;
+    timeFirst?: boolean;
+    dateOnly?: boolean;
+    timeOnly?: boolean;
+}): string;
+/**
+ * Format a datetime range to a string like:
+ * - 'today, 10am'
+ * - 'today, 3pm to 5pm'
+ * - 'today, 3pm to tomorrow, 5pm'
+ * - 'today, 3pm to 5pm (CDT)' (if `includeTz` is true)
+ * - '3pm today to 5pm tomorrow' (if `timeFirst` is true)
+ * - 'today to tomorrow' (if `dateOnly` is true)
+ *
+ * This uses `formatDateFriendlyString()` to format the individual dates and times.
+ *
+ * @param start The start date and time.
+ * @param end The end date and time.
+ * @param timezone The time zone to use for formatting.
+ * @param options Additional options for formatting the displayed date, taken from `formatDateFriendlyString()`.
+ * @returns Human-readable string representing the datetime range.
+ */
+export declare function formatDateRangeFriendly(start: Date, end: Date, timezone: string, { baseDate, includeTz, timeFirst, dateOnly, }?: Parameters<typeof formatDateFriendly>[2]): string;

package/dist/date.js

@@ -1,3 +1,4 @@
+import { toTemporalInstant } from '@js-temporal/polyfill';
 import keyBy from 'lodash/keyBy.js';
 /**
  * Format a date to a human-readable string like '2020-03-27T12:34:56 (CDT)'.
@@ -84,4 +85,260 @@ export function formatTz(timeZone) {
     const tz = parts.find((p) => p.type === 'timeZoneName');
     return tz ? tz.value : timeZone;
 }
+/**
+ * Format a date to a human-readable string like '14:27:00 (CDT)'.
+ *
+ * @param date The date to format.
+ * @param timeZone The time zone to use for formatting.
+ * @param param2.includeTz Whether to include the time zone in the output (default true).
+ * @returns Human-readable string representing the date.
+ */
+export function formatDateHMS(date, timeZone, { includeTz = true } = {}) {
+    const options = {
+        timeZone,
+        hourCycle: 'h23',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        timeZoneName: 'short',
+    };
+    const parts = keyBy(new Intl.DateTimeFormat('en-US', options).formatToParts(date), (x) => x.type);
+    let dateFormatted = `${parts.hour.value}:${parts.minute.value}:${parts.second.value}`;
+    if (includeTz) {
+        dateFormatted = `${dateFormatted} (${parts.timeZoneName.value})`;
+    }
+    return dateFormatted;
+}
+/**
+ * Format a date to a human-readable string like '18:23' or 'May 2, 07:12',
+ * where the precision is determined by the range.
+ *
+ * @param date The date to format.
+ * @param rangeStart The start of the range.
+ * @param rangeEnd The end of the range.
+ * @param timeZone The time zone to use for formatting.
+ * @returns Human-readable string representing the date.
+ */
+export function formatDateWithinRange(date, rangeStart, rangeEnd, timeZone) {
+    const options = {
+        timeZone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        timeZoneName: 'short',
+    };
+    const dateParts = keyBy(new Intl.DateTimeFormat('en-US', options).formatToParts(date), (x) => x.type);
+    const startParts = keyBy(new Intl.DateTimeFormat('en-US', options).formatToParts(rangeStart), (x) => x.type);
+    const endParts = keyBy(new Intl.DateTimeFormat('en-US', options).formatToParts(rangeEnd), (x) => x.type);
+    // format the date (not time) parts
+    const dateYMD = `${dateParts.year.value}-${dateParts.month.value}-${dateParts.day.value}`;
+    const startYMD = `${startParts.year.value}-${startParts.month.value}-${startParts.day.value}`;
+    const endYMD = `${endParts.year.value}-${endParts.month.value}-${endParts.day.value}`;
+    if (dateYMD === startYMD && dateYMD === endYMD) {
+        // only show the time if the date is the same for all three
+        return `${dateParts.hour.value}:${dateParts.minute.value}`;
+    }
+    // format the year, but not the month or day
+    const dateY = `${dateParts.year.value}`;
+    const startY = `${startParts.year.value}`;
+    const endY = `${endParts.year.value}`;
+    // if the year is the same for all three, show the month, day, and time
+    if (dateY === startY && dateY === endY) {
+        const options = {
+            timeZone,
+            month: 'short',
+            day: 'numeric',
+            hour: '2-digit',
+            minute: '2-digit',
+        };
+        const dateParts = keyBy(new Intl.DateTimeFormat('en-US', options).formatToParts(date), (x) => x.type);
+        return `${dateParts.month.value} ${dateParts.day.value}, ${dateParts.hour.value}:${dateParts.minute.value}`;
+    }
+    // fall back to the full date
+    return `${dateParts.year.value}-${dateParts.month.value}-${dateParts.day.value} ${dateParts.hour.value}:${dateParts.minute.value}`;
+}
+/**
+ * Format a Date to date and time strings in the given time zone. The date is
+ * formatted like
+ * - 'today'
+ * - 'Mon, Mar 20' (if within 180 days of the base date)
+ * - 'Wed, Jan 1, 2020'
+ *
+ * The time format leaves off zero minutes and seconds, and uses 12-hour time,
+ * giving strings like
+ * - '3pm'
+ * - '3:34pm'
+ * - '3:34:17pm'
+ *
+ * @param date The date to format.
+ * @param timezone The time zone to use for formatting.
+ * @param baseDate The base date to use for comparison.
+ */
+function formatDateFriendlyParts(date, timezone, baseDate) {
+    // compute the number of days from the base date (0 = today, 1 = tomorrow, etc.)
+    const baseZonedDateTime = toTemporalInstant.call(baseDate).toZonedDateTimeISO(timezone);
+    const zonedDateTime = toTemporalInstant.call(date).toZonedDateTimeISO(timezone);
+    const basePlainDate = baseZonedDateTime.toPlainDate();
+    const plainDate = zonedDateTime.toPlainDate();
+    const daysOffset = plainDate.since(basePlainDate, { largestUnit: 'day' }).days;
+    // format the parts of the date and time
+    const options = {
+        timeZone: timezone,
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+        weekday: 'short',
+        hourCycle: 'h12',
+        hour: 'numeric',
+        minute: '2-digit',
+        second: '2-digit',
+        timeZoneName: 'short',
+    };
+    const parts = keyBy(new Intl.DateTimeFormat('en-US', options).formatToParts(date), (x) => x.type);
+    // format the date string
+    let dateFormatted = '';
+    if (daysOffset === 0) {
+        dateFormatted = 'today';
+    }
+    else if (daysOffset === 1) {
+        dateFormatted = 'tomorrow';
+    }
+    else if (daysOffset === -1) {
+        dateFormatted = 'yesterday';
+    }
+    else if (Math.abs(daysOffset) <= 180) {
+        // non-breaking-space (\u00a0) is used between the month and day
+        dateFormatted = `${parts.weekday.value}, ${parts.month.value}\u00a0${parts.day.value}`;
+    }
+    else {
+        dateFormatted = `${parts.weekday.value}, ${parts.month.value}\u00a0${parts.day.value}, ${parts.year.value}`;
+    }
+    // format the time string
+    let timeFormatted = '';
+    if (parts.minute.value === '00' && parts.second.value === '00') {
+        timeFormatted = `${parts.hour.value}`;
+    }
+    else if (parts.second.value === '00') {
+        timeFormatted = `${parts.hour.value}:${parts.minute.value}`;
+    }
+    else {
+        timeFormatted = `${parts.hour.value}:${parts.minute.value}:${parts.second.value}`;
+    }
+    // add the am/pm part
+    timeFormatted = `${timeFormatted}${parts.dayPeriod.value.toLowerCase()}`;
+    // format the timezone
+    const timezoneFormatted = `(${parts.timeZoneName.value})`;
+    return {
+        dateFormatted,
+        timeFormatted,
+        timezoneFormatted,
+    };
+}
+/**
+ * Format a date to a string like:
+ * - 'today, 3pm'
+ * - 'tomorrow, 10:30am'
+ * - 'yesterday, 11:45pm'
+ * - 'Mon, Mar 20, 8:15am' (if within 180 days of the base date)
+ * - 'Wed, Jan 1, 2020, 12pm'
+ * - `today, 3pm (CDT)` (if `includeTz` is true)
+ * - `3pm today` (if `timeFirst` is true)
+ * - 'today' (if `dateOnly` is true)
+ *
+ * If using this within a sentence like `... at ${formatDateFriendlyString()}`,
+ * use `timeFirst: true` to improve readability.
+ *
+ * @param date The date to format.
+ * @param timezone The time zone to use for formatting.
+ * @param param.baseDate The base date to use for comparison (default is the current date).
+ * @param param.includeTz Whether to include the time zone in the output (default true).
+ * @param param.timeFirst If true, the time is shown before the date (default false).
+ * @param param.dateOnly If true, only the date is shown (default false).
+ * @param param.timeOnly If true, only the time is shown (default false).
+ * @returns Human-readable string representing the date and time.
+ */
+export function formatDateFriendly(date, timezone, { baseDate = new Date(), includeTz = true, timeFirst = false, dateOnly = false, timeOnly = false, } = {}) {
+    const { dateFormatted, timeFormatted, timezoneFormatted } = formatDateFriendlyParts(date, timezone, baseDate);
+    let dateTimeFormatted = '';
+    if (dateOnly) {
+        dateTimeFormatted = dateFormatted;
+    }
+    else if (timeOnly) {
+        dateTimeFormatted = timeFormatted;
+    }
+    else {
+        if (timeFirst) {
+            dateTimeFormatted = `${timeFormatted} ${dateFormatted}`;
+        }
+        else {
+            dateTimeFormatted = `${dateFormatted}, ${timeFormatted}`;
+        }
+    }
+    if (includeTz) {
+        dateTimeFormatted = `${dateTimeFormatted} ${timezoneFormatted}`;
+    }
+    return dateTimeFormatted;
+}
+/**
+ * Format a datetime range to a string like:
+ * - 'today, 10am'
+ * - 'today, 3pm to 5pm'
+ * - 'today, 3pm to tomorrow, 5pm'
+ * - 'today, 3pm to 5pm (CDT)' (if `includeTz` is true)
+ * - '3pm today to 5pm tomorrow' (if `timeFirst` is true)
+ * - 'today to tomorrow' (if `dateOnly` is true)
+ *
+ * This uses `formatDateFriendlyString()` to format the individual dates and times.
+ *
+ * @param start The start date and time.
+ * @param end The end date and time.
+ * @param timezone The time zone to use for formatting.
+ * @param options Additional options for formatting the displayed date, taken from `formatDateFriendlyString()`.
+ * @returns Human-readable string representing the datetime range.
+ */
+export function formatDateRangeFriendly(start, end, timezone, { baseDate = new Date(), includeTz = true, timeFirst = false, dateOnly = false, } = {}) {
+    const { dateFormatted: startDateFormatted, timeFormatted: startTimeFormatted, timezoneFormatted, } = formatDateFriendlyParts(start, timezone, baseDate);
+    const { dateFormatted: endDateFormatted, timeFormatted: endTimeFormatted } = formatDateFriendlyParts(end, timezone, baseDate);
+    let result;
+    if (dateOnly) {
+        if (startDateFormatted === endDateFormatted) {
+            result = startDateFormatted;
+        }
+        else {
+            result = `${startDateFormatted} to ${endDateFormatted}`;
+        }
+    }
+    else {
+        if (startDateFormatted === endDateFormatted) {
+            let timeRangeFormatted;
+            if (startTimeFormatted === endTimeFormatted) {
+                timeRangeFormatted = startTimeFormatted;
+            }
+            else {
+                timeRangeFormatted = `${startTimeFormatted} to ${endTimeFormatted}`;
+            }
+            if (timeFirst) {
+                result = `${timeRangeFormatted} ${startDateFormatted}`;
+            }
+            else {
+                result = `${startDateFormatted}, ${timeRangeFormatted}`;
+            }
+        }
+        else {
+            if (timeFirst) {
+                result = `${startTimeFormatted} ${startDateFormatted} to ${endTimeFormatted} ${endDateFormatted}`;
+            }
+            else {
+                result = `${startDateFormatted}, ${startTimeFormatted} to ${endDateFormatted}, ${endTimeFormatted}`;
+            }
+        }
+    }
+    if (includeTz) {
+        result = `${result} ${timezoneFormatted}`;
+    }
+    return result;
+}
 //# sourceMappingURL=date.js.map

package/dist/date.js.map

@@ -1 +1 @@
-{"version":3,"file":"date.js","sourceRoot":"","sources":["../src/date.ts"],"names":[],"mappings":"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","sourcesContent":["import keyBy from 'lodash/keyBy.js';\n\n/**\n * Format a date to a human-readable string like '2020-03-27T12:34:56 (CDT)'.\n *\n * @param date The date to format.\n * @param timeZone The time zone to use for formatting.\n * @param param2.includeTz Whether to include the time zone in the output (default true).\n * @param param2.longTz Whether to use the long time zone name (default false).\n * @returns Human-readable string representing the date.\n */\nexport function formatDate(\n  date: Date,\n  timeZone: string,\n  {\n    includeTz = true,\n    longTz = false,\n    includeMs = false,\n  }: { includeTz?: boolean; longTz?: boolean; includeMs?: boolean } = {},\n): string {\n  const options: Intl.DateTimeFormatOptions = {\n    timeZone,\n    hourCycle: 'h23',\n    year: 'numeric',\n    month: '2-digit',\n    day: '2-digit',\n    hour: '2-digit',\n    minute: '2-digit',\n    second: '2-digit',\n    fractionalSecondDigits: includeMs ? 3 : undefined,\n    timeZoneName: longTz ? 'long' : 'short',\n  };\n  const parts = keyBy(new Intl.DateTimeFormat('en-US', options).formatToParts(date), (x) => x.type);\n  let dateFormatted = `${parts.year.value}-${parts.month.value}-${parts.day.value} ${parts.hour.value}:${parts.minute.value}:${parts.second.value}`;\n  if (includeMs) {\n    dateFormatted = `${dateFormatted}.${parts.fractionalSecond.value}`;\n  }\n  if (includeTz) {\n    dateFormatted = `${dateFormatted} (${parts.timeZoneName.value})`;\n  }\n  return dateFormatted;\n}\n\n/**\n * Format a date to a human-readable string like '2020-03-27'.\n *\n * @param date The date to format.\n * @param timeZone The time zone to use for formatting.\n * @returns Human-readable string representing the date.\n */\nexport function formatDateYMD(date: Date, timeZone: string): string {\n  const options: Intl.DateTimeFormatOptions = {\n    timeZone,\n    hourCycle: 'h23',\n    year: 'numeric',\n    month: '2-digit',\n    day: '2-digit',\n  };\n  const parts = keyBy(new Intl.DateTimeFormat('en-US', options).formatToParts(date), (x) => x.type);\n  return `${parts.year.value}-${parts.month.value}-${parts.day.value}`;\n}\n\n/**\n * Format a date to a human-readable string like '2020-03-27 14:27'.\n *\n * @param date The date to format.\n * @param timeZone The time zone to use for formatting.\n * @returns Human-readable string representing the date.\n */\nexport function formatDateYMDHM(date: Date, timeZone: string): string {\n  const options: Intl.DateTimeFormatOptions = {\n    timeZone,\n    hourCycle: 'h23',\n    year: 'numeric',\n    month: '2-digit',\n    day: '2-digit',\n    hour: '2-digit',\n    minute: '2-digit',\n  };\n  const parts = keyBy(new Intl.DateTimeFormat('en-US', options).formatToParts(date), (x) => x.type);\n  return `${parts.year.value}-${parts.month.value}-${parts.day.value} ${parts.hour.value}:${parts.minute.value}`;\n}\n\n/**\n * Format a time zone to a human-readable string like 'CDT'.\n *\n * @param timeZone The time zone to format.\n * @returns Human-readable string representing the time zone.\n */\nexport function formatTz(timeZone: string): string {\n  const date = new Date();\n  const parts = new Intl.DateTimeFormat('en-US', {\n    timeZone,\n    timeZoneName: 'short',\n  }).formatToParts(date);\n  const tz = parts.find((p) => p.type === 'timeZoneName');\n  return tz ? tz.value : timeZone;\n}\n"]}
+{"version":3,"file":"date.js","sourceRoot":"","sources":["../src/date.ts"],"names":[],"mappings":"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","sourcesContent":["import { toTemporalInstant } from '@js-temporal/polyfill';\nimport keyBy from 'lodash/keyBy.js';\n\n/**\n * Format a date to a human-readable string like '2020-03-27T12:34:56 (CDT)'.\n *\n * @param date The date to format.\n * @param timeZone The time zone to use for formatting.\n * @param param2.includeTz Whether to include the time zone in the output (default true).\n * @param param2.longTz Whether to use the long time zone name (default false).\n * @returns Human-readable string representing the date.\n */\nexport function formatDate(\n  date: Date,\n  timeZone: string,\n  {\n    includeTz = true,\n    longTz = false,\n    includeMs = false,\n  }: { includeTz?: boolean; longTz?: boolean; includeMs?: boolean } = {},\n): string {\n  const options: Intl.DateTimeFormatOptions = {\n    timeZone,\n    hourCycle: 'h23',\n    year: 'numeric',\n    month: '2-digit',\n    day: '2-digit',\n    hour: '2-digit',\n    minute: '2-digit',\n    second: '2-digit',\n    fractionalSecondDigits: includeMs ? 3 : undefined,\n    timeZoneName: longTz ? 'long' : 'short',\n  };\n  const parts = keyBy(new Intl.DateTimeFormat('en-US', options).formatToParts(date), (x) => x.type);\n  let dateFormatted = `${parts.year.value}-${parts.month.value}-${parts.day.value} ${parts.hour.value}:${parts.minute.value}:${parts.second.value}`;\n  if (includeMs) {\n    dateFormatted = `${dateFormatted}.${parts.fractionalSecond.value}`;\n  }\n  if (includeTz) {\n    dateFormatted = `${dateFormatted} (${parts.timeZoneName.value})`;\n  }\n  return dateFormatted;\n}\n\n/**\n * Format a date to a human-readable string like '2020-03-27'.\n *\n * @param date The date to format.\n * @param timeZone The time zone to use for formatting.\n * @returns Human-readable string representing the date.\n */\nexport function formatDateYMD(date: Date, timeZone: string): string {\n  const options: Intl.DateTimeFormatOptions = {\n    timeZone,\n    hourCycle: 'h23',\n    year: 'numeric',\n    month: '2-digit',\n    day: '2-digit',\n  };\n  const parts = keyBy(new Intl.DateTimeFormat('en-US', options).formatToParts(date), (x) => x.type);\n  return `${parts.year.value}-${parts.month.value}-${parts.day.value}`;\n}\n\n/**\n * Format a date to a human-readable string like '2020-03-27 14:27'.\n *\n * @param date The date to format.\n * @param timeZone The time zone to use for formatting.\n * @returns Human-readable string representing the date.\n */\nexport function formatDateYMDHM(date: Date, timeZone: string): string {\n  const options: Intl.DateTimeFormatOptions = {\n    timeZone,\n    hourCycle: 'h23',\n    year: 'numeric',\n    month: '2-digit',\n    day: '2-digit',\n    hour: '2-digit',\n    minute: '2-digit',\n  };\n  const parts = keyBy(new Intl.DateTimeFormat('en-US', options).formatToParts(date), (x) => x.type);\n  return `${parts.year.value}-${parts.month.value}-${parts.day.value} ${parts.hour.value}:${parts.minute.value}`;\n}\n\n/**\n * Format a time zone to a human-readable string like 'CDT'.\n *\n * @param timeZone The time zone to format.\n * @returns Human-readable string representing the time zone.\n */\nexport function formatTz(timeZone: string): string {\n  const date = new Date();\n  const parts = new Intl.DateTimeFormat('en-US', {\n    timeZone,\n    timeZoneName: 'short',\n  }).formatToParts(date);\n  const tz = parts.find((p) => p.type === 'timeZoneName');\n  return tz ? tz.value : timeZone;\n}\n\n/**\n * Format a date to a human-readable string like '14:27:00 (CDT)'.\n *\n * @param date The date to format.\n * @param timeZone The time zone to use for formatting.\n * @param param2.includeTz Whether to include the time zone in the output (default true).\n * @returns Human-readable string representing the date.\n */\nexport function formatDateHMS(\n  date: Date,\n  timeZone: string,\n  { includeTz = true }: { includeTz?: boolean } = {},\n): string {\n  const options: Intl.DateTimeFormatOptions = {\n    timeZone,\n    hourCycle: 'h23',\n    hour: '2-digit',\n    minute: '2-digit',\n    second: '2-digit',\n    timeZoneName: 'short',\n  };\n  const parts = keyBy(new Intl.DateTimeFormat('en-US', options).formatToParts(date), (x) => x.type);\n  let dateFormatted = `${parts.hour.value}:${parts.minute.value}:${parts.second.value}`;\n  if (includeTz) {\n    dateFormatted = `${dateFormatted} (${parts.timeZoneName.value})`;\n  }\n  return dateFormatted;\n}\n\n/**\n * Format a date to a human-readable string like '18:23' or 'May 2, 07:12',\n * where the precision is determined by the range.\n *\n * @param date The date to format.\n * @param rangeStart The start of the range.\n * @param rangeEnd The end of the range.\n * @param timeZone The time zone to use for formatting.\n * @returns Human-readable string representing the date.\n */\nexport function formatDateWithinRange(\n  date: Date,\n  rangeStart: Date,\n  rangeEnd: Date,\n  timeZone: string,\n): string {\n  const options: Intl.DateTimeFormatOptions = {\n    timeZone,\n    hourCycle: 'h23',\n    year: 'numeric',\n    month: '2-digit',\n    day: '2-digit',\n    hour: '2-digit',\n    minute: '2-digit',\n    timeZoneName: 'short',\n  };\n  const dateParts = keyBy(\n    new Intl.DateTimeFormat('en-US', options).formatToParts(date),\n    (x) => x.type,\n  );\n  const startParts = keyBy(\n    new Intl.DateTimeFormat('en-US', options).formatToParts(rangeStart),\n    (x) => x.type,\n  );\n  const endParts = keyBy(\n    new Intl.DateTimeFormat('en-US', options).formatToParts(rangeEnd),\n    (x) => x.type,\n  );\n\n  // format the date (not time) parts\n  const dateYMD = `${dateParts.year.value}-${dateParts.month.value}-${dateParts.day.value}`;\n  const startYMD = `${startParts.year.value}-${startParts.month.value}-${startParts.day.value}`;\n  const endYMD = `${endParts.year.value}-${endParts.month.value}-${endParts.day.value}`;\n\n  if (dateYMD === startYMD && dateYMD === endYMD) {\n    // only show the time if the date is the same for all three\n    return `${dateParts.hour.value}:${dateParts.minute.value}`;\n  }\n\n  // format the year, but not the month or day\n  const dateY = `${dateParts.year.value}`;\n  const startY = `${startParts.year.value}`;\n  const endY = `${endParts.year.value}`;\n\n  // if the year is the same for all three, show the month, day, and time\n  if (dateY === startY && dateY === endY) {\n    const options: Intl.DateTimeFormatOptions = {\n      timeZone,\n      month: 'short',\n      day: 'numeric',\n      hour: '2-digit',\n      minute: '2-digit',\n    };\n    const dateParts = keyBy(\n      new Intl.DateTimeFormat('en-US', options).formatToParts(date),\n      (x) => x.type,\n    );\n    return `${dateParts.month.value} ${dateParts.day.value}, ${dateParts.hour.value}:${dateParts.minute.value}`;\n  }\n\n  // fall back to the full date\n  return `${dateParts.year.value}-${dateParts.month.value}-${dateParts.day.value} ${dateParts.hour.value}:${dateParts.minute.value}`;\n}\n\n/**\n * Format a Date to date and time strings in the given time zone. The date is\n * formatted like\n * - 'today'\n * - 'Mon, Mar 20' (if within 180 days of the base date)\n * - 'Wed, Jan 1, 2020'\n *\n * The time format leaves off zero minutes and seconds, and uses 12-hour time,\n * giving strings like\n * - '3pm'\n * - '3:34pm'\n * - '3:34:17pm'\n *\n * @param date The date to format.\n * @param timezone The time zone to use for formatting.\n * @param baseDate The base date to use for comparison.\n */\nfunction formatDateFriendlyParts(\n  date: Date,\n  timezone: string,\n  baseDate: Date,\n): { dateFormatted: string; timeFormatted: string; timezoneFormatted: string } {\n  // compute the number of days from the base date (0 = today, 1 = tomorrow, etc.)\n\n  const baseZonedDateTime = toTemporalInstant.call(baseDate).toZonedDateTimeISO(timezone);\n  const zonedDateTime = toTemporalInstant.call(date).toZonedDateTimeISO(timezone);\n\n  const basePlainDate = baseZonedDateTime.toPlainDate();\n  const plainDate = zonedDateTime.toPlainDate();\n\n  const daysOffset = plainDate.since(basePlainDate, { largestUnit: 'day' }).days;\n\n  // format the parts of the date and time\n\n  const options: Intl.DateTimeFormatOptions = {\n    timeZone: timezone,\n    year: 'numeric',\n    month: 'short',\n    day: 'numeric',\n    weekday: 'short',\n    hourCycle: 'h12',\n    hour: 'numeric',\n    minute: '2-digit',\n    second: '2-digit',\n    timeZoneName: 'short',\n  };\n  const parts = keyBy(new Intl.DateTimeFormat('en-US', options).formatToParts(date), (x) => x.type);\n\n  // format the date string\n\n  let dateFormatted = '';\n  if (daysOffset === 0) {\n    dateFormatted = 'today';\n  } else if (daysOffset === 1) {\n    dateFormatted = 'tomorrow';\n  } else if (daysOffset === -1) {\n    dateFormatted = 'yesterday';\n  } else if (Math.abs(daysOffset) <= 180) {\n    // non-breaking-space (\\u00a0) is used between the month and day\n    dateFormatted = `${parts.weekday.value}, ${parts.month.value}\\u00a0${parts.day.value}`;\n  } else {\n    dateFormatted = `${parts.weekday.value}, ${parts.month.value}\\u00a0${parts.day.value}, ${parts.year.value}`;\n  }\n\n  // format the time string\n\n  let timeFormatted = '';\n  if (parts.minute.value === '00' && parts.second.value === '00') {\n    timeFormatted = `${parts.hour.value}`;\n  } else if (parts.second.value === '00') {\n    timeFormatted = `${parts.hour.value}:${parts.minute.value}`;\n  } else {\n    timeFormatted = `${parts.hour.value}:${parts.minute.value}:${parts.second.value}`;\n  }\n  // add the am/pm part\n  timeFormatted = `${timeFormatted}${parts.dayPeriod.value.toLowerCase()}`;\n\n  // format the timezone\n\n  const timezoneFormatted = `(${parts.timeZoneName.value})`;\n\n  return {\n    dateFormatted,\n    timeFormatted,\n    timezoneFormatted,\n  };\n}\n\n/**\n * Format a date to a string like:\n * - 'today, 3pm'\n * - 'tomorrow, 10:30am'\n * - 'yesterday, 11:45pm'\n * - 'Mon, Mar 20, 8:15am' (if within 180 days of the base date)\n * - 'Wed, Jan 1, 2020, 12pm'\n * - `today, 3pm (CDT)` (if `includeTz` is true)\n * - `3pm today` (if `timeFirst` is true)\n * - 'today' (if `dateOnly` is true)\n *\n * If using this within a sentence like `... at ${formatDateFriendlyString()}`,\n * use `timeFirst: true` to improve readability.\n *\n * @param date The date to format.\n * @param timezone The time zone to use for formatting.\n * @param param.baseDate The base date to use for comparison (default is the current date).\n * @param param.includeTz Whether to include the time zone in the output (default true).\n * @param param.timeFirst If true, the time is shown before the date (default false).\n * @param param.dateOnly If true, only the date is shown (default false).\n * @param param.timeOnly If true, only the time is shown (default false).\n * @returns Human-readable string representing the date and time.\n */\nexport function formatDateFriendly(\n  date: Date,\n  timezone: string,\n  {\n    baseDate = new Date(),\n    includeTz = true,\n    timeFirst = false,\n    dateOnly = false,\n    timeOnly = false,\n  }: {\n    baseDate?: Date;\n    includeTz?: boolean;\n    timeFirst?: boolean;\n    dateOnly?: boolean;\n    timeOnly?: boolean;\n  } = {},\n): string {\n  const { dateFormatted, timeFormatted, timezoneFormatted } = formatDateFriendlyParts(\n    date,\n    timezone,\n    baseDate,\n  );\n\n  let dateTimeFormatted = '';\n  if (dateOnly) {\n    dateTimeFormatted = dateFormatted;\n  } else if (timeOnly) {\n    dateTimeFormatted = timeFormatted;\n  } else {\n    if (timeFirst) {\n      dateTimeFormatted = `${timeFormatted} ${dateFormatted}`;\n    } else {\n      dateTimeFormatted = `${dateFormatted}, ${timeFormatted}`;\n    }\n  }\n  if (includeTz) {\n    dateTimeFormatted = `${dateTimeFormatted} ${timezoneFormatted}`;\n  }\n  return dateTimeFormatted;\n}\n\n/**\n * Format a datetime range to a string like:\n * - 'today, 10am'\n * - 'today, 3pm to 5pm'\n * - 'today, 3pm to tomorrow, 5pm'\n * - 'today, 3pm to 5pm (CDT)' (if `includeTz` is true)\n * - '3pm today to 5pm tomorrow' (if `timeFirst` is true)\n * - 'today to tomorrow' (if `dateOnly` is true)\n *\n * This uses `formatDateFriendlyString()` to format the individual dates and times.\n *\n * @param start The start date and time.\n * @param end The end date and time.\n * @param timezone The time zone to use for formatting.\n * @param options Additional options for formatting the displayed date, taken from `formatDateFriendlyString()`.\n * @returns Human-readable string representing the datetime range.\n */\nexport function formatDateRangeFriendly(\n  start: Date,\n  end: Date,\n  timezone: string,\n  {\n    baseDate = new Date(),\n    includeTz = true,\n    timeFirst = false,\n    dateOnly = false,\n  }: Parameters<typeof formatDateFriendly>[2] = {},\n): string {\n  const {\n    dateFormatted: startDateFormatted,\n    timeFormatted: startTimeFormatted,\n    timezoneFormatted,\n  } = formatDateFriendlyParts(start, timezone, baseDate);\n  const { dateFormatted: endDateFormatted, timeFormatted: endTimeFormatted } =\n    formatDateFriendlyParts(end, timezone, baseDate);\n\n  let result: string | undefined;\n  if (dateOnly) {\n    if (startDateFormatted === endDateFormatted) {\n      result = startDateFormatted;\n    } else {\n      result = `${startDateFormatted} to ${endDateFormatted}`;\n    }\n  } else {\n    if (startDateFormatted === endDateFormatted) {\n      let timeRangeFormatted: string | undefined;\n      if (startTimeFormatted === endTimeFormatted) {\n        timeRangeFormatted = startTimeFormatted;\n      } else {\n        timeRangeFormatted = `${startTimeFormatted} to ${endTimeFormatted}`;\n      }\n      if (timeFirst) {\n        result = `${timeRangeFormatted} ${startDateFormatted}`;\n      } else {\n        result = `${startDateFormatted}, ${timeRangeFormatted}`;\n      }\n    } else {\n      if (timeFirst) {\n        result = `${startTimeFormatted} ${startDateFormatted} to ${endTimeFormatted} ${endDateFormatted}`;\n      } else {\n        result = `${startDateFormatted}, ${startTimeFormatted} to ${endDateFormatted}, ${endTimeFormatted}`;\n      }\n    }\n  }\n  if (includeTz) {\n    result = `${result} ${timezoneFormatted}`;\n  }\n  return result;\n}\n"]}