@superdispatch/dates 0.21.6 → 0.21.13

package/src/date-time-utils/DateTimeUtils.ts

@@ -0,0 +1,339 @@
+import { DateTime, Settings, ToRelativeOptions, ToRelativeUnit } from 'luxon';
+import {
+  DateConfig,
+  DateFormat,
+  defaultDateConfig,
+} from '../date-config/DateConfig';
+
+//
+// Config
+//
+export type DateDisplayVariant = 'Date' | 'ShortDate' | 'Time' | 'DateTime';
+
+const DATE_FORMATS: Readonly<Record<DateFormat, string>> = {
+  DateISO: '',
+  DateTimeISO: '',
+  JodaISO: "yyyy-MM-dd'T'HH:mm:ss.SSSZZZ",
+};
+
+const DATE_DISPLAY_VARIANTS: Readonly<
+  Record<DateDisplayVariant, Intl.DateTimeFormatOptions>
+> = {
+  Date: {
+    day: '2-digit',
+    month: 'short',
+    year: 'numeric',
+  },
+  ShortDate: {
+    day: '2-digit',
+    month: 'short',
+  },
+  Time: {
+    hour: 'numeric',
+    minute: 'numeric',
+  },
+  DateTime: {
+    day: '2-digit',
+    month: 'short',
+    year: 'numeric',
+    hour: 'numeric',
+    minute: 'numeric',
+  },
+};
+
+//
+// Date Utils
+//
+
+export type DateString = string;
+export type NullableDateString = null | undefined | DateString;
+export type PrimitiveDateInput = number | DateString;
+export type NullableDateInput =
+  | null
+  | undefined
+  | Date
+  | DateTime
+  | PrimitiveDateInput;
+
+export function toPrimitiveDateInput(
+  input: NullableDateInput,
+): PrimitiveDateInput {
+  if (typeof input == 'number' || typeof input == 'string') {
+    return input;
+  }
+
+  if (input instanceof Date || input instanceof DateTime) {
+    return input.valueOf();
+  }
+
+  return NaN;
+}
+
+export function parseDate(
+  input: NullableDateInput,
+  { format }: DateConfig = defaultDateConfig,
+): DateTime {
+  if (input instanceof DateTime) {
+    const { defaultZone } = Settings;
+
+    if (!defaultZone.equals(input.zone)) {
+      return input.setZone(defaultZone);
+    }
+
+    return input;
+  }
+
+  if (input instanceof Date) {
+    return DateTime.fromJSDate(input);
+  }
+
+  if (typeof input === 'number') {
+    return DateTime.fromMillis(input);
+  }
+
+  if (typeof input == 'string') {
+    switch (format) {
+      case 'DateISO':
+      case 'DateTimeISO':
+        return DateTime.fromISO(input);
+      default:
+        return DateTime.fromFormat(input, DATE_FORMATS[format]);
+    }
+  }
+
+  return DateTime.invalid('invalid input');
+}
+
+export function stringifyDate(
+  input: NullableDateInput,
+  config: DateConfig = defaultDateConfig,
+): string | null {
+  const date = parseDate(input, config);
+
+  if (date.isValid) {
+    const { format } = config;
+
+    switch (format) {
+      case 'DateISO':
+        return date.toISODate();
+      case 'DateTimeISO':
+        return date.toISO();
+      default:
+        return date.toFormat(DATE_FORMATS[format]);
+    }
+  }
+
+  return null;
+}
+
+export interface FormatDateConfig {
+  fallback?: string;
+  variant: DateDisplayVariant;
+}
+
+export function formatDate(
+  input: NullableDateInput,
+  { variant, fallback = 'Invalid Date' }: FormatDateConfig,
+  config: DateConfig = defaultDateConfig,
+): string {
+  const date = parseDate(input, config);
+
+  if (!date.isValid) {
+    return fallback;
+  }
+
+  return date.toLocaleString(DATE_DISPLAY_VARIANTS[variant]);
+}
+
+function formatUnit(unit: ToRelativeUnit): string {
+  switch (unit) {
+    case 'months':
+      return 'mo';
+    default:
+      return unit.charAt(0);
+  }
+}
+
+export interface FormatRelativeTimeOptions
+  extends Pick<ToRelativeOptions, 'round' | 'padding'> {
+  fallback?: string;
+  unit?: ToRelativeUnit;
+  base?: NullableDateInput;
+}
+
+export function formatRelativeTime(
+  input: NullableDateInput,
+  {
+    round = true,
+
+    unit: unitOption,
+    base: baseOption,
+    padding: paddingOption,
+    fallback = 'Invalid Date',
+  }: FormatRelativeTimeOptions = {},
+  config: DateConfig = defaultDateConfig,
+): string {
+  const base =
+    baseOption == null ? DateTime.now() : parseDate(baseOption, config);
+  const date = parseDate(input, config);
+  const padding = paddingOption
+    ? date < base
+      ? -paddingOption
+      : paddingOption
+    : 0;
+
+  function format(value: number, unit: ToRelativeUnit): string {
+    const isPast = Object.is(value, -0) || value < 0;
+    const diff = Math.abs(!round ? value : Math.trunc(value));
+    const formattedUnit = formatUnit(unit);
+
+    return isPast
+      ? `${diff}${formattedUnit} ago`
+      : `in ${diff}${formattedUnit}`;
+  }
+
+  function differ(unit: ToRelativeUnit): number {
+    return date.plus(padding).diff(base, unit).get(unit);
+  }
+
+  if (date.isValid && base.isValid) {
+    const units: ToRelativeUnit[] = [
+      'years',
+      'months',
+      'days',
+      'hours',
+      'minutes',
+      'seconds',
+    ];
+
+    if (unitOption) {
+      return format(differ(unitOption), unitOption);
+    }
+
+    for (const unit of units) {
+      const diff = differ(unit);
+
+      if (Math.abs(diff) >= 1) {
+        return format(diff, unit);
+      }
+    }
+
+    return format(0, 'seconds');
+  }
+
+  return fallback;
+}
+
+export interface DatePayload {
+  readonly config: DateConfig;
+  readonly dateValue: DateTime;
+  readonly stringValue: null | DateString;
+}
+
+export function toDatePayload(
+  input: NullableDateInput,
+  config: DateConfig = defaultDateConfig,
+): DatePayload {
+  const dateValue = parseDate(input, config);
+
+  return {
+    config,
+    dateValue,
+    stringValue: stringifyDate(dateValue, config),
+  };
+}
+
+//
+// Date Range Utils
+//
+
+export type DateTimeRange = [null | DateTime, null | DateTime];
+export type DateStringRange = [null | DateString, null | DateString];
+export type NullableDateRangeInput =
+  | null
+  | undefined
+  | [NullableDateInput?, NullableDateInput?];
+export type PrimitiveDateRangeInput = [
+  undefined | PrimitiveDateInput,
+  undefined | PrimitiveDateInput,
+];
+
+export function toPrimitiveDateRangeInput(
+  input: NullableDateRangeInput,
+): PrimitiveDateRangeInput {
+  if (!Array.isArray(input)) {
+    return [undefined, undefined];
+  }
+
+  return [toPrimitiveDateInput(input[0]), toPrimitiveDateInput(input[1])];
+}
+
+export function parseDateRange(
+  input: NullableDateRangeInput,
+  config?: DateConfig,
+): DateTimeRange {
+  let start: null | DateTime = null;
+  let finish: null | DateTime = null;
+
+  if (Array.isArray(input)) {
+    [start = null, finish = null] = input
+      .map((value) => parseDate(value, config))
+      .filter((date) => date.isValid)
+      .sort((a, b) => a.valueOf() - b.valueOf());
+  }
+
+  return [start, finish];
+}
+
+export function stringifyDateRange(
+  input: NullableDateRangeInput,
+  config?: DateConfig,
+): DateStringRange {
+  const [start, finish] = parseDateRange(input, config);
+
+  return [stringifyDate(start, config), stringifyDate(finish, config)];
+}
+
+export interface FormatDateRangeOptions {
+  fallback?: string;
+}
+
+export function formatDateRange(
+  input: NullableDateRangeInput,
+  { fallback = 'Invalid Date Range' }: FormatDateRangeOptions,
+  config: DateConfig = defaultDateConfig,
+): string {
+  const [start, finish] = parseDateRange(input, config);
+
+  if (!start) {
+    return fallback;
+  }
+
+  const startVariant: DateDisplayVariant = !finish?.hasSame(start, 'year')
+    ? 'Date'
+    : 'ShortDate';
+
+  const startText = formatDate(start, { variant: startVariant }, config);
+  const finishText = !finish ? '…' : formatDate(finish, { variant: 'Date' });
+
+  return `${startText} - ${finishText}`;
+}
+
+export interface DateRangePayload {
+  config: DateConfig;
+  dateValue: DateTimeRange;
+  stringValue: DateStringRange;
+}
+
+export function toDateRangePayload(
+  input: NullableDateRangeInput,
+  config: DateConfig = defaultDateConfig,
+): DateRangePayload {
+  const dateValue = parseDateRange(input, config);
+
+  return {
+    config,
+    dateValue,
+    stringValue: stringifyDateRange(dateValue, config),
+  };
+}

package/src/date-utils/DateUtils.spec.ts

@@ -0,0 +1,234 @@
+import { setDefaultTimeZone } from '../date-config/DateConfig';
+import {
+  DateObject,
+  DateUtils,
+  isDate,
+  isDateLike,
+  isDateRange,
+  isDateRangeLike,
+  isValidDate,
+  isValidDateRange,
+  NullableDateLike,
+  toDate,
+  toDateRange,
+} from './DateUtils';
+
+function invalidDate() {
+  return new Date(NaN);
+}
+
+function stubDateObject({
+  year = 2019,
+  month = 5,
+  day = 24,
+  hour = 1,
+  minute = 2,
+  second = 3,
+  millisecond = 45,
+}: Partial<DateObject> = {}): DateObject {
+  return {
+    year,
+    month,
+    day,
+    hour,
+    minute,
+    second,
+    millisecond,
+  };
+}
+
+function stubTimestamp(values?: Partial<DateObject>): number {
+  const { year, month, day, hour, minute, second, millisecond } =
+    stubDateObject(values);
+
+  return Date.UTC(year, month - 1, day, hour, minute, second, millisecond);
+}
+function stubDate(values?: Partial<DateObject>): Date {
+  return new Date(stubTimestamp(values));
+}
+
+beforeEach(() => {
+  setDefaultTimeZone('local');
+});
+
+test.each`
+  input                        | date     | dateLike | validDate
+  ${null}                      | ${false} | ${false} | ${false}
+  ${undefined}                 | ${false} | ${false} | ${false}
+  ${''}                        | ${false} | ${false} | ${false}
+  ${NaN}                       | ${false} | ${false} | ${false}
+  ${Infinity}                  | ${false} | ${false} | ${false}
+  ${0}                         | ${false} | ${true}  | ${false}
+  ${0.1}                       | ${false} | ${false} | ${false}
+  ${Date.UTC(2020, 0)}         | ${false} | ${true}  | ${false}
+  ${new Date(0)}               | ${true}  | ${true}  | ${true}
+  ${invalidDate()}             | ${true}  | ${true}  | ${false}
+  ${new Date(0).toISOString()} | ${false} | ${false} | ${false}
+`('validates "$input"', ({ input, date, dateLike, validDate }) => {
+  expect(isDate(input)).toBe(date);
+  expect(isDateLike(input)).toBe(dateLike);
+  expect(isValidDate(input)).toBe(validDate);
+});
+
+test.each`
+  input                                                  | range    | rangeLike | validRange
+  ${null}                                                | ${false} | ${false}  | ${false}
+  ${undefined}                                           | ${false} | ${false}  | ${false}
+  ${{}}                                                  | ${false} | ${false}  | ${false}
+  ${''}                                                  | ${false} | ${false}  | ${false}
+  ${[]}                                                  | ${true}  | ${true}   | ${true}
+  ${[stubTimestamp()]}                                   | ${false} | ${true}   | ${false}
+  ${[stubTimestamp(), stubTimestamp()]}                  | ${false} | ${true}   | ${false}
+  ${[stubTimestamp(), stubTimestamp(), stubTimestamp()]} | ${false} | ${false}  | ${false}
+  ${[stubDate()]}                                        | ${true}  | ${true}   | ${true}
+  ${[stubDate(), stubDate()]}                            | ${true}  | ${true}   | ${true}
+  ${[stubDate(), stubDate(), stubDate()]}                | ${false} | ${false}  | ${false}
+  ${[invalidDate()]}                                     | ${true}  | ${true}   | ${false}
+  ${[invalidDate(), invalidDate()]}                      | ${true}  | ${true}   | ${false}
+  ${[invalidDate(), invalidDate(), invalidDate()]}       | ${false} | ${false}  | ${false}
+`('validates "$input" range', ({ input, range, rangeLike, validRange }) => {
+  expect(isDateRange(input)).toBe(range);
+  expect(isDateRangeLike(input)).toBe(rangeLike);
+  expect(isValidDateRange(input)).toBe(validRange);
+});
+
+test.each`
+  input              | result
+  ${null}            | ${invalidDate()}
+  ${undefined}       | ${invalidDate()}
+  ${'foo'}           | ${invalidDate()}
+  ${NaN}             | ${invalidDate()}
+  ${Infinity}        | ${invalidDate()}
+  ${stubDate()}      | ${stubDate()}
+  ${stubTimestamp()} | ${stubDate()}
+`('toDate($input) => $result', ({ input, result }) => {
+  expect(toDate(input)).toBeSameDate(result);
+});
+
+test.each([
+  [undefined, undefined, undefined, undefined],
+  [invalidDate(), undefined, invalidDate(), undefined],
+  [undefined, invalidDate(), invalidDate(), undefined],
+  [invalidDate(), invalidDate(), invalidDate(), invalidDate()],
+  [stubTimestamp(), invalidDate(), invalidDate(), stubDate()],
+  [invalidDate(), stubTimestamp(), invalidDate(), stubDate()],
+  [stubTimestamp(), undefined, stubDate(), undefined],
+  [undefined, stubTimestamp(), stubDate(), undefined],
+  [
+    stubTimestamp({ year: 2019 }),
+    stubTimestamp({ year: 2020 }),
+    stubDate({ year: 2019 }),
+    stubDate({ year: 2020 }),
+  ],
+])(
+  'toDateRange(%p, %p)',
+  (rawStart, rawFinish, expectedStart, expectedFinish) => {
+    const [start, finish] = toDateRange([rawStart, rawFinish]);
+
+    expect(start).toBeSameDate(expectedStart);
+    expect(finish).toBeSameDate(expectedFinish);
+  },
+);
+
+test.each`
+  tz      | date              | shortDate   | time         | dateTime
+  ${0}    | ${'May 24, 2019'} | ${'May 24'} | ${'1:02 AM'} | ${'May 24, 2019, 1:02 AM'}
+  ${+300} | ${'May 24, 2019'} | ${'May 24'} | ${'6:02 AM'} | ${'May 24, 2019, 6:02 AM'}
+  ${-300} | ${'May 23, 2019'} | ${'May 23'} | ${'8:02 PM'} | ${'May 23, 2019, 8:02 PM'}
+`(
+  'DateUtils({ zone: $tz })#format()',
+  ({ tz, date, shortDate, time, dateTime }) => {
+    const utils = new DateUtils();
+
+    setDefaultTimeZone(tz);
+
+    expect(utils.format(stubDate(), 'date')).toBe(date);
+    expect(utils.format(stubTimestamp(), 'date')).toBe(date);
+
+    expect(utils.format(stubDate(), 'shortDate')).toBe(shortDate);
+    expect(utils.format(stubTimestamp(), 'shortDate')).toBe(shortDate);
+
+    expect(utils.format(stubDate(), 'time')).toBe(time);
+    expect(utils.format(stubTimestamp(), 'time')).toBe(time);
+
+    expect(utils.format(stubDate(), 'dateTime')).toBe(dateTime);
+    expect(utils.format(stubTimestamp(), 'dateTime')).toBe(dateTime);
+  },
+);
+
+test.each<[NullableDateLike, NullableDateLike, string | undefined, string]>([
+  [undefined, undefined, undefined, ''],
+  [undefined, undefined, 'Empty Text', 'Empty Text'],
+  [invalidDate(), undefined, undefined, 'Invalid Date Range'],
+  [invalidDate(), invalidDate(), undefined, 'Invalid Date Range'],
+  [stubDate(), invalidDate(), undefined, 'Invalid Date Range'],
+  [stubDate(), undefined, undefined, 'May 24, 2019 - …'],
+  [
+    stubDate({ month: 5 }),
+    stubDate({ month: 6 }),
+    undefined,
+    'May 24 - Jun 24, 2019',
+  ],
+  [
+    stubDate({ year: 2020 }),
+    stubDate({ year: 2019 }),
+    undefined,
+    'May 24, 2019 - May 24, 2020',
+  ],
+])(
+  'DateUtils#formatDateRange([%p, %p]) -> %p',
+  (start, end, emptyText, result) => {
+    const utils = new DateUtils();
+
+    setDefaultTimeZone(0);
+
+    expect(utils.formatRange([start, end], emptyText)).toBe(result);
+    expect(utils.formatRange([end, start], emptyText)).toBe(result);
+  },
+);
+
+test.each([
+  [[NaN], 'in 0 sec.', 'in 0 sec.', 'in 0 seconds'],
+  [[-3], 'in 3 yr.', 'in 3 yr.', 'in 3 years'],
+  [[+3], '3 yr. ago', '3 yr. ago', '3 years ago'],
+  [[0, -3], 'in 3 mo.', 'in 3 mo.', 'in 3 months'],
+  [[0, +3], '3 mo. ago', '3 mo. ago', '3 months ago'],
+  [[0, 0, -3], 'in 3 days', 'in 3 days', 'in 3 days'],
+  [[0, 0, +3], '3 days ago', '3 days ago', '3 days ago'],
+  [[0, 0, 0, -3], 'in 3 hr.', 'in 3 hr.', 'in 3 hours'],
+  [[0, 0, 0, +3], '3 hr. ago', '3 hr. ago', '3 hours ago'],
+  [[0, 0, 0, 0, -3], 'in 3 min.', 'in 3 min.', 'in 3 minutes'],
+  [[0, 0, 0, 0, +3], '3 min. ago', '3 min. ago', '3 minutes ago'],
+  [[0, 0, 0, 0, 0, -3], 'in 3 sec.', 'in 3 sec.', 'in 3 seconds'],
+  [[0, 0, 0, 0, 0, +3], '3 sec. ago', '3 sec. ago', '3 seconds ago'],
+])(
+  'DateUtils#formatRelativeTime($offsets)',
+  (
+    [years = 0, months = 0, days = 0, hours = 0, minutes = 0, seconds = 0],
+    short,
+    narrow,
+    long,
+  ) => {
+    const utils = new DateUtils();
+    const input = new Date(Date.UTC(2019, 4, 24));
+    const base = new Date(
+      Date.UTC(years + 2019, months + 4, days + 24, hours, minutes, seconds),
+    );
+
+    expect(
+      utils.formatRelativeTime(input, { compare: base, style: 'narrow' }),
+    ).toBe(narrow);
+    expect(
+      utils.formatRelativeTime(input, { compare: base, style: 'short' }),
+    ).toBe(short);
+    expect(
+      utils.formatRelativeTime(input, { compare: base, style: 'long' }),
+    ).toBe(long);
+    expect(utils.formatRelativeTime(input, { compare: base })).toBe(long);
+
+    jest.spyOn(Date, 'now').mockImplementation(() => base.getTime());
+    expect(Date.now).toHaveBeenCalledTimes(0);
+    expect(utils.formatRelativeTime(input)).toBe(long);
+    expect(Date.now).toHaveBeenCalledTimes(1);
+  },
+);