@checkdigit/time 3.0.0-PR.17-5aaf → 4.0.0-PR.18-81a3

package/src/date-fns/locale/types.ts

@@ -1,23 +1,89 @@
 /* eslint-disable no-unused-vars */
 
-import type { Day, Era, FirstWeekContainsDate, Month, Quarter, Unit } from '../types';
-import type { BuildLocalizeFnArgCallback, LocalizeUnitValues, LocalizeUnitValuesIndex } from './_lib/buildLocalizeFn';
+import type { Day, Era, FirstWeekContainsDateOptions, LocalizedOptions, Month, Quarter, WeekOptions } from '../types';
 
+/**
+ * The locale object with all functions and data needed to parse and format
+ * dates. This is what each locale implements and exports.
+ */
 export interface Locale {
+  /** The locale code (ISO 639-1 + optional country code) */
   code: string;
+  /** The function to format distance */
   formatDistance: FormatDistanceFn;
+  /** The function to relative time */
   formatRelative: FormatRelativeFn;
+  /** The object with functions used to localize various values */
   localize: Localize;
+  /** The object with functions that return localized formats */
   formatLong: FormatLong;
+  /** The object with functions used to match and parse various localized values */
   match: Match;
+  /** An object with locale options */
   options?: LocaleOptions;
 }
 
-export interface LocaleOptions {
-  weekStartsOn?: Day;
-  firstWeekContainsDate?: FirstWeekContainsDate;
+/**
+ * The locale options.
+ */
+export interface LocaleOptions extends WeekOptions, FirstWeekContainsDateOptions {}
+
+/// Format distance types
+
+/**
+ * The function that takes a token (i.e. halfAMinute) passed by `formatDistance`
+ * or `formatDistanceStrict` and payload, and returns localized distance.
+ *
+ * @param token - The token to localize
+ * @param count - The distance number
+ * @param options - The object with options
+ *
+ * @returns The localized distance in words
+ */
+export type FormatDistanceFn = (token: FormatDistanceToken, count: number, options?: FormatDistanceFnOptions) => string;
+
+/**
+ * The {@link FormatDistanceFn} function options.
+ */
+export interface FormatDistanceFnOptions {
+  /** Add "X ago"/"in X" in the locale language */
+  addSuffix?: boolean;
+  /** The distance vector. -1 represents past and 1 future. Tells which suffix
+   * to use. */
+  comparison?: -1 | 0 | 1;
 }
 
+/**
+ * The function used inside the {@link FormatDistanceFn} function, implementing
+ * formatting for a particular token.
+ */
+export type FormatDistanceTokenFn = (
+  /** The distance as number to format */
+  count: number,
+  /** The object with options */
+  options?: FormatDistanceFnOptions,
+) => string;
+
+/**
+ * The tokens map to string templates used in the format distance function.
+ * It looks like this:
+ *
+ *   const formatDistanceLocale: FormatDistanceLocale<FormatDistanceTokenValue> = {
+ *     lessThanXSeconds: 'តិចជាង {{count}} វិនាទី',
+ *     xSeconds: '{{count}} វិនាទី',
+ *     // ...
+ *   }
+ *
+ * @typeParam Template - The property value type.
+ */
+export type FormatDistanceLocale<Template> = {
+  [Token in FormatDistanceToken]: Template;
+};
+
+/**
+ * The token used in the format distance function. Represents the distance unit
+ * with prespecified precision.
+ */
 export type FormatDistanceToken =
   | 'lessThanXSeconds'
   | 'xSeconds'
@@ -36,37 +102,20 @@ export type FormatDistanceToken =
   | 'overXYears'
   | 'almostXYears';
 
-export type FormatDistanceLocale<Value> = {
-  [token in FormatDistanceToken]: Value;
-};
-
-export interface FormatDistanceFnOptions {
-  addSuffix?: boolean;
-  comparison?: -1 | 0 | 1;
-}
-
-export type FormatDistanceTokenFn = (count: number, options?: FormatDistanceFnOptions) => string;
-
-export interface FormatDistanceFnOptions {
-  addSuffix?: boolean;
-  comparison?: -1 | 0 | 1;
-}
-
-export type FormatDistanceFn = (token: FormatDistanceToken, count: number, options?: FormatDistanceFnOptions) => string;
-
-export type FormatRelativeTokenFn = <DateType extends Date>(
-  date: DateType | number,
-  baseDate: DateType | number,
-  options?: { weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 },
-) => string;
-
-export type FormatRelativeToken = 'lastWeek' | 'yesterday' | 'today' | 'tomorrow' | 'nextWeek' | 'other';
-
-export interface FormatRelativeFnOptions {
-  weekStartsOn?: Day;
-  locale?: Locale;
-}
-
+/// Format relative types
+
+/**
+ * The locale function that does the work for the `formatRelative` function.
+ *
+ * @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 token - The token to localize
+ * @param date - The date to format
+ * @param baseDate - The date to compare with
+ * @param options - The object with options
+ *
+ * @returns The localized relative date format
+ */
 export type FormatRelativeFn = <DateType extends Date>(
   token: FormatRelativeToken,
   date: DateType,
@@ -74,146 +123,247 @@ export type FormatRelativeFn = <DateType extends Date>(
   options?: FormatRelativeFnOptions,
 ) => string;
 
-// TODO: You're real champion if you're actually get back to it. Proud of you!
-// Try to get rid of this and (especially) ArgCallback types because the only
-// case when it's helpful is when using quarter. Maybe.
-export type LocalizeUnitIndex<Unit extends LocaleUnit | number> = Unit extends LocaleUnit
-  ? LocalizeUnitValuesIndex<LocalizeUnitValues<Unit>>
-  : number;
-
-export type LocalizeFn<
-  Result extends LocaleUnit | number,
-  ArgCallback extends BuildLocalizeFnArgCallback<Result> | undefined = undefined,
-> = (
-  value: ArgCallback extends undefined ? Result : Result extends Quarter ? Quarter : LocalizeUnitIndex<Result>,
-  options?: {
-    width?: LocalePatternWidth;
-    context?: 'formatting' | 'standalone';
-    unit?: Unit;
-  },
+/**
+ * The {@link FormatRelativeFn} function options.
+ */
+export interface FormatRelativeFnOptions extends WeekOptions, LocalizedOptions<'options' | 'formatRelative'> {}
+
+/**
+ * The locale function used inside the {@link FormatRelativeFn} function
+ * implementing formatting for a particular token.
+ *
+ * @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 date to format
+ * @param baseDate - The date to compare with
+ * @param options - The object with options
+ */
+export type FormatRelativeTokenFn = <DateType extends Date>(
+  date: DateType | number | string,
+  baseDate: DateType | number | string,
+  options?: FormatRelativeTokenFnOptions,
 ) => string;
 
-export interface Localize {
-  ordinalNumber: LocalizeFn<number, BuildLocalizeFnArgCallback<number> | undefined>;
-  era: LocalizeFn<Era, undefined>;
-  quarter: LocalizeFn<Quarter, BuildLocalizeFnArgCallback<Quarter>>;
-  month: LocalizeFn<Month, undefined>;
-  day: LocalizeFn<Day, undefined>;
-  dayPeriod: LocalizeFn<LocaleDayPeriod, undefined>;
-}
+/**
+ * The {@link FormatRelativeTokenFn} function options.
+ */
+export interface FormatRelativeTokenFnOptions extends WeekOptions {}
+
+/**
+ * The token used in format relative function. Represents the time unit.
+ */
+export type FormatRelativeToken = 'lastWeek' | 'yesterday' | 'today' | 'tomorrow' | 'nextWeek' | 'other';
 
-export interface BuildMatchFnArgs<
-  Result extends LocaleUnit,
-  DefaultMatchWidth extends LocalePatternWidth,
-  DefaultParseWidth extends LocalePatternWidth,
-> {
-  matchPatterns: MatchPatterns<DefaultMatchWidth>;
-  defaultMatchWidth: DefaultMatchWidth;
-  parsePatterns: ParsePatterns<Result, DefaultParseWidth>;
-  defaultParseWidth: DefaultParseWidth;
-  valueCallback?: MatchValueCallback<Result extends LocaleDayPeriod ? string : number, Result>;
+/**
+ * A format part that represents a token or string literal, used by format parser/tokenizer
+ */
+export interface FormatPart {
+  /** If the part is a format token. */
+  isToken: boolean;
+  /** The format part value (i.e. `"do"`). */
+  value: string;
 }
 
-export type MatchPatterns<DefaultWidth extends LocalePatternWidth> = {
-  [pattern in LocalePatternWidth]?: RegExp;
-} & { [key in DefaultWidth]: RegExp };
-
-export type ParsePatterns<Result extends LocaleUnit, DefaultWidth extends LocalePatternWidth> = {
-  [pattern in LocalePatternWidth]?: ParsePattern<Result>;
-} & { [key in DefaultWidth]: ParsePattern<Result> };
-
-export type ParsePattern<Result extends LocaleUnit> = Result extends LocaleDayPeriod
-  ? Record<LocaleDayPeriod, RegExp>
-  : Result extends Quarter
-    ? readonly [RegExp, RegExp, RegExp, RegExp]
-    : Result extends Era
-      ? readonly [RegExp, RegExp]
-      : Result extends Day
-        ? readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp]
-        : Result extends Month
-          ? readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp]
-          : never;
-
-export type BuildMatchFn<
-  Result extends LocaleUnit,
-  DefaultMatchWidth extends LocalePatternWidth,
-  DefaultParseWidth extends LocalePatternWidth,
-> = (args: BuildMatchFnArgs<Result, DefaultMatchWidth, DefaultParseWidth>) => MatchFn<Result>;
+/// Localize types
 
-export type MatchFn<Result, ExtraOptions = Record<string, unknown>> = (
-  str: string,
-  options?: {
-    width?: LocalePatternWidth;
-    /**
-     * @deprecated Map the value manually instead.
-     * @example
-     * const matchResult = locale.match.ordinalNumber('1st')
-     * if (matchResult) {
-     *   matchResult.value = valueCallback(matchResult.value)
-     * }
-     */
-    valueCallback?: MatchValueCallback<string, Result>;
-  } & ExtraOptions,
-) => { value: Result; rest: string } | null;
+/**
+ * The object with functions used to localize various values. Part of the public
+ * locale API.
+ */
+export interface Localize {
+  /** The function that localizes an ordinal number */
+  ordinalNumber: LocalizeFn<number>;
+  /** The function that localized the era */
+  era: LocalizeFn<Era>;
+  /** The function that localizes the quarter */
+  quarter: LocalizeFn<Quarter>;
+  /** The function that localizes the month */
+  month: LocalizeFn<Month>;
+  /** The function that localizes the day of the week */
+  day: LocalizeFn<Day>;
+  /** The function that localizes the day period */
+  dayPeriod: LocalizeFn<LocaleDayPeriod>;
+
+  /** The function that can preprocess parts/tokens **/
+  preprocessor?: <DateType extends Date>(date: DateType, parts: FormatPart[]) => FormatPart[];
+}
 
-export type MatchValueCallback<Arg, Result> = (value: Arg) => Result;
+/**
+ * Individual localize function. Part of {@link Localize}.
+ *
+ * @typeParam Value - The value type to localize.
+ *
+ * @param value - The value to localize
+ * @param options - The object with options
+ *
+ * @returns The localized string
+ */
+export type LocalizeFn<Value extends LocaleUnitValue | number> = (value: Value, options?: LocalizeFnOptions) => string;
+
+/**
+ * The {@link LocalizeFn} function options.
+ */
+export interface LocalizeFnOptions {
+  /** The width to use formatting the value, defines how short or long
+   * the formatted string might be. */
+  width?: LocaleWidth;
+  /** The context where the formatted value is used - standalone: the result
+   * should make grammatical sense as is and formatting: the result is a part
+   * of the formatted string. See: https://date-fns.org/docs/I18n-Contribution-Guide */
+  context?: 'formatting' | 'standalone';
+  /** The unit to format */
+  unit?: LocaleUnit;
+}
 
+/// Match types
+
+/**
+ * The object with functions used to match and parse various localized values.
+ */
 export interface Match {
-  ordinalNumber: MatchFn<
-    number,
-    {
-      unit: LocaleOrdinalUnit;
-    }
-  >;
+  /** The function that parses a localized ordinal number. */
+  ordinalNumber: MatchFn<number, { unit: LocaleUnit }>;
+  /** The function that parses a localized era. */
   era: MatchFn<Era>;
+  /** The function that parses a localized quarter. */
   quarter: MatchFn<Quarter>;
+  /** The function that parses a localized month. */
   month: MatchFn<Month>;
+  /** The function that parses a localized day of the week. */
   day: MatchFn<Day>;
+  /** The function that parses a localized time of the day. */
   dayPeriod: MatchFn<LocaleDayPeriod>;
 }
 
-export type LocaleOrdinalUnit =
-  | 'second'
-  | 'minute'
-  | 'hour'
-  | 'day'
-  | 'week'
-  | 'month'
-  | 'quarter'
-  | 'year'
-  | 'date'
-  | 'dayOfYear';
-
-export type LocalePatternWidth = 'narrow' | 'short' | 'abbreviated' | 'wide' | 'any';
-
-export type LocaleDayPeriod = 'am' | 'pm' | 'midnight' | 'noon' | 'morning' | 'afternoon' | 'evening' | 'night';
-
-export type LocaleOptionUnit =
-  | 'year'
-  | 'quarter'
-  | 'month'
-  | 'week'
-  | 'date'
-  | 'dayOfYear'
-  | 'day'
-  | 'hour'
-  | 'minute'
-  | 'second';
+/**
+ * The match function. Part of {@link Match}. Implements matcher for particular
+ * unit type.
+ *
+ * @typeParam Result - The matched value type.
+ * @typeParam ExtraOptions - The the extra options type.
+ *
+ * @param str - The string to match
+ * @param options - The object with options
+ *
+ * @returns The match result or null if match failed
+ */
+export type MatchFn<Result, ExtraOptions = Record<string, unknown>> = (
+  str: string,
+  options?: MatchFnOptions<Result> & ExtraOptions,
+) => MatchFnResult<Result> | null;
+
+/**
+ * The {@link MatchFn} function options.
+ *
+ * @typeParam Result - The matched value type.
+ */
+export interface MatchFnOptions<Result> {
+  /** The width to use matching the value, defines how short or long
+   * the matched string might be. */
+  width?: LocaleWidth;
+  /**
+   * @deprecated Map the value manually instead.
+   * @example
+   * const matchResult = locale.match.ordinalNumber('1st')
+   * if (matchResult) {
+   *   matchResult.value = valueCallback(matchResult.value)
+   * }
+   */
+  valueCallback?: MatchValueCallback<string, Result>;
+}
 
-export type FormatLongWidth = 'full' | 'long' | 'medium' | 'short' | 'any';
+/**
+ * The function that allows to map the matched value to the actual type.
+ *
+ * @typeParam Arg - The argument type.
+ * @typeParam Result - The matched value type.
+ *
+ * @param arg - The value to match
+ *
+ * @returns The matched value
+ */
+export type MatchValueCallback<Arg, Result> = (value: Arg) => Result;
 
-export type DateTimeFormat = { [format in FormatLongWidth]: string };
+/**
+ * The {@link MatchFn} function result.
+ *
+ * @typeParam Result - The matched value type.
+ */
+export interface MatchFnResult<Result> {
+  /** The matched value parsed as the corresponding unit type */
+  value: Result;
+  /** The remaining string after parsing */
+  rest: string;
+}
 
-export type LocaleUnit = Era | Quarter | Month | Day | LocaleDayPeriod;
+/// Format long types
 
+/**
+ * The object with functions that return localized formats. Long stands for
+ * sequence of tokens (i.e. PPpp) that allows to define how format both date
+ * and time at once. Part of the public locale API.
+ */
 export interface FormatLong {
+  /** The function that returns a localized long date format */
   date: FormatLongFn;
+  /** The function that returns a localized long time format */
   time: FormatLongFn;
+  /** The function that returns a localized format of date and time combined */
   dateTime: FormatLongFn;
 }
 
+/**
+ * The format long function. Formats date, time or both.
+ *
+ * @param options - The object with options
+ *
+ * @returns The localized string
+ */
+export type FormatLongFn = (options: FormatLongFnOptions) => string;
+
+/**
+ * The {@link FormatLongFn} function options.
+ */
 export interface FormatLongFnOptions {
+  /** Format width to set */
   width?: FormatLongWidth;
 }
 
-export type FormatLongFn = (options: FormatLongFnOptions) => string;
+/**
+ * The format long width token, defines how short or long the formnatted value
+ * might be. The actual result length is defined by the locale.
+ */
+export type FormatLongWidth = 'full' | 'long' | 'medium' | 'short' | 'any';
+
+/// Common types
+
+/**
+ * The formatting unit value, represents the raw value that can be formatted.
+ */
+export type LocaleUnitValue = Era | Quarter | Month | Day | LocaleDayPeriod;
+
+/**
+ * The format width. Defines how short or long the formatted string might be.
+ * The actaul result length depends on the locale.
+ */
+export type LocaleWidth = 'narrow' | 'short' | 'abbreviated' | 'wide' | 'any';
+
+/**
+ * Token representing particular period of the day.
+ */
+export type LocaleDayPeriod = 'am' | 'pm' | 'midnight' | 'noon' | 'morning' | 'afternoon' | 'evening' | 'night';
+
+/**
+ * The units commonly used in the date formatting or parsing.
+ */
+export type LocaleUnit =
+  | 'second'
+  | 'minute'
+  | 'hour'
+  | 'day'
+  | 'dayOfYear'
+  | 'date'
+  | 'week'
+  | 'month'
+  | 'quarter'
+  | 'year';

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

@@ -1,4 +1,4 @@
-import toDate from '../toDate/index';
+import { toDate } from '../toDate/index';
 
 /**
  * @name max
@@ -8,8 +8,11 @@ import toDate from '../toDate/index';
  * @description
  * Return the latest of the given dates.
  *
- * @param datesArray - the dates to compare
- * @returns the latest of the dates
+ * @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 dates - The dates to compare
+ *
+ * @returns The latest of the dates
  *
  * @example
  * // Which of these dates is the latest?
@@ -21,9 +24,9 @@ import toDate from '../toDate/index';
  * ])
  * //=> Sun Jul 02 1995 00:00:00
  */
-export default function max<DateType extends Date>(datesArray: Array<DateType | number>): DateType | Date {
+export function max<DateType extends Date>(dates: Array<DateType | number | string>): DateType | Date {
   let result: Date | undefined;
-  datesArray.forEach(function (dirtyDate) {
+  dates.forEach(function (dirtyDate) {
     const currentDate = toDate(dirtyDate);
 
     if (result === undefined || result < currentDate || isNaN(Number(currentDate))) {

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

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import { max } from './index';
+
+describe('max', () => {
+  it('returns the latest date', () => {
+    const result = max([new Date(1989, 6 /* Jul */, 10), new Date(1987, 1 /* Feb */, 11)]);
+    expect(result).toEqual(new Date(1989, 6 /* Jul */, 10));
+  });
+
+  it('accepts array with more than 2 entries', () => {
+    const result = max([
+      new Date(1987, 1 /* Feb */, 11),
+      new Date(1989, 6 /* Jul */, 10),
+      new Date(1995, 6 /* Jul */, 2),
+      new Date(1990, 0 /* Jan */, 1),
+    ]);
+    expect(result).toEqual(new Date(1995, 6 /* Jul */, 2));
+  });
+
+  it('accepts timestamps', () => {
+    const result = max([new Date(1989, 6 /* Jul */, 10).getTime(), new Date(1987, 1 /* Feb */, 11).getTime()]);
+    expect(result).toEqual(new Date(1989, 6 /* Jul */, 10));
+  });
+
+  it('returns `Invalid Date` if any given date is invalid', () => {
+    const result = max([new Date(1989, 6 /* Jul */, 10), new Date(NaN), new Date(1987, 1 /* Feb */, 11)]);
+    expect(isNaN(+result)).toBe(true);
+  });
+
+  it('returns `Invalid Date` for empty array', () => {
+    const result = max([]);
+    expect(isNaN(+result)).toBe(true);
+  });
+});

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

@@ -1,9 +1,6 @@
+import { daysInYear } from '../constants/index';
 import type { Duration } from '../types';
 
-// Leap year occures every 4 years, except for years that are divisable by 100 and not divisable by 400.
-// 1 mean year = (365+1/4-1/100+1/400) days = 365.2425 days
-const daysInYear = 365.2425;
-
 /**
  * @name milliseconds
  * @category Millisecond Helpers
@@ -20,8 +17,9 @@ const daysInYear = 365.2425;
  *
  * One month is a year divided by 12.
  *
- * @param duration - the object with years, months, weeks, days, hours, minutes and seconds to be added. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
- * @returns the milliseconds
+ * @param duration - The object with years, months, weeks, days, hours, minutes and seconds to be added.
+ *
+ * @returns The milliseconds
  *
  * @example
  * // 1 year in milliseconds
@@ -32,7 +30,7 @@ const daysInYear = 365.2425;
  * milliseconds({ months: 3 })
  * //=> 7889238000
  */
-export default function milliseconds({ years, months, weeks, days, hours, minutes, seconds }: Duration): number {
+export function milliseconds({ years, months, weeks, days, hours, minutes, seconds }: Duration): number {
   let totalDays = 0;
 
   if (years) totalDays += years * daysInYear;
@@ -46,5 +44,5 @@ export default function milliseconds({ years, months, weeks, days, hours, minute
   if (minutes) totalSeconds += minutes * 60;
   if (seconds) totalSeconds += seconds;
 
-  return Math.round(totalSeconds * 1000);
+  return Math.trunc(totalSeconds * 1000);
 }

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

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+import { milliseconds } from './index';
+
+describe('milliseconds', () => {
+  it('converts years to milliseconds', () => {
+    const result = milliseconds({ years: 2 });
+    expect(result).toBe(63113903999);
+  });
+
+  it('converts months to milliseconds', () => {
+    const result = milliseconds({ months: 3 });
+    expect(result).toBe(7889237999);
+  });
+
+  it('converts weeks to milliseconds', () => {
+    const result = milliseconds({ weeks: 2 });
+    expect(result).toBe(1209600000);
+  });
+
+  it('converts days to milliseconds', () => {
+    const result = milliseconds({ days: 5 });
+    expect(result).toBe(432000000);
+  });
+
+  it('converts hours to milliseconds', () => {
+    const result = milliseconds({ hours: 2 });
+    expect(result).toBe(7200000);
+  });
+
+  it('converts minutes to milliseconds', () => {
+    const result = milliseconds({ minutes: 5 });
+    expect(result).toBe(300000);
+  });
+
+  it('converts seconds to milliseconds', () => {
+    const result = milliseconds({ seconds: 10 });
+    expect(result).toBe(10000);
+  });
+
+  it('sums all the duration values', () => {
+    const result = milliseconds({
+      years: 2,
+      months: 3,
+      weeks: 2,
+      days: 5,
+      hours: 2,
+      minutes: 5,
+      seconds: 10,
+    });
+    expect(result).toBe(72652252000);
+  });
+
+  it('returns 0 for an empty duration', () => {
+    const result = milliseconds({});
+    expect(result).toBe(0);
+  });
+
+  it('properly works with negative numbers', () => {
+    expect(milliseconds({ seconds: 1.2345 })).toBe(1234);
+    expect(milliseconds({ seconds: -1.2345 })).toBe(-1234);
+  });
+});