@checkdigit/time 3.0.0-PR.17-58cd → 4.0.0-PR.18-9134

package/src/date-fns/formatDuration/index.ts

@@ -1,18 +1,30 @@
-import type { FormatDistanceToken } from '../locale/types';
-import type { Duration, DurationUnit, LocaleOptions } from '../types';
-import defaultLocale from '../_lib/defaultLocale/index';
-import { getDefaultOptions } from '../_lib/defaultOptions/index';
+import type { FormatDistanceToken } from "../locale/types";
+import type { Duration, DurationUnit, LocalizedOptions } from "../types";
+import { defaultLocale } from "../_lib/defaultLocale/index";
+import { getDefaultOptions } from "../_lib/defaultOptions/index";
 
 /**
  * The {@link formatDuration} function options.
  */
-export interface FormatDurationOptions extends LocaleOptions {
+export interface FormatDurationOptions
+  extends LocalizedOptions<"formatDistance"> {
+  /** The array of units to format */
   format?: DurationUnit[];
+  /** Should be zeros be included in the output? */
   zero?: boolean;
+  /** The delimiter string to use */
   delimiter?: string;
 }
 
-const defaultFormat: DurationUnit[] = ['years', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds'];
+const defaultFormat: DurationUnit[] = [
+  "years",
+  "months",
+  "weeks",
+  "days",
+  "hours",
+  "minutes",
+  "seconds",
+];
 
 /**
  * @name formatDuration
@@ -22,9 +34,12 @@ const defaultFormat: DurationUnit[] = ['years', 'months', 'weeks', 'days', 'hour
  * @description
  * Return human-readable duration string i.e. "9 months 2 days"
  *
- * @param duration - the duration to format
- * @param options - an object with options.
- * @returns the formatted date string
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ *
+ * @param duration - The duration to format
+ * @param options - An object with options.
+ *
+ * @returns The formatted date string
  *
  * @example
  * // Format full duration
@@ -71,20 +86,25 @@ const defaultFormat: DurationUnit[] = ['years', 'months', 'weeks', 'days', 'hour
  * formatDuration({ years: 2, months: 9, weeks: 3 }, { delimiter: ', ' })
  * //=> '2 years, 9 months, 3 weeks'
  */
-export default function formatDuration(duration: Duration, options?: FormatDurationOptions): string {
+export function formatDuration(
+  duration: Duration,
+  options?: FormatDurationOptions,
+): string {
   const defaultOptions = getDefaultOptions();
   const locale = options?.locale ?? defaultOptions.locale ?? defaultLocale;
   const format = options?.format ?? defaultFormat;
   const zero = options?.zero ?? false;
-  const delimiter = options?.delimiter ?? ' ';
+  const delimiter = options?.delimiter ?? " ";
 
   if (!locale.formatDistance) {
-    return '';
+    return "";
   }
 
   const result = format
     .reduce((acc, unit) => {
-      const token = `x${unit.replace(/(^.)/, (m) => m.toUpperCase())}` as FormatDistanceToken;
+      const token = `x${unit.replace(/(^.)/, (m) =>
+        m.toUpperCase(),
+      )}` as FormatDistanceToken;
       const value = duration[unit];
       if (value !== undefined && (zero || duration[unit])) {
         return acc.concat(locale.formatDistance(token, value));

package/src/date-fns/formatDuration/test.mts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import { formatDuration } from "./index";
+
+describe("formatDuration", () => {
+  it("formats full duration", () => {
+    expect(formatDuration({
+      years: 2,
+      months: 9,
+      weeks: 1,
+      days: 7,
+      hours: 5,
+      minutes: 9,
+      seconds: 30,
+    })).toBe("2 years 9 months 1 week 7 days 5 hours 9 minutes 30 seconds");
+  });
+
+  it("formats partial duration", () => {
+    expect(formatDuration({ months: 9, days: 2 })).toBe("9 months 2 days");
+  });
+
+  it("allows to customize the format", () => {
+    expect(formatDuration(
+      {
+        years: 2,
+        months: 9,
+        weeks: 1,
+        days: 7,
+        hours: 5,
+        minutes: 9,
+        seconds: 30,
+      },
+      { format: ["months", "weeks"] },
+    )).toBe("9 months 1 week");
+  });
+
+  it("does not include zeros by default", () => {
+    expect(formatDuration({
+      years: 0,
+      months: 0,
+      weeks: 1,
+      days: 0,
+      hours: 0,
+      minutes: 0,
+      seconds: 0,
+    })).toBe("1 week");
+  });
+
+  it("allows to include zeros", () => {
+    expect(formatDuration(
+      {
+        years: 0,
+        months: 0,
+        weeks: 1,
+        days: 0,
+        hours: 0,
+        minutes: 0,
+        seconds: 0,
+      },
+      { zero: true },
+    )).toBe("0 years 0 months 1 week 0 days 0 hours 0 minutes 0 seconds");
+  });
+
+  it("allows to customize the delimiter", () => {
+    expect(formatDuration({ months: 9, days: 2 }, { delimiter: ", " })).toBe("9 months, 2 days");
+  });
+});

package/src/date-fns/formatISO/index.ts

@@ -1,11 +1,11 @@
-import toDate from '../toDate/index';
-import type { FormatOptions, RepresentationOptions } from '../types';
-import addLeadingZeros from '../_lib/addLeadingZeros/index';
+import { toDate } from "../toDate/index";
+import type { ISOFormatOptions } from "../types";
+import { addLeadingZeros } from "../_lib/addLeadingZeros/index";
 
 /**
  * The {@link formatISO} function options.
  */
-export interface FormatISOOptions extends FormatOptions, RepresentationOptions {}
+export interface FormatISOOptions extends ISOFormatOptions {}
 
 /**
  * @name formatISO
@@ -15,10 +15,14 @@ export interface FormatISOOptions extends FormatOptions, RepresentationOptions {
  * @description
  * Return the formatted date string in ISO 8601 format. Options may be passed to control the parts and notations of the date.
  *
- * @param date - the original date
- * @param options - an object with options.
- * @returns the formatted date string (in local time zone)
- * @throws {RangeError} `date` must not be Invalid Date
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ *
+ * @param date - The original date
+ * @param options - An object with options.
+ *
+ * @returns The formatted date string (in loca.l time zone)
+ *
+ * @throws `date` must not be Invalid Date
  *
  * @example
  * // Represent 18 September 2019 in ISO 8601 format (local time zone is UTC):
@@ -40,55 +44,58 @@ export interface FormatISOOptions extends FormatOptions, RepresentationOptions {
  * const result = formatISO(new Date(2019, 8, 18, 19, 0, 52), { representation: 'time' })
  * //=> '19:00:52Z'
  */
-export default function formatISO<DateType extends Date>(date: DateType | number, options?: FormatISOOptions): string {
-  const originalDate = toDate(date);
-
-  if (isNaN(originalDate.getTime())) {
-    throw new RangeError('Invalid time value');
+export function formatISO<DateType extends Date>(
+  date: DateType | number | string,
+  options?: FormatISOOptions,
+): string {
+  const _date = toDate(date);
+
+  if (isNaN(_date.getTime())) {
+    throw new RangeError("Invalid time value");
   }
 
-  const format = options?.format ?? 'extended';
-  const representation = options?.representation ?? 'complete';
+  const format = options?.format ?? "extended";
+  const representation = options?.representation ?? "complete";
 
-  let result = '';
-  let tzOffset = '';
+  let result = "";
+  let tzOffset = "";
 
-  const dateDelimiter = format === 'extended' ? '-' : '';
-  const timeDelimiter = format === 'extended' ? ':' : '';
+  const dateDelimiter = format === "extended" ? "-" : "";
+  const timeDelimiter = format === "extended" ? ":" : "";
 
   // Representation is either 'date' or 'complete'
-  if (representation !== 'time') {
-    const day = addLeadingZeros(originalDate.getDate(), 2);
-    const month = addLeadingZeros(originalDate.getMonth() + 1, 2);
-    const year = addLeadingZeros(originalDate.getFullYear(), 4);
+  if (representation !== "time") {
+    const day = addLeadingZeros(_date.getDate(), 2);
+    const month = addLeadingZeros(_date.getMonth() + 1, 2);
+    const year = addLeadingZeros(_date.getFullYear(), 4);
 
     // yyyyMMdd or yyyy-MM-dd.
     result = `${year}${dateDelimiter}${month}${dateDelimiter}${day}`;
   }
 
   // Representation is either 'time' or 'complete'
-  if (representation !== 'date') {
+  if (representation !== "date") {
     // Add the timezone.
-    const offset = originalDate.getTimezoneOffset();
+    const offset = _date.getTimezoneOffset();
 
     if (offset !== 0) {
       const absoluteOffset = Math.abs(offset);
-      const hourOffset = addLeadingZeros(Math.floor(absoluteOffset / 60), 2);
+      const hourOffset = addLeadingZeros(Math.trunc(absoluteOffset / 60), 2);
       const minuteOffset = addLeadingZeros(absoluteOffset % 60, 2);
       // If less than 0, the sign is +, because it is ahead of time.
-      const sign = offset < 0 ? '+' : '-';
+      const sign = offset < 0 ? "+" : "-";
 
       tzOffset = `${sign}${hourOffset}:${minuteOffset}`;
     } else {
-      tzOffset = 'Z';
+      tzOffset = "Z";
     }
 
-    const hour = addLeadingZeros(originalDate.getHours(), 2);
-    const minute = addLeadingZeros(originalDate.getMinutes(), 2);
-    const second = addLeadingZeros(originalDate.getSeconds(), 2);
+    const hour = addLeadingZeros(_date.getHours(), 2);
+    const minute = addLeadingZeros(_date.getMinutes(), 2);
+    const second = addLeadingZeros(_date.getSeconds(), 2);
 
     // If there's also date, separate it with time with 'T'
-    const separator = result === '' ? '' : 'T';
+    const separator = result === "" ? "" : "T";
 
     // Creates a time string consisting of hour, minute, and second, separated by delimiters, if defined.
     const time = [hour, minute, second].join(timeDelimiter);

package/src/date-fns/formatISO/test.mts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import sinon from "sinon";
+import { formatISO } from "./index";
+import { generateOffset } from "../_lib/test/index";
+
+describe("formatISO", () => {
+  it("formats ISO-8601 extended format", () => {
+    const date = new Date(2019, 2 /* Mar */, 3, 19, 0, 52, 123);
+    const tzOffsetExtended = generateOffset(date);
+    expect(formatISO(date)).toBe(`2019-03-03T19:00:52${tzOffsetExtended}`);
+
+    const getTimezoneOffsetStub = sinon.stub(
+      Date.prototype,
+      "getTimezoneOffset",
+    );
+
+    getTimezoneOffsetStub.returns(480);
+    const tzNegativeOffsetExtended = generateOffset(date);
+    expect(formatISO(date)).toBe(`2019-03-03T19:00:52${tzNegativeOffsetExtended}`);
+
+    getTimezoneOffsetStub.returns(0);
+    const tzZOffsetExtended = generateOffset(date);
+    expect(formatISO(date)).toBe(`2019-03-03T19:00:52${tzZOffsetExtended}`);
+
+    getTimezoneOffsetStub.restore();
+  });
+
+  it("accepts a timestamp", () => {
+    const date = new Date(2019, 2 /* Mar */, 3, 19, 0, 52, 123).getTime();
+    const tzOffsetExtended = generateOffset(new Date(date));
+    expect(formatISO(date)).toBe(`2019-03-03T19:00:52${tzOffsetExtended}`);
+  });
+
+  it("formats ISO-8601 basic format", () => {
+    const date = new Date(2019, 9 /* Oct */, 4, 12, 30, 13, 456);
+    const tzOffsetBasic = generateOffset(date);
+    expect(formatISO(date, { format: "basic" })).toBe(`20191004T123013${tzOffsetBasic}`);
+  });
+
+  it("formats only date", () => {
+    const date = new Date(2019, 11 /* Dec */, 11, 1, 0, 0, 789);
+
+    expect(formatISO(date, { representation: "date", format: "extended" })).toBe("2019-12-11");
+    expect(formatISO(date, { representation: "date", format: "basic" })).toBe("20191211");
+  });
+
+  it("formats only time", () => {
+    const date = new Date(2019, 2 /* Mar */, 3, 19, 0, 52, 123);
+    const tzOffset = generateOffset(date);
+
+    expect(formatISO(date, { representation: "time", format: "extended" })).toBe(`19:00:52${tzOffset}`);
+    expect(formatISO(date, { representation: "time", format: "basic" })).toBe(`190052${tzOffset}`);
+  });
+
+  it("throws RangeError if the time value is invalid", () => {
+    expect(formatISO.bind(null, new Date(NaN))).toThrow(RangeError);
+  });
+});

package/src/date-fns/formatISO9075/index.ts

@@ -1,12 +1,12 @@
-import isValid from '../isValid/index';
-import toDate from '../toDate/index';
-import type { FormatOptions, RepresentationOptions } from '../types';
-import addLeadingZeros from '../_lib/addLeadingZeros/index';
+import { isValid } from "../isValid/index";
+import { toDate } from "../toDate/index";
+import type { ISOFormatOptions } from "../types";
+import { addLeadingZeros } from "../_lib/addLeadingZeros/index";
 
 /**
  * The {@link formatISO9075} function options.
  */
-export interface FormatISO9075Options extends FormatOptions, RepresentationOptions {}
+export interface FormatISO9075Options extends ISOFormatOptions {}
 
 /**
  * @name formatISO9075
@@ -16,10 +16,14 @@ export interface FormatISO9075Options extends FormatOptions, RepresentationOptio
  * @description
  * Return the formatted date string in ISO 9075 format. Options may be passed to control the parts and notations of the date.
  *
- * @param date - the original date
- * @param options - an object with options.
- * @returns the formatted date string
- * @throws {RangeError} `date` must not be Invalid Date
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ *
+ * @param date - The original date
+ * @param options - An object with options.
+ *
+ * @returns The formatted date string
+ *
+ * @throws `date` must not be Invalid Date
  *
  * @example
  * // Represent 18 September 2019 in ISO 9075 format:
@@ -41,42 +45,42 @@ export interface FormatISO9075Options extends FormatOptions, RepresentationOptio
  * const result = formatISO9075(new Date(2019, 8, 18, 19, 0, 52), { representation: 'time' })
  * //=> '19:00:52'
  */
-export default function formatISO9075<DateType extends Date>(
-  dirtyDate: DateType | number,
+export function formatISO9075<DateType extends Date>(
+  date: DateType | number | string,
   options?: FormatISO9075Options,
 ): string {
-  const originalDate = toDate(dirtyDate);
+  const _date = toDate(date);
 
-  if (!isValid(originalDate)) {
-    throw new RangeError('Invalid time value');
+  if (!isValid(_date)) {
+    throw new RangeError("Invalid time value");
   }
 
-  const format = options?.format ?? 'extended';
-  const representation = options?.representation ?? 'complete';
+  const format = options?.format ?? "extended";
+  const representation = options?.representation ?? "complete";
 
-  let result = '';
+  let result = "";
 
-  const dateDelimiter = format === 'extended' ? '-' : '';
-  const timeDelimiter = format === 'extended' ? ':' : '';
+  const dateDelimiter = format === "extended" ? "-" : "";
+  const timeDelimiter = format === "extended" ? ":" : "";
 
   // Representation is either 'date' or 'complete'
-  if (representation !== 'time') {
-    const day = addLeadingZeros(originalDate.getDate(), 2);
-    const month = addLeadingZeros(originalDate.getMonth() + 1, 2);
-    const year = addLeadingZeros(originalDate.getFullYear(), 4);
+  if (representation !== "time") {
+    const day = addLeadingZeros(_date.getDate(), 2);
+    const month = addLeadingZeros(_date.getMonth() + 1, 2);
+    const year = addLeadingZeros(_date.getFullYear(), 4);
 
     // yyyyMMdd or yyyy-MM-dd.
     result = `${year}${dateDelimiter}${month}${dateDelimiter}${day}`;
   }
 
   // Representation is either 'time' or 'complete'
-  if (representation !== 'date') {
-    const hour = addLeadingZeros(originalDate.getHours(), 2);
-    const minute = addLeadingZeros(originalDate.getMinutes(), 2);
-    const second = addLeadingZeros(originalDate.getSeconds(), 2);
+  if (representation !== "date") {
+    const hour = addLeadingZeros(_date.getHours(), 2);
+    const minute = addLeadingZeros(_date.getMinutes(), 2);
+    const second = addLeadingZeros(_date.getSeconds(), 2);
 
     // If there's also date, separate it with time with a space
-    const separator = result === '' ? '' : ' ';
+    const separator = result === "" ? "" : " ";
 
     // HHmmss or HH:mm:ss.
     result = `${result}${separator}${hour}${timeDelimiter}${minute}${timeDelimiter}${second}`;

package/src/date-fns/formatISO9075/test.mts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { formatISO9075 } from "./index";
+
+describe("formatISO9075", () => {
+  it("formats ISO-9075 extended date format", () => {
+    const date = new Date(2019, 2 /* Mar */, 3, 19, 0, 52, 123);
+    expect(formatISO9075(date)).toBe("2019-03-03 19:00:52");
+  });
+
+  it("accepts a timestamp", () => {
+    const date = new Date(2019, 2 /* Mar */, 3, 19, 0, 52, 123).getTime();
+    expect(formatISO9075(date)).toBe("2019-03-03 19:00:52");
+  });
+
+  it("formats ISO-8601 basic date format", () => {
+    const date = new Date(2019, 9 /* Oct */, 4, 12, 30, 13, 456);
+    expect(formatISO9075(date, { format: "basic" })).toBe("20191004 123013");
+  });
+
+  it("formats only date", () => {
+    const date = new Date(2019, 11 /* Dec */, 11, 1, 0, 0, 789);
+    expect(formatISO9075(date, { representation: "date", format: "extended" })).toBe("2019-12-11");
+    expect(formatISO9075(date, { representation: "date", format: "basic" })).toBe("20191211");
+  });
+
+  it("formats only time", () => {
+    const date = new Date(2019, 2 /* Mar */, 3, 19, 0, 52, 123);
+    expect(formatISO9075(date, { representation: "time", format: "extended" })).toBe("19:00:52");
+    expect(formatISO9075(date, { representation: "time", format: "basic" })).toBe("190052");
+  });
+
+  it("throws RangeError if the time value is invalid", () => {
+    expect(formatISO9075.bind(null, new Date(NaN))).toThrow(RangeError);
+  });
+});

package/src/date-fns/formatISODuration/index.ts

@@ -1,4 +1,4 @@
-import type { Duration } from '../types';
+import type { Duration } from "../types";
 
 /**
  * @name formatISODuration
@@ -6,9 +6,9 @@ import type { Duration } from '../types';
  * @summary Format a duration object according as ISO 8601 duration string
  *
  * @description
- * Format a duration object according to the ISO 8601 duration standard (https://www.digi.com/resources/documentation/digidocs/90001437-13/reference/r_iso_8601_duration_format.htm)
+ * Format a duration object according to the ISO 8601 duration standard (https://www.digi.com/resources/documentation/digidocs//90001488-13/reference/r_iso_8601_duration_format.htm)
  *
- * @param duration - the duration to format
+ * @param duration - The duration to format
  *
  * @returns The ISO 8601 duration string
  *
@@ -24,8 +24,15 @@ import type { Duration } from '../types';
  * })
  * //=> 'P39Y2M20DT0H0M0S'
  */
-export default function formatISODuration(duration: Duration): string {
-  const { years = 0, months = 0, days = 0, hours = 0, minutes = 0, seconds = 0 } = duration;
+export function formatISODuration(duration: Duration): string {
+  const {
+    years = 0,
+    months = 0,
+    days = 0,
+    hours = 0,
+    minutes = 0,
+    seconds = 0,
+  } = duration;
 
   return `P${years}Y${months}M${days}DT${hours}H${minutes}M${seconds}S`;
 }

package/src/date-fns/formatISODuration/test.mts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import { formatISODuration } from "./index";
+import { intervalToDuration } from "../intervalToDuration/index";
+
+describe("formatISODuration", () => {
+  it("Everything returns correct duration for arbitrary dates", () => {
+    const start = new Date(1929, 0, 15, 12, 0, 0);
+    const end = new Date(1968, 3, 4, 19, 5, 0);
+    const result = formatISODuration(intervalToDuration({ start, end }));
+
+    expect(result).toBe("P39Y2M20DT7H5M0S");
+  });
+  it("Everything returns P1Y1M1DT1H1M1S (1 of everything)", () => {
+    const start = new Date(2020, 2, 1, 12, 0, 0);
+    const end = new Date(2021, 3, 2, 13, 1, 1);
+    const result = formatISODuration(intervalToDuration({ start, end }));
+
+    expect(result).toBe("P1Y1M1DT1H1M1S");
+  });
+  it("Returns P0Y0M0DT0H0M0S when the dates are the same", () => {
+    const start = new Date(2020, 2, 1, 12, 0, 0);
+    const end = new Date(2020, 2, 1, 12, 0, 0);
+    const result = formatISODuration(intervalToDuration({ start, end }));
+
+    expect(result).toBe("P0Y0M0DT0H0M0S");
+  });
+  it("Seconds returns P0Y0M0DT0H0M1S (1 second)", () => {
+    const start = new Date(2020, 2, 1, 12, 0, 0);
+    const end = new Date(2020, 2, 1, 12, 0, 1);
+    const result = formatISODuration(intervalToDuration({ start, end }));
+
+    expect(result).toBe("P0Y0M0DT0H0M1S");
+  });
+  it("Minutes returns P0Y0M0DT0H1M0S (1 minute)", () => {
+    const start = new Date(2020, 2, 1, 12, 0, 0);
+    const end = new Date(2020, 2, 1, 12, 1, 0);
+    const result = formatISODuration(intervalToDuration({ start, end }));
+
+    expect(result).toBe("P0Y0M0DT0H1M0S");
+  });
+  it("Hours returns P0Y0M0DT1H0M0S (1 hour)", () => {
+    const start = new Date(2020, 2, 1, 12, 0, 0);
+    const end = new Date(2020, 2, 1, 13, 0, 0);
+    const result = formatISODuration(intervalToDuration({ start, end }));
+
+    expect(result).toBe("P0Y0M0DT1H0M0S");
+  });
+  it("Days returns P0Y0M1DT0H0M0S (1 day)", () => {
+    const start = new Date(2020, 2, 1, 12, 0, 0);
+    const end = new Date(2020, 2, 2, 12, 0, 0);
+    const result = formatISODuration(intervalToDuration({ start, end }));
+
+    expect(result).toBe("P0Y0M1DT0H0M0S");
+  });
+  it("Months returns P0Y1M0DT0H0M0S (1 month)", () => {
+    const start = new Date(2020, 2, 1, 12, 0, 0);
+    const end = new Date(2020, 3, 1, 12, 0, 0);
+    const result = formatISODuration(intervalToDuration({ start, end }));
+
+    expect(result).toBe("P0Y1M0DT0H0M0S");
+  });
+  it("Years returns P1Y0M0DT0H0M1S (1 year)", () => {
+    const start = new Date(2020, 2, 1, 12, 0, 0);
+    const end = new Date(2021, 2, 1, 12, 0, 0);
+    const result = formatISODuration(intervalToDuration({ start, end }));
+
+    expect(result).toBe("P1Y0M0DT0H0M0S");
+  });
+
+  it("returns P0Y0M0DT0H0M0S when given an empty object", () => {
+    const result = formatISODuration({});
+
+    expect(result).toBe("P0Y0M0DT0H0M0S");
+  });
+});