npm - @prairielearn/formatter - Versions diffs - 1.4.0 → 1.4.2 - Mend

@prairielearn/formatter 1.4.0 → 1.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,17 @@
 # @prairielearn/formatter
+## 1.4.2
+### Patch Changes
+- 7f25a8a: Add `maxPrecision` and `minPrecision` options to `format*Friendly` functions.
+## 1.4.1
+### Patch Changes
+- 678b48a: Upgrade all JavaScript dependencies
 ## 1.4.0
 ### Minor Changes

package/dist/date.d.ts CHANGED Viewed

@@ -1,3 +1,4 @@
+type TimePrecision = 'hour' | 'minute' | 'second';
 /**
  * Format a date to a human-readable string like '2020-03-27T12:34:56 (CDT)'.
  *
@@ -78,14 +79,18 @@ export declare function formatDateWithinRange(date: Date, rangeStart: Date, rang
  * @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).
+ * @param param.maxPrecision The maximum precision to show for time (default 'minute').
+ * @param param.minPrecision The minimum precision to always show for time (default 'hour').
  * @returns Human-readable string representing the date and time.
  */
-export declare function formatDateFriendly(date: Date, timezone: string, { baseDate, includeTz, timeFirst, dateOnly, timeOnly, }?: {
+export declare function formatDateFriendly(date: Date, timezone: string, { baseDate, includeTz, timeFirst, dateOnly, timeOnly, maxPrecision, minPrecision, }?: {
     baseDate?: Date;
     includeTz?: boolean;
     timeFirst?: boolean;
     dateOnly?: boolean;
     timeOnly?: boolean;
+    maxPrecision?: TimePrecision;
+    minPrecision?: TimePrecision;
 }): string;
 /**
  * Format a datetime range to a string like:
@@ -104,4 +109,5 @@ export declare function formatDateFriendly(date: Date, timezone: string, { baseD
  * @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;
+export declare function formatDateRangeFriendly(start: Date, end: Date, timezone: string, { baseDate, includeTz, timeFirst, dateOnly, maxPrecision, minPrecision, }?: Parameters<typeof formatDateFriendly>[2]): string;
+export {};

package/dist/date.js CHANGED Viewed

@@ -173,11 +173,16 @@ export function formatDateWithinRange(date, rangeStart, rangeEnd, timeZone) {
  * - '3:34pm'
  * - '3:34:17pm'
  *
+ * maxPrecision must be an equal or smaller unit than minPrecision.
+ *
  * @param date The date to format.
  * @param timezone The time zone to use for formatting.
  * @param baseDate The base date to use for comparison.
+ * @param maxPrecision Only show units as large or larger than the max precision.
+ * @param minPrecision Always show that unit and larger, potentially showing smaller units.
+ *
  */
-function formatDateFriendlyParts(date, timezone, baseDate) {
+function formatDateFriendlyParts(date, timezone, baseDate, maxPrecision = 'second', minPrecision = 'hour') {
     // 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);
@@ -216,16 +221,50 @@ function formatDateFriendlyParts(date, timezone, baseDate) {
     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}`;
+    const precisionOrder = ['second', 'minute', 'hour'];
+    const maxIndex = precisionOrder.indexOf(maxPrecision);
+    const minIndex = precisionOrder.indexOf(minPrecision);
+    /**
+     * The maximum precision must be a unit smaller than or equal to the minimum precision, otherwise the rules will contradict each other.
+     *
+     * If max is a larger unit than min, e.g. max = hour, min = minute, then by "min"
+     * we must display minute and smaller but by "max" we can display hour and larger, which is a contradiction.
+     *
+     * If min is a larger unit than max, e.g. max = minute, min = hour, then by "min" we must display
+     * hour and smaller and by "max" we can display minutes and larger. These do not contradict each other.
+     *
+     *  V min/max > | h | m | s
+     *  h           | X | X | X
+     *  m           | I | X | X
+     *  s           | I | I | X
+     *
+     * X - valid configuration
+     * I - invalid configuration
+     */
+    // A higher index corresponds to a larger unit, so if maxIndex is larger than minIndex, then the rules contradict each other.
+    if (maxIndex > minIndex) {
+        throw new Error('maxPrecision must be an equal or smaller unit than minPrecision.');
     }
-    else if (parts.second.value === '00') {
-        timeFormatted = `${parts.hour.value}:${parts.minute.value}`;
+    /** Examples:
+     * min=h, max=h: 0:00:00AM -> 0AM, 0:00:01AM -> 0AM, 0:01:01AM -> 0AM
+     * min=h, max=m: 0:00:00AM -> 0AM, 0:00:01AM -> 0AM, 0:01:01AM -> 0:01AM
+     * min=h, max=s: 0:00:00AM -> 0AM, 0:00:01AM -> 0:00:01AM, 0:01:01AM -> 0:01:01AM
+     *
+     * min=m, max=m: 0:00:00AM -> 0:00AM, 0:00:01AM -> 0:00AM, 0:01:01AM -> 0:00AM
+     * min=m, max=s: 0:00:00AM -> 0:00AM, 0:00:01AM -> 0:00AM, 0:01:01AM -> 0:01:01AM
+     *
+     * min=s, max=s: 0:00:00AM -> 0:00:00AM, 0:00:01AM -> 0:00:01AM, 0:01:01AM -> 0:01:01AM
+     */
+    let timeFormatted = parts.hour.value;
+    const shouldShowMinutes = ['minute', 'second'].includes(minPrecision) ||
+        (maxPrecision === 'minute' && parts.minute.value !== '00') ||
+        (maxPrecision === 'second' && (parts.minute.value !== '00' || parts.second.value !== '00'));
+    if (shouldShowMinutes) {
+        timeFormatted += `:${parts.minute.value}`;
     }
-    else {
-        timeFormatted = `${parts.hour.value}:${parts.minute.value}:${parts.second.value}`;
+    const shouldShowSeconds = minPrecision === 'second' || (maxPrecision === 'second' && parts.second.value !== '00');
+    if (shouldShowSeconds) {
+        timeFormatted += `:${parts.second.value}`;
     }
     // add the am/pm part
     timeFormatted = `${timeFormatted}${parts.dayPeriod.value.toLowerCase()}`;
@@ -258,10 +297,12 @@ function formatDateFriendlyParts(date, timezone, baseDate) {
  * @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).
+ * @param param.maxPrecision The maximum precision to show for time (default 'minute').
+ * @param param.minPrecision The minimum precision to always show for time (default 'hour').
  * @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);
+export function formatDateFriendly(date, timezone, { baseDate = new Date(), includeTz = true, timeFirst = false, dateOnly = false, timeOnly = false, maxPrecision = 'second', minPrecision = 'hour', } = {}) {
+    const { dateFormatted, timeFormatted, timezoneFormatted } = formatDateFriendlyParts(date, timezone, baseDate, maxPrecision, minPrecision);
     let dateTimeFormatted = '';
     if (dateOnly) {
         dateTimeFormatted = dateFormatted;
@@ -299,9 +340,9 @@ export function formatDateFriendly(date, timezone, { baseDate = new Date(), incl
  * @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);
+export function formatDateRangeFriendly(start, end, timezone, { baseDate = new Date(), includeTz = true, timeFirst = false, dateOnly = false, maxPrecision = 'second', minPrecision = 'hour', } = {}) {
+    const { dateFormatted: startDateFormatted, timeFormatted: startTimeFormatted, timezoneFormatted, } = formatDateFriendlyParts(start, timezone, baseDate, maxPrecision, minPrecision);
+    const { dateFormatted: endDateFormatted, timeFormatted: endTimeFormatted } = formatDateFriendlyParts(end, timezone, baseDate, maxPrecision, minPrecision);
     let result;
     if (dateOnly) {
         if (startDateFormatted === endDateFormatted) {

package/dist/date.js.map CHANGED Viewed