@checkdigit/time 1.0.0 → 2.0.0-PR.14-c36c

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

@@ -0,0 +1,193 @@
+import compareAsc from '../compareAsc/index';
+import { millisecondsInMinute, minutesInDay, minutesInMonth, minutesInYear } from '../constants/index';
+import toDate from '../toDate/index';
+import type { LocaleOptions, FormatDistanceStrictUnit } from '../types';
+import assign from '../_lib/assign/index';
+import cloneObject from '../_lib/cloneObject/index';
+import defaultLocale from '../_lib/defaultLocale/index';
+import { getDefaultOptions } from '../_lib/defaultOptions/index';
+import getTimezoneOffsetInMilliseconds from '../_lib/getTimezoneOffsetInMilliseconds/index';
+import { getRoundingMethod } from '../_lib/roundingMethods/index';
+
+/**
+ * The {@link formatDistanceStrict} function options.
+ */
+export interface FormatDistanceStrictOptions extends LocaleOptions {
+  addSuffix?: boolean;
+  unit?: FormatDistanceStrictUnit;
+  roundingMethod?: 'floor' | 'ceil' | 'round';
+}
+
+/**
+ * @name formatDistanceStrict
+ * @category Common Helpers
+ * @summary Return the distance between the given dates in words.
+ *
+ * @description
+ * Return the distance between the given dates in words, using strict units.
+ * This is like `formatDistance`, but does not use helpers like 'almost', 'over',
+ * 'less than' and the like.
+ *
+ * | Distance between dates | Result              |
+ * |------------------------|---------------------|
+ * | 0 ... 59 secs          | [0..59] seconds     |
+ * | 1 ... 59 mins          | [1..59] minutes     |
+ * | 1 ... 23 hrs           | [1..23] hours       |
+ * | 1 ... 29 days          | [1..29] days        |
+ * | 1 ... 11 months        | [1..11] months      |
+ * | 1 ... N years          | [1..N]  years       |
+ *
+ * @param date - the date
+ * @param baseDate - the date to compare with
+ * @param options - an object with options.
+ * @returns the distance in words
+ * @throws {RangeError} `date` must not be Invalid Date
+ * @throws {RangeError} `baseDate` must not be Invalid Date
+ * @throws {RangeError} `options.unit` must be 'second', 'minute', 'hour', 'day', 'month' or 'year'
+ * @throws {RangeError} `options.locale` must contain `formatDistance` property
+ *
+ * @example
+ * // What is the distance between 2 July 2014 and 1 January 2015?
+ * const result = formatDistanceStrict(new Date(2014, 6, 2), new Date(2015, 0, 2))
+ * //=> '6 months'
+ *
+ * @example
+ * // What is the distance between 1 January 2015 00:00:15
+ * // and 1 January 2015 00:00:00?
+ * const result = formatDistanceStrict(
+ *   new Date(2015, 0, 1, 0, 0, 15),
+ *   new Date(2015, 0, 1, 0, 0, 0)
+ * )
+ * //=> '15 seconds'
+ *
+ * @example
+ * // What is the distance from 1 January 2016
+ * // to 1 January 2015, with a suffix?
+ * const result = formatDistanceStrict(new Date(2015, 0, 1), new Date(2016, 0, 1), {
+ *   addSuffix: true
+ * })
+ * //=> '1 year ago'
+ *
+ * @example
+ * // What is the distance from 1 January 2016
+ * // to 1 January 2015, in minutes?
+ * const result = formatDistanceStrict(new Date(2016, 0, 1), new Date(2015, 0, 1), {
+ *   unit: 'minute'
+ * })
+ * //=> '525600 minutes'
+ *
+ * @example
+ * // What is the distance from 1 January 2015
+ * // to 28 January 2015, in months, rounded up?
+ * const result = formatDistanceStrict(new Date(2015, 0, 28), new Date(2015, 0, 1), {
+ *   unit: 'month',
+ *   roundingMethod: 'ceil'
+ * })
+ * //=> '1 month'
+ *
+ * @example
+ * // What is the distance between 1 August 2016 and 1 January 2015 in Esperanto?
+ * import { eoLocale } from 'date-fns/locale/eo'
+ * const result = formatDistanceStrict(new Date(2016, 7, 1), new Date(2015, 0, 1), {
+ *   locale: eoLocale
+ * })
+ * //=> '1 jaro'
+ */
+
+export default function formatDistanceStrict<DateType extends Date>(
+  dirtyDate: DateType | number,
+  dirtyBaseDate: DateType | number,
+  options?: FormatDistanceStrictOptions,
+): string {
+  const defaultOptions = getDefaultOptions();
+  const locale = options?.locale ?? defaultOptions.locale ?? defaultLocale;
+
+  if (!locale.formatDistance) {
+    throw new RangeError('locale must contain localize.formatDistance property');
+  }
+
+  const comparison = compareAsc(dirtyDate, dirtyBaseDate);
+
+  if (isNaN(comparison)) {
+    throw new RangeError('Invalid time value');
+  }
+
+  const localizeOptions = assign(cloneObject(options), {
+    addSuffix: options?.addSuffix,
+    comparison: comparison as -1 | 0 | 1,
+  });
+
+  let dateLeft;
+  let dateRight;
+  if (comparison > 0) {
+    dateLeft = toDate(dirtyBaseDate);
+    dateRight = toDate(dirtyDate);
+  } else {
+    dateLeft = toDate(dirtyDate);
+    dateRight = toDate(dirtyBaseDate);
+  }
+
+  const roundingMethod = getRoundingMethod(options?.roundingMethod ?? 'round');
+
+  const milliseconds = dateRight.getTime() - dateLeft.getTime();
+  const minutes = milliseconds / millisecondsInMinute;
+
+  const timezoneOffset = getTimezoneOffsetInMilliseconds(dateRight) - getTimezoneOffsetInMilliseconds(dateLeft);
+
+  // Use DST-normalized difference in minutes for years, months and days;
+  // use regular difference in minutes for hours, minutes and seconds.
+  const dstNormalizedMinutes = (milliseconds - timezoneOffset) / millisecondsInMinute;
+
+  const defaultUnit = options?.unit;
+  let unit: FormatDistanceStrictUnit;
+  if (!defaultUnit) {
+    if (minutes < 1) {
+      unit = 'second';
+    } else if (minutes < 60) {
+      unit = 'minute';
+    } else if (minutes < minutesInDay) {
+      unit = 'hour';
+    } else if (dstNormalizedMinutes < minutesInMonth) {
+      unit = 'day';
+    } else if (dstNormalizedMinutes < minutesInYear) {
+      unit = 'month';
+    } else {
+      unit = 'year';
+    }
+  } else {
+    unit = defaultUnit;
+  }
+
+  // 0 up to 60 seconds
+  if (unit === 'second') {
+    const seconds = roundingMethod(milliseconds / 1000);
+    return locale.formatDistance('xSeconds', seconds, localizeOptions);
+
+    // 1 up to 60 mins
+  } else if (unit === 'minute') {
+    const roundedMinutes = roundingMethod(minutes);
+    return locale.formatDistance('xMinutes', roundedMinutes, localizeOptions);
+
+    // 1 up to 24 hours
+  } else if (unit === 'hour') {
+    const hours = roundingMethod(minutes / 60);
+    return locale.formatDistance('xHours', hours, localizeOptions);
+
+    // 1 up to 30 days
+  } else if (unit === 'day') {
+    const days = roundingMethod(dstNormalizedMinutes / minutesInDay);
+    return locale.formatDistance('xDays', days, localizeOptions);
+
+    // 1 up to 12 months
+  } else if (unit === 'month') {
+    const months = roundingMethod(dstNormalizedMinutes / minutesInMonth);
+    return months === 12 && defaultUnit !== 'month'
+      ? locale.formatDistance('xYears', 1, localizeOptions)
+      : locale.formatDistance('xMonths', months, localizeOptions);
+
+    // 1 year up to max Date
+  } else {
+    const years = roundingMethod(dstNormalizedMinutes / minutesInYear);
+    return locale.formatDistance('xYears', years, localizeOptions);
+  }
+}

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

@@ -0,0 +1,95 @@
+import distanceInWords, { FormatDistanceOptions } from '../formatDistance/index';
+
+/**
+ * The {@link formatDistanceToNow} function options.
+ */
+export interface FormatDistanceToNowOptions extends FormatDistanceOptions {}
+
+/**
+ * @name formatDistanceToNow
+ * @category Common Helpers
+ * @summary Return the distance between the given date and now in words.
+ * @pure false
+ *
+ * @description
+ * Return the distance between the given date and now in words.
+ *
+ * | Distance to now                                                   | Result              |
+ * |-------------------------------------------------------------------|---------------------|
+ * | 0 ... 30 secs                                                     | less than a minute  |
+ * | 30 secs ... 1 min 30 secs                                         | 1 minute            |
+ * | 1 min 30 secs ... 44 mins 30 secs                                 | [2..44] minutes     |
+ * | 44 mins ... 30 secs ... 89 mins 30 secs                           | about 1 hour        |
+ * | 89 mins 30 secs ... 23 hrs 59 mins 30 secs                        | about [2..24] hours |
+ * | 23 hrs 59 mins 30 secs ... 41 hrs 59 mins 30 secs                 | 1 day               |
+ * | 41 hrs 59 mins 30 secs ... 29 days 23 hrs 59 mins 30 secs         | [2..30] days        |
+ * | 29 days 23 hrs 59 mins 30 secs ... 44 days 23 hrs 59 mins 30 secs | about 1 month       |
+ * | 44 days 23 hrs 59 mins 30 secs ... 59 days 23 hrs 59 mins 30 secs | about 2 months      |
+ * | 59 days 23 hrs 59 mins 30 secs ... 1 yr                           | [2..12] months      |
+ * | 1 yr ... 1 yr 3 months                                            | about 1 year        |
+ * | 1 yr 3 months ... 1 yr 9 month s                                  | over 1 year         |
+ * | 1 yr 9 months ... 2 yrs                                           | almost 2 years      |
+ * | N yrs ... N yrs 3 months                                          | about N years       |
+ * | N yrs 3 months ... N yrs 9 months                                 | over N years        |
+ * | N yrs 9 months ... N+1 yrs                                        | almost N+1 years    |
+ *
+ * With `options.includeSeconds == true`:
+ * | Distance to now     | Result               |
+ * |---------------------|----------------------|
+ * | 0 secs ... 5 secs   | less than 5 seconds  |
+ * | 5 secs ... 10 secs  | less than 10 seconds |
+ * | 10 secs ... 20 secs | less than 20 seconds |
+ * | 20 secs ... 40 secs | half a minute        |
+ * | 40 secs ... 60 secs | less than a minute   |
+ * | 60 secs ... 90 secs | 1 minute             |
+ *
+ * > ⚠️ Please note that this function is not present in the FP submodule as
+ * > it uses `Date.now()` internally hence impure and can't be safely curried.
+ *
+ * @param date - the given date
+ * @param options - the object with options
+ * @returns the distance in words
+ * @throws {RangeError} `date` must not be Invalid Date
+ * @throws {RangeError} `options.locale` must contain `formatDistance` property
+ *
+ * @example
+ * // If today is 1 January 2015, what is the distance to 2 July 2014?
+ * const result = formatDistanceToNow(
+ *   new Date(2014, 6, 2)
+ * )
+ * //=> '6 months'
+ *
+ * @example
+ * // If now is 1 January 2015 00:00:00,
+ * // what is the distance to 1 January 2015 00:00:15, including seconds?
+ * const result = formatDistanceToNow(
+ *   new Date(2015, 0, 1, 0, 0, 15),
+ *   {includeSeconds: true}
+ * )
+ * //=> 'less than 20 seconds'
+ *
+ * @example
+ * // If today is 1 January 2015,
+ * // what is the distance to 1 January 2016, with a suffix?
+ * const result = formatDistanceToNow(
+ *   new Date(2016, 0, 1),
+ *   {addSuffix: true}
+ * )
+ * //=> 'in about 1 year'
+ *
+ * @example
+ * // If today is 1 January 2015,
+ * // what is the distance to 1 August 2016 in Esperanto?
+ * const eoLocale = require('date-fns/locale/eo')
+ * const result = formatDistanceToNow(
+ *   new Date(2016, 7, 1),
+ *   {locale: eoLocale}
+ * )
+ * //=> 'pli ol 1 jaro'
+ */
+export default function formatDistanceToNow<DateType extends Date>(
+  dirtyDate: DateType | number,
+  options?: FormatDistanceToNowOptions,
+): string {
+  return distanceInWords(dirtyDate, Date.now(), options);
+}

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

@@ -0,0 +1,82 @@
+import formatDistanceStrict, { FormatDistanceStrictOptions } from '../formatDistanceStrict/index';
+
+/**
+ * The {@link formatDistanceToNowStrict} function options.
+ */
+export interface FormatDistanceToNowStrictOptions extends FormatDistanceStrictOptions {}
+
+/**
+ * @name formatDistanceToNowStrict
+ * @category Common Helpers
+ * @summary Return the distance between the given date and now in words.
+ * @pure false
+ *
+ * @description
+ * Return the distance between the given dates in words, using strict units.
+ * This is like `formatDistance`, but does not use helpers like 'almost', 'over',
+ * 'less than' and the like.
+ *
+ * | Distance between dates | Result              |
+ * |------------------------|---------------------|
+ * | 0 ... 59 secs          | [0..59] seconds     |
+ * | 1 ... 59 mins          | [1..59] minutes     |
+ * | 1 ... 23 hrs           | [1..23] hours       |
+ * | 1 ... 29 days          | [1..29] days        |
+ * | 1 ... 11 months        | [1..11] months      |
+ * | 1 ... N years          | [1..N]  years       |
+ *
+ * @param date - the given date
+ * @param options - an object with options.
+ * @returns the distance in words
+ * @throws {RangeError} `date` must not be Invalid Date
+ * @throws {RangeError} `options.locale` must contain `formatDistance` property
+ *
+ * @example
+ * // If today is 1 January 2015, what is the distance to 2 July 2014?
+ * const result = formatDistanceToNowStrict(
+ *   new Date(2014, 6, 2)
+ * )
+ * //=> '6 months'
+ *
+ * @example
+ * // If now is 1 January 2015 00:00:00,
+ * // what is the distance to 1 January 2015 00:00:15, including seconds?
+ * const result = formatDistanceToNowStrict(
+ *   new Date(2015, 0, 1, 0, 0, 15)
+ * )
+ * //=> '15 seconds'
+ *
+ * @example
+ * // If today is 1 January 2015,
+ * // what is the distance to 1 January 2016, with a suffix?
+ * const result = formatDistanceToNowStrict(
+ *   new Date(2016, 0, 1),
+ *   {addSuffix: true}
+ * )
+ * //=> 'in 1 year'
+ *
+ * @example
+ * // If today is 28 January 2015,
+ * // what is the distance to 1 January 2015, in months, rounded up??
+ * const result = formatDistanceToNowStrict(new Date(2015, 0, 1), {
+ *   unit: 'month',
+ *   roundingMethod: 'ceil'
+ * })
+ * //=> '1 month'
+ *
+ * @example
+ * // If today is 1 January 2015,
+ * // what is the distance to 1 January 2016 in Esperanto?
+ * const eoLocale = require('date-fns/locale/eo')
+ * const result = formatDistanceToNowStrict(
+ *   new Date(2016, 0, 1),
+ *   {locale: eoLocale}
+ * )
+ * //=> '1 jaro'
+ */
+export default function formatDistanceToNowStrict<DateType extends Date>(
+  dirtyDate: DateType | number,
+  options?: FormatDistanceToNowStrictOptions,
+): string {
+  return formatDistanceStrict(dirtyDate, Date.now(), options);
+}

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

@@ -0,0 +1,97 @@
+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';
+
+/**
+ * The {@link formatDuration} function options.
+ */
+export interface FormatDurationOptions extends LocaleOptions {
+  format?: DurationUnit[];
+  zero?: boolean;
+  delimiter?: string;
+}
+
+const defaultFormat: DurationUnit[] = ['years', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds'];
+
+/**
+ * @name formatDuration
+ * @category Common Helpers
+ * @summary Formats a duration in human-readable format
+ *
+ * @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
+ *
+ * @example
+ * // Format full duration
+ * formatDuration({
+ *   years: 2,
+ *   months: 9,
+ *   weeks: 1,
+ *   days: 7,
+ *   hours: 5,
+ *   minutes: 9,
+ *   seconds: 30
+ * })
+ * //=> '2 years 9 months 1 week 7 days 5 hours 9 minutes 30 seconds'
+ *
+ * @example
+ * // Format partial duration
+ * formatDuration({ months: 9, days: 2 })
+ * //=> '9 months 2 days'
+ *
+ * @example
+ * // Customize the format
+ * formatDuration(
+ *   {
+ *     years: 2,
+ *     months: 9,
+ *     weeks: 1,
+ *     days: 7,
+ *     hours: 5,
+ *     minutes: 9,
+ *     seconds: 30
+ *   },
+ *   { format: ['months', 'weeks'] }
+ * ) === '9 months 1 week'
+ *
+ * @example
+ * // Customize the zeros presence
+ * formatDuration({ years: 0, months: 9 })
+ * //=> '9 months'
+ * formatDuration({ years: 0, months: 9 }, { zero: true })
+ * //=> '0 years 9 months'
+ *
+ * @example
+ * // Customize the delimiter
+ * formatDuration({ years: 2, months: 9, weeks: 3 }, { delimiter: ', ' })
+ * //=> '2 years, 9 months, 3 weeks'
+ */
+export default 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 ?? ' ';
+
+  if (!locale.formatDistance) {
+    return '';
+  }
+
+  const result = format
+    .reduce((acc, unit) => {
+      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));
+      }
+      return acc;
+    }, [] as string[])
+    .join(delimiter);
+
+  return result;
+}

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

@@ -0,0 +1,101 @@
+import toDate from '../toDate/index';
+import type { FormatOptions, RepresentationOptions } from '../types';
+import addLeadingZeros from '../_lib/addLeadingZeros/index';
+
+/**
+ * The {@link formatISO} function options.
+ */
+export interface FormatISOOptions extends FormatOptions, RepresentationOptions {}
+
+/**
+ * @name formatISO
+ * @category Common Helpers
+ * @summary Format the date according to the ISO 8601 standard (https://support.sas.com/documentation/cdl/en/lrdict/64316/HTML/default/viewer.htm#a003169814.htm).
+ *
+ * @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
+ *
+ * @example
+ * // Represent 18 September 2019 in ISO 8601 format (local time zone is UTC):
+ * const result = formatISO(new Date(2019, 8, 18, 19, 0, 52))
+ * //=> '2019-09-18T19:00:52Z'
+ *
+ * @example
+ * // Represent 18 September 2019 in ISO 8601, short format (local time zone is UTC):
+ * const result = formatISO(new Date(2019, 8, 18, 19, 0, 52), { format: 'basic' })
+ * //=> '20190918T190052'
+ *
+ * @example
+ * // Represent 18 September 2019 in ISO 8601 format, date only:
+ * const result = formatISO(new Date(2019, 8, 18, 19, 0, 52), { representation: 'date' })
+ * //=> '2019-09-18'
+ *
+ * @example
+ * // Represent 18 September 2019 in ISO 8601 format, time only (local time zone is UTC):
+ * 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');
+  }
+
+  const format = options?.format ?? 'extended';
+  const representation = options?.representation ?? 'complete';
+
+  let result = '';
+  let tzOffset = '';
+
+  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);
+
+    // yyyyMMdd or yyyy-MM-dd.
+    result = `${year}${dateDelimiter}${month}${dateDelimiter}${day}`;
+  }
+
+  // Representation is either 'time' or 'complete'
+  if (representation !== 'date') {
+    // Add the timezone.
+    const offset = originalDate.getTimezoneOffset();
+
+    if (offset !== 0) {
+      const absoluteOffset = Math.abs(offset);
+      const hourOffset = addLeadingZeros(Math.floor(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 ? '+' : '-';
+
+      tzOffset = `${sign}${hourOffset}:${minuteOffset}`;
+    } else {
+      tzOffset = 'Z';
+    }
+
+    const hour = addLeadingZeros(originalDate.getHours(), 2);
+    const minute = addLeadingZeros(originalDate.getMinutes(), 2);
+    const second = addLeadingZeros(originalDate.getSeconds(), 2);
+
+    // If there's also date, separate it with time with '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);
+
+    // HHmmss or HH:mm:ss.
+    result = `${result}${separator}${time}${tzOffset}`;
+  }
+
+  return result;
+}

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

@@ -0,0 +1,86 @@
+import isValid from '../isValid/index';
+import toDate from '../toDate/index';
+import type { FormatOptions, RepresentationOptions } from '../types';
+import addLeadingZeros from '../_lib/addLeadingZeros/index';
+
+/**
+ * The {@link formatISO9075} function options.
+ */
+export interface FormatISO9075Options extends FormatOptions, RepresentationOptions {}
+
+/**
+ * @name formatISO9075
+ * @category Common Helpers
+ * @summary Format the date according to the ISO 9075 standard (https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_get-format).
+ *
+ * @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
+ *
+ * @example
+ * // Represent 18 September 2019 in ISO 9075 format:
+ * const result = formatISO9075(new Date(2019, 8, 18, 19, 0, 52))
+ * //=> '2019-09-18 19:00:52'
+ *
+ * @example
+ * // Represent 18 September 2019 in ISO 9075, short format:
+ * const result = formatISO9075(new Date(2019, 8, 18, 19, 0, 52), { format: 'basic' })
+ * //=> '20190918 190052'
+ *
+ * @example
+ * // Represent 18 September 2019 in ISO 9075 format, date only:
+ * const result = formatISO9075(new Date(2019, 8, 18, 19, 0, 52), { representation: 'date' })
+ * //=> '2019-09-18'
+ *
+ * @example
+ * // Represent 18 September 2019 in ISO 9075 format, time only:
+ * 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,
+  options?: FormatISO9075Options,
+): string {
+  const originalDate = toDate(dirtyDate);
+
+  if (!isValid(originalDate)) {
+    throw new RangeError('Invalid time value');
+  }
+
+  const format = options?.format ?? 'extended';
+  const representation = options?.representation ?? 'complete';
+
+  let result = '';
+
+  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);
+
+    // 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 there's also date, separate it with time with a space
+    const separator = result === '' ? '' : ' ';
+
+    // HHmmss or HH:mm:ss.
+    result = `${result}${separator}${hour}${timeDelimiter}${minute}${timeDelimiter}${second}`;
+  }
+
+  return result;
+}

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

@@ -0,0 +1,31 @@
+import type { Duration } from '../types';
+
+/**
+ * @name formatISODuration
+ * @category Common Helpers
+ * @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)
+ *
+ * @param duration - the duration to format
+ *
+ * @returns The ISO 8601 duration string
+ *
+ * @example
+ * // Format the given duration as ISO 8601 string
+ * const result = formatISODuration({
+ *   years: 39,
+ *   months: 2,
+ *   days: 20,
+ *   hours: 7,
+ *   minutes: 5,
+ *   seconds: 0
+ * })
+ * //=> 'P39Y2M20DT0H0M0S'
+ */
+export default 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`;
+}