@prairielearn/formatter 1.3.14 → 1.4.1

package/src/date.ts

@@ -1,3 +1,4 @@
+import { toTemporalInstant } from '@js-temporal/polyfill';
 import keyBy from 'lodash/keyBy.js';
 
 /**
@@ -96,3 +97,328 @@ export function formatTz(timeZone: string): string {
   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: Date,
+  timeZone: string,
+  { includeTz = true }: { includeTz?: boolean } = {},
+): string {
+  const options: Intl.DateTimeFormatOptions = {
+    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: Date,
+  rangeStart: Date,
+  rangeEnd: Date,
+  timeZone: string,
+): string {
+  const options: Intl.DateTimeFormatOptions = {
+    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: Intl.DateTimeFormatOptions = {
+      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: Date,
+  timezone: string,
+  baseDate: Date,
+): { dateFormatted: string; timeFormatted: string; timezoneFormatted: string } {
+  // 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: Intl.DateTimeFormatOptions = {
+    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: Date,
+  timezone: string,
+  {
+    baseDate = new Date(),
+    includeTz = true,
+    timeFirst = false,
+    dateOnly = false,
+    timeOnly = false,
+  }: {
+    baseDate?: Date;
+    includeTz?: boolean;
+    timeFirst?: boolean;
+    dateOnly?: boolean;
+    timeOnly?: boolean;
+  } = {},
+): string {
+  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: Date,
+  end: Date,
+  timezone: string,
+  {
+    baseDate = new Date(),
+    includeTz = true,
+    timeFirst = false,
+    dateOnly = false,
+  }: Parameters<typeof formatDateFriendly>[2] = {},
+): string {
+  const {
+    dateFormatted: startDateFormatted,
+    timeFormatted: startTimeFormatted,
+    timezoneFormatted,
+  } = formatDateFriendlyParts(start, timezone, baseDate);
+  const { dateFormatted: endDateFormatted, timeFormatted: endTimeFormatted } =
+    formatDateFriendlyParts(end, timezone, baseDate);
+
+  let result: string | undefined;
+  if (dateOnly) {
+    if (startDateFormatted === endDateFormatted) {
+      result = startDateFormatted;
+    } else {
+      result = `${startDateFormatted} to ${endDateFormatted}`;
+    }
+  } else {
+    if (startDateFormatted === endDateFormatted) {
+      let timeRangeFormatted: string | undefined;
+      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;
+}

package/src/index.ts

@@ -1,2 +1,16 @@
-export { formatDate, formatDateYMD, formatDateYMDHM, formatTz } from './date.js';
-export { formatInterval } from './interval.js';
+export {
+  formatDate,
+  formatDateFriendly,
+  formatDateRangeFriendly,
+  formatDateWithinRange,
+  formatDateYMD,
+  formatDateYMDHM,
+  formatTz,
+} from './date.js';
+export {
+  formatInterval,
+  formatIntervalHM,
+  formatIntervalMinutes,
+  formatIntervalRelative,
+  makeInterval,
+} from './interval.js';

package/src/interval.test.ts

@@ -1,6 +1,12 @@
 import { assert, describe, it } from 'vitest';
 
-import { formatInterval } from './interval.js';
+import {
+  formatInterval,
+  formatIntervalHM,
+  formatIntervalMinutes,
+  formatIntervalRelative,
+  makeInterval,
+} from './interval.js';
 
 describe('interval formatting', () => {
   describe('formatInterval()', () => {
@@ -32,4 +38,78 @@ describe('interval formatting', () => {
       );
     });
   });
+  describe('formatIntervalRelative()', () => {
+    it('should handle positive intervals', () => {
+      assert.equal(
+        formatIntervalRelative(3 * 1000, 'Until', 'the start time'),
+        'Until 3 s after the start time',
+      );
+    });
+    it('should handle negative intervals', () => {
+      assert.equal(
+        formatIntervalRelative(-7 * 60 * 1000, 'From', 'the start time'),
+        'From 7 min before the start time',
+      );
+    });
+    it('should handle zero intervals', () => {
+      assert.equal(formatIntervalRelative(0, 'From', 'the start time'), 'From the start time');
+    });
+  });
+
+  describe('formatIntervalMinutes()', () => {
+    it('should correctly round up', () => {
+      assert.equal(formatIntervalMinutes(3.2 * 60 * 1000), '4 minutes');
+    });
+    it('should correctly handle 1 minute', () => {
+      assert.equal(formatIntervalMinutes(17 * 1000), '1 minute');
+    });
+    it('should correctly handle zero', () => {
+      assert.equal(formatIntervalMinutes(0), '0 minutes');
+    });
+    it('should correctly handle -1 minute', () => {
+      assert.equal(formatIntervalMinutes(-17 * 1000), '-1 minute');
+    });
+    it('should correctly handle negative intervals', () => {
+      assert.equal(formatIntervalMinutes(-3.2 * 60 * 1000), '-4 minutes');
+    });
+  });
+
+  describe('formatIntervalHM()', () => {
+    it('should correctly handle postive minutes', () => {
+      assert.equal(formatIntervalHM(3.2 * 60 * 1000), '00:03');
+    });
+    it('should correctly handle postive hours', () => {
+      assert.equal(formatIntervalHM((4 * 60 + 17.8) * 60 * 1000), '04:17');
+    });
+    it('should correctly handle large postive hours', () => {
+      assert.equal(formatIntervalHM((143 * 60 + 17.8) * 60 * 1000), '143:17');
+    });
+    it('should correctly handle an explicit sign', () => {
+      assert.equal(formatIntervalHM((4 * 60 + 17.8) * 60 * 1000, { signed: true }), '+04:17');
+    });
+    it('should correctly handle negative minutes', () => {
+      assert.equal(formatIntervalHM(-3.2 * 60 * 1000), '-00:03');
+    });
+    it('should correctly handle negative hours', () => {
+      assert.equal(formatIntervalHM(-(4 * 60 + 17.8) * 60 * 1000), '-04:17');
+    });
+  });
+
+  describe('makeInterval()', () => {
+    it('should handle seconds', () => {
+      assert.equal(makeInterval({ seconds: 7 }), 7 * 1000);
+    });
+    it('should handle minutes', () => {
+      assert.equal(makeInterval({ minutes: 2 }), 2 * 60 * 1000);
+    });
+    it('should handle hours', () => {
+      assert.equal(makeInterval({ hours: 3 }), 3 * 60 * 60 * 1000);
+    });
+    it('should handle days', () => {
+      assert.equal(makeInterval({ days: 4 }), 4 * 24 * 60 * 60 * 1000);
+    });
+    it('should default to zero', () => {
+      assert.equal(makeInterval({}), 0);
+    });
+  });
 });

package/src/interval.ts

@@ -3,6 +3,28 @@ export const MINUTE_IN_MILLISECONDS = 60 * SECOND_IN_MILLISECONDS;
 export const HOUR_IN_MILLISECONDS = 60 * MINUTE_IN_MILLISECONDS;
 export const DAY_IN_MILLISECONDS = 24 * HOUR_IN_MILLISECONDS;
 
+/**
+ * Makes an interval (in milliseconds).
+ *
+ * @param param.days The number of days in the interval.
+ * @param param.hours The number of hours in the interval.
+ * @param param.minutes The number of minutes in the interval.
+ * @param param.seconds The number of seconds in the interval.
+ */
+export function makeInterval({
+  days = 0,
+  hours = 0,
+  minutes = 0,
+  seconds = 0,
+}: {
+  days?: number;
+  hours?: number;
+  minutes?: number;
+  seconds?: number;
+}): number {
+  return (((days * 24 + hours) * 60 + minutes) * 60 + seconds) * 1000;
+}
+
 /**
  * Format an interval (in milliseconds) to a human-readable string like '3 h 40 m'.
  *
@@ -37,3 +59,61 @@ export function formatInterval(interval: number): string {
 
   return parts.join(' ');
 }
+
+/**
+ * Format an interval (in milliseconds) to a human-readable string like 'Until 6
+ * minutes before the session start time'.
+ *
+ * @param interval Time interval in milliseconds relative to `reference` (positive intervals are after `reference`).
+ * @param prefix The prefix to use, must be 'Until' or 'From' (or lowercase versions of these).
+ * @param reference The reference time, for example 'session start time'.
+ * @returns Human-readable string representing the interval.
+ */
+export function formatIntervalRelative(
+  interval: number,
+  prefix: 'Until' | 'until' | 'From' | 'from',
+  reference: string,
+): string {
+  if (interval > 0) {
+    return `${prefix} ${formatInterval(interval)} after ${reference}`;
+  } else if (interval < 0) {
+    return `${prefix} ${formatInterval(-interval)} before ${reference}`;
+  } else if (interval === 0) {
+    return `${prefix} ${reference}`;
+  } else {
+    return `Invalid interval: ${interval}`;
+  }
+}
+
+/**
+ * Format an interval (in milliseconds) to a human-readable string like HH:MM or +HH:MM.
+ *
+ * @param interval Time interval in milliseconds.
+ * @param options.signed Whether to include the sign in the output.
+ * @returns Human-readable string representing the interval in minutes.
+ */
+export function formatIntervalHM(
+  interval: number,
+  { signed = false }: { signed?: boolean } = { signed: false },
+): string {
+  const sign = interval < 0 ? '-' : interval > 0 ? (signed ? '+' : '') : '';
+  const hours = Math.floor(Math.abs(interval) / HOUR_IN_MILLISECONDS);
+  const mins = Math.floor(Math.abs(interval) / MINUTE_IN_MILLISECONDS) % 60;
+  return `${sign}${hours.toString().padStart(2, '0')}:${mins.toString().padStart(2, '0')}`;
+}
+
+/**
+ * Format an interval (in milliseconds) to a human-readable string with the number of minutes, like '7 minutes' or '1 minute'.
+ *
+ * @param interval Time interval in milliseconds.
+ * @returns Human-readable string representing the interval in minutes.
+ */
+export function formatIntervalMinutes(interval: number): string {
+  const sign = interval < 0 ? '-' : '';
+  const minutes = Math.ceil(Math.abs(interval / MINUTE_IN_MILLISECONDS));
+  if (minutes === 1) {
+    return `${sign}1 minute`;
+  } else {
+    return `${sign}${minutes} minutes`;
+  }
+}