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

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

@@ -0,0 +1,49 @@
+import startOfWeek from '../startOfWeek/index';
+import type { LocaleOptions, WeekStartOptions } from '../types';
+
+/**
+ * The {@link isSameWeek} function options.
+ */
+export interface IsSameWeekOptions extends WeekStartOptions, LocaleOptions {}
+
+/**
+ * @name isSameWeek
+ * @category Week Helpers
+ * @summary Are the given dates in the same week (and month and year)?
+ *
+ * @description
+ * Are the given dates in the same week (and month and year)?
+ *
+ * @param dateLeft - the first date to check
+ * @param dateRight - the second date to check
+ * @param options - an object with options.
+ * @returns the dates are in the same week (and month and year)
+ *
+ * @example
+ * // Are 31 August 2014 and 4 September 2014 in the same week?
+ * const result = isSameWeek(new Date(2014, 7, 31), new Date(2014, 8, 4))
+ * //=> true
+ *
+ * @example
+ * // If week starts with Monday,
+ * // are 31 August 2014 and 4 September 2014 in the same week?
+ * const result = isSameWeek(new Date(2014, 7, 31), new Date(2014, 8, 4), {
+ *   weekStartsOn: 1
+ * })
+ * //=> false
+ *
+ * @example
+ * // Are 1 January 2014 and 1 January 2015 in the same week?
+ * const result = isSameWeek(new Date(2014, 0, 1), new Date(2015, 0, 1))
+ * //=> false
+ */
+export default function isSameWeek<DateType extends Date>(
+  dirtyDateLeft: DateType | number,
+  dirtyDateRight: DateType | number,
+  options?: IsSameWeekOptions,
+): boolean {
+  const dateLeftStartOfWeek = startOfWeek(dirtyDateLeft, options);
+  const dateRightStartOfWeek = startOfWeek(dirtyDateRight, options);
+
+  return dateLeftStartOfWeek.getTime() === dateRightStartOfWeek.getTime();
+}

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

@@ -0,0 +1,27 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name isSameYear
+ * @category Year Helpers
+ * @summary Are the given dates in the same year?
+ *
+ * @description
+ * Are the given dates in the same year?
+ *
+ * @param dateLeft - the first date to check
+ * @param dateRight - the second date to check
+ * @returns the dates are in the same year
+ *
+ * @example
+ * // Are 2 September 2014 and 25 September 2014 in the same year?
+ * const result = isSameYear(new Date(2014, 8, 2), new Date(2014, 8, 25))
+ * //=> true
+ */
+export default function isSameYear<DateType extends Date>(
+  dirtyDateLeft: DateType | number,
+  dirtyDateRight: DateType | number,
+): boolean {
+  const dateLeft = toDate(dirtyDateLeft);
+  const dateRight = toDate(dirtyDateRight);
+  return dateLeft.getFullYear() === dateRight.getFullYear();
+}

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

@@ -0,0 +1,21 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name isSaturday
+ * @category Weekday Helpers
+ * @summary Is the given date Saturday?
+ *
+ * @description
+ * Is the given date Saturday?
+ *
+ * @param date - the date to check
+ * @returns the date is Saturday
+ *
+ * @example
+ * // Is 27 September 2014 Saturday?
+ * const result = isSaturday(new Date(2014, 8, 27))
+ * //=> true
+ */
+export default function isSaturday<DateType extends Date>(dirtyDate: DateType | number): boolean {
+  return toDate(dirtyDate).getDay() === 6;
+}

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

@@ -0,0 +1,21 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name isSunday
+ * @category Weekday Helpers
+ * @summary Is the given date Sunday?
+ *
+ * @description
+ * Is the given date Sunday?
+ *
+ * @param date - the date to check
+ * @returns the date is Sunday
+ *
+ * @example
+ * // Is 21 September 2014 Sunday?
+ * const result = isSunday(new Date(2014, 8, 21))
+ * //=> true
+ */
+export default function isSunday<DateType extends Date>(dirtyDate: DateType | number): boolean {
+  return toDate(dirtyDate).getDay() === 0;
+}

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

@@ -0,0 +1,26 @@
+import isSameHour from '../isSameHour/index';
+
+/**
+ * @name isThisHour
+ * @category Hour Helpers
+ * @summary Is the given date in the same hour as the current date?
+ * @pure false
+ *
+ * @description
+ * Is the given date in the same hour as the current date?
+ *
+ * > ⚠️ 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 date to check
+ * @returns the date is in this hour
+ *
+ * @example
+ * // If now is 25 September 2014 18:30:15.500,
+ * // is 25 September 2014 18:00:00 in this hour?
+ * const result = isThisHour(new Date(2014, 8, 25, 18))
+ * //=> true
+ */
+export default function isThisHour<DateType extends Date>(dirtyDate: DateType | number): boolean {
+  return isSameHour(Date.now(), dirtyDate);
+}

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

@@ -0,0 +1,28 @@
+import isSameISOWeek from '../isSameISOWeek/index';
+
+/**
+ * @name isThisISOWeek
+ * @category ISO Week Helpers
+ * @summary Is the given date in the same ISO week as the current date?
+ * @pure false
+ *
+ * @description
+ * Is the given date in the same ISO week as the current date?
+ *
+ * ISO week-numbering year: http://en.wikipedia.org/wiki/ISO_week_date
+ *
+ * > ⚠️ 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 date to check
+ * @returns the date is in this ISO week
+ *
+ * @example
+ * // If today is 25 September 2014, is 22 September 2014 in this ISO week?
+ * const result = isThisISOWeek(new Date(2014, 8, 22))
+ * //=> true
+ */
+
+export default function isThisISOWeek<DateType extends Date>(dirtyDate: DateType | number): boolean {
+  return isSameISOWeek(dirtyDate, Date.now());
+}

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

@@ -0,0 +1,27 @@
+import isSameMinute from '../isSameMinute/index';
+
+/**
+ * @name isThisMinute
+ * @category Minute Helpers
+ * @summary Is the given date in the same minute as the current date?
+ * @pure false
+ *
+ * @description
+ * Is the given date in the same minute as the current date?
+ *
+ * > ⚠️ 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 date to check
+ * @returns the date is in this minute
+ *
+ * @example
+ * // If now is 25 September 2014 18:30:15.500,
+ * // is 25 September 2014 18:30:00 in this minute?
+ * const result = isThisMinute(new Date(2014, 8, 25, 18, 30))
+ * //=> true
+ */
+
+export default function isThisMinute<DateType extends Date>(dirtyDate: DateType | number): boolean {
+  return isSameMinute(Date.now(), dirtyDate);
+}

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

@@ -0,0 +1,26 @@
+import isSameMonth from '../isSameMonth/index';
+
+/**
+ * @name isThisMonth
+ * @category Month Helpers
+ * @summary Is the given date in the same month as the current date?
+ * @pure false
+ *
+ * @description
+ * Is the given date in the same month as the current date?
+ *
+ * > ⚠️ 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 date to check
+ * @returns the date is in this month
+ *
+ * @example
+ * // If today is 25 September 2014, is 15 September 2014 in this month?
+ * const result = isThisMonth(new Date(2014, 8, 15))
+ * //=> true
+ */
+
+export default function isThisMonth<DateType extends Date>(dirtyDate: DateType | number): boolean {
+  return isSameMonth(Date.now(), dirtyDate);
+}

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

@@ -0,0 +1,25 @@
+import isSameQuarter from '../isSameQuarter/index';
+
+/**
+ * @name isThisQuarter
+ * @category Quarter Helpers
+ * @summary Is the given date in the same quarter as the current date?
+ * @pure false
+ *
+ * @description
+ * Is the given date in the same quarter as the current date?
+ *
+ * > ⚠️ 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 date to check
+ * @returns the date is in this quarter
+ *
+ * @example
+ * // If today is 25 September 2014, is 2 July 2014 in this quarter?
+ * const result = isThisQuarter(new Date(2014, 6, 2))
+ * //=> true
+ */
+export default function isThisQuarter<DateType extends Date>(dirtyDate: DateType | number): boolean {
+  return isSameQuarter(Date.now(), dirtyDate);
+}

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

@@ -0,0 +1,26 @@
+import isSameSecond from '../isSameSecond/index';
+
+/**
+ * @name isThisSecond
+ * @category Second Helpers
+ * @summary Is the given date in the same second as the current date?
+ * @pure false
+ *
+ * @description
+ * Is the given date in the same second as the current date?
+ *
+ * > ⚠️ 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 date to check
+ * @returns the date is in this second
+ *
+ * @example
+ * // If now is 25 September 2014 18:30:15.500,
+ * // is 25 September 2014 18:30:15.000 in this second?
+ * const result = isThisSecond(new Date(2014, 8, 25, 18, 30, 15))
+ * //=> true
+ */
+export default function isThisSecond<DateType extends Date>(dirtyDate: DateType | number): boolean {
+  return isSameSecond(Date.now(), dirtyDate);
+}

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

@@ -0,0 +1,39 @@
+import isSameWeek from '../isSameWeek/index';
+import type { LocaleOptions, WeekStartOptions } from '../types';
+
+/**
+ * The {@link isThisWeek} function options.
+ */
+export interface IsThisWeekOptions extends WeekStartOptions, LocaleOptions {}
+
+/**
+ * @name isThisWeek
+ * @category Week Helpers
+ * @summary Is the given date in the same week as the current date?
+ * @pure false
+ *
+ * @description
+ * Is the given date in the same week as the current date?
+ *
+ * > ⚠️ 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 date to check
+ * @param options - the object with options
+ * @returns the date is in this week
+ *
+ * @example
+ * // If today is 25 September 2014, is 21 September 2014 in this week?
+ * const result = isThisWeek(new Date(2014, 8, 21))
+ * //=> true
+ *
+ * @example
+ * // If today is 25 September 2014 and week starts with Monday
+ * // is 21 September 2014 in this week?
+ * const result = isThisWeek(new Date(2014, 8, 21), { weekStartsOn: 1 })
+ * //=> false
+ */
+
+export default function is<DateType extends Date>(dirtyDate: DateType | number, options?: IsThisWeekOptions): boolean {
+  return isSameWeek(dirtyDate, Date.now(), options);
+}

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

@@ -0,0 +1,25 @@
+import isSameYear from '../isSameYear/index';
+
+/**
+ * @name isThisYear
+ * @category Year Helpers
+ * @summary Is the given date in the same year as the current date?
+ * @pure false
+ *
+ * @description
+ * Is the given date in the same year as the current date?
+ *
+ * > ⚠️ 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 date to check
+ * @returns the date is in this year
+ *
+ * @example
+ * // If today is 25 September 2014, is 2 July 2014 in this year?
+ * const result = isThisYear(new Date(2014, 6, 2))
+ * //=> true
+ */
+export default function isThisYear<DateType extends Date>(dirtyDate: DateType | number): boolean {
+  return isSameYear(dirtyDate, Date.now());
+}

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

@@ -0,0 +1,21 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name isThursday
+ * @category Weekday Helpers
+ * @summary Is the given date Thursday?
+ *
+ * @description
+ * Is the given date Thursday?
+ *
+ * @param date - the date to check
+ * @returns the date is Thursday
+ *
+ * @example
+ * // Is 25 September 2014 Thursday?
+ * const result = isThursday(new Date(2014, 8, 25))
+ * //=> true
+ */
+export default function isThursday<DateType extends Date>(dirtyDate: DateType | number): boolean {
+  return toDate(dirtyDate).getDay() === 4;
+}

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

@@ -0,0 +1,25 @@
+import isSameDay from '../isSameDay/index';
+
+/**
+ * @name isToday
+ * @category Day Helpers
+ * @summary Is the given date today?
+ * @pure false
+ *
+ * @description
+ * Is the given date today?
+ *
+ * > ⚠️ 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 date to check
+ * @returns the date is today
+ *
+ * @example
+ * // If today is 6 October 2014, is 6 October 14:00:00 today?
+ * const result = isToday(new Date(2014, 9, 6, 14, 0))
+ * //=> true
+ */
+export default function isToday<DateType extends Date>(dirtyDate: DateType | number): boolean {
+  return isSameDay(dirtyDate, Date.now());
+}

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

@@ -0,0 +1,26 @@
+import addDays from '../addDays/index';
+import isSameDay from '../isSameDay/index';
+
+/**
+ * @name isTomorrow
+ * @category Day Helpers
+ * @summary Is the given date tomorrow?
+ * @pure false
+ *
+ * @description
+ * Is the given date tomorrow?
+ *
+ * > ⚠️ 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 date to check
+ * @returns the date is tomorrow
+ *
+ * @example
+ * // If today is 6 October 2014, is 7 October 14:00:00 tomorrow?
+ * const result = isTomorrow(new Date(2014, 9, 7, 14, 0))
+ * //=> true
+ */
+export default function isTomorrow<DateType extends Date>(dirtyDate: DateType | number): boolean {
+  return isSameDay(dirtyDate, addDays(Date.now(), 1));
+}

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

@@ -0,0 +1,21 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name isTuesday
+ * @category Weekday Helpers
+ * @summary Is the given date Tuesday?
+ *
+ * @description
+ * Is the given date Tuesday?
+ *
+ * @param date - the date to check
+ * @returns the date is Tuesday
+ *
+ * @example
+ * // Is 23 September 2014 Tuesday?
+ * const result = isTuesday(new Date(2014, 8, 23))
+ * //=> true
+ */
+export default function isTuesday<DateType extends Date>(dirtyDate: DateType | number): boolean {
+  return toDate(dirtyDate).getDay() === 2;
+}

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

@@ -0,0 +1,40 @@
+import isDate from '../isDate/index';
+import toDate from '../toDate/index';
+
+/**
+ * @name isValid
+ * @category Common Helpers
+ * @summary Is the given date valid?
+ *
+ * @description
+ * Returns false if argument is Invalid Date and true otherwise.
+ * Argument is converted to Date using `toDate`. See [toDate]{@link https://date-fns.org/docs/toDate}
+ * Invalid Date is a Date, whose time value is NaN.
+ *
+ * Time value of Date: http://es5.github.io/#x15.9.1.1
+ *
+ * @param date - the date to check
+ * @returns the date is valid
+ *
+ * @example
+ * // For the valid date:
+ * const result = isValid(new Date(2014, 1, 31))
+ * //=> true
+ *
+ * @example
+ * // For the value, convertable into a date:
+ * const result = isValid(1393804800000)
+ * //=> true
+ *
+ * @example
+ * // For the invalid date:
+ * const result = isValid(new Date(''))
+ * //=> false
+ */
+export default function isValid(dirtyDate: unknown): boolean {
+  if (!isDate(dirtyDate) && typeof dirtyDate !== 'number') {
+    return false;
+  }
+  const date = toDate(dirtyDate);
+  return !isNaN(Number(date));
+}

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

@@ -0,0 +1,21 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name isWednesday
+ * @category Weekday Helpers
+ * @summary Is the given date Wednesday?
+ *
+ * @description
+ * Is the given date Wednesday?
+ *
+ * @param date - the date to check
+ * @returns the date is Wednesday
+ *
+ * @example
+ * // Is 24 September 2014 Wednesday?
+ * const result = isWednesday(new Date(2014, 8, 24))
+ * //=> true
+ */
+export default function isWednesday<DateType extends Date>(dirtyDate: DateType | number): boolean {
+  return toDate(dirtyDate).getDay() === 3;
+}

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

@@ -0,0 +1,23 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name isWeekend
+ * @category Weekday Helpers
+ * @summary Does the given date fall on a weekend?
+ *
+ * @description
+ * Does the given date fall on a weekend?
+ *
+ * @param date - the date to check
+ * @returns the date falls on a weekend
+ *
+ * @example
+ * // Does 5 October 2014 fall on a weekend?
+ * const result = isWeekend(new Date(2014, 9, 5))
+ * //=> true
+ */
+export default function isWeekend<DateType extends Date>(dirtyDate: DateType | number): boolean {
+  const date = toDate(dirtyDate);
+  const day = date.getDay();
+  return day === 0 || day === 6;
+}

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

@@ -0,0 +1,56 @@
+import toDate from '../toDate/index';
+import type { Interval } from '../types';
+
+/**
+ * @name isWithinInterval
+ * @category Interval Helpers
+ * @summary Is the given date within the interval?
+ *
+ * @description
+ * Is the given date within the interval? (Including start and end.)
+ *
+ * @param date - the date to check
+ * @param interval - the interval to check
+ * @returns the date is within the interval
+ * @throws {RangeError} The start of an interval cannot be after its end
+ * @throws {RangeError} Date in interval cannot be `Invalid Date`
+ *
+ * @example
+ * // For the date within the interval:
+ * isWithinInterval(new Date(2014, 0, 3), {
+ *   start: new Date(2014, 0, 1),
+ *   end: new Date(2014, 0, 7)
+ * })
+ * //=> true
+ *
+ * @example
+ * // For the date outside of the interval:
+ * isWithinInterval(new Date(2014, 0, 10), {
+ *   start: new Date(2014, 0, 1),
+ *   end: new Date(2014, 0, 7)
+ * })
+ * //=> false
+ *
+ * @example
+ * // For date equal to interval start:
+ * isWithinInterval(date, { start, end: date }) // => true
+ *
+ * @example
+ * // For date equal to interval end:
+ * isWithinInterval(date, { start: date, end }) // => true
+ */
+export default function isWithinInterval<DateType extends Date>(
+  dirtyDate: DateType | number,
+  interval: Interval<DateType>,
+): boolean {
+  const time = toDate(dirtyDate).getTime();
+  const startTime = toDate(interval.start).getTime();
+  const endTime = toDate(interval.end).getTime();
+
+  // Throw an exception if start date is after end date or if any date is `Invalid Date`
+  if (!(startTime <= endTime)) {
+    throw new RangeError('Invalid interval');
+  }
+
+  return time >= startTime && time <= endTime;
+}

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

@@ -0,0 +1,26 @@
+import isSameDay from '../isSameDay/index';
+import subDays from '../subDays/index';
+
+/**
+ * @name isYesterday
+ * @category Day Helpers
+ * @summary Is the given date yesterday?
+ * @pure false
+ *
+ * @description
+ * Is the given date yesterday?
+ *
+ * > ⚠️ 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 date to check
+ * @returns the date is yesterday
+ *
+ * @example
+ * // If today is 6 October 2014, is 5 October 14:00:00 yesterday?
+ * const result = isYesterday(new Date(2014, 9, 5, 14, 0))
+ * //=> true
+ */
+export default function isYesterday<DateType extends Date>(dirtyDate: DateType | number): boolean {
+  return isSameDay(dirtyDate, subDays(Date.now(), 1));
+}

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

@@ -0,0 +1,26 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name lastDayOfDecade
+ * @category Decade Helpers
+ * @summary Return the last day of a decade for the given date.
+ *
+ * @description
+ * Return the last day of a decade for the given date.
+ *
+ * @param date - the original date
+ * @returns the last day of a decade
+ *
+ * @example
+ * // The last day of a decade for 21 December 2012 21:12:00:
+ * const result = lastDayOfDecade(new Date(2012, 11, 21, 21, 12, 00))
+ * //=> Wed Dec 31 2019 00:00:00
+ */
+export default function lastDayOfDecade<DateType extends Date>(dirtyDate: DateType | number): DateType {
+  const date = toDate(dirtyDate);
+  const year = date.getFullYear();
+  const decade = 9 + Math.floor(year / 10) * 10;
+  date.setFullYear(decade + 1, 0, 0);
+  date.setHours(0, 0, 0, 0);
+  return date;
+}

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

@@ -0,0 +1,24 @@
+import lastDayOfWeek from '../lastDayOfWeek/index';
+
+/**
+ * @name lastDayOfISOWeek
+ * @category ISO Week Helpers
+ * @summary Return the last day of an ISO week for the given date.
+ *
+ * @description
+ * Return the last day of an ISO week for the given date.
+ * The result will be in the local timezone.
+ *
+ * ISO week-numbering year: http://en.wikipedia.org/wiki/ISO_week_date
+ *
+ * @param date - the original date
+ * @returns the last day of an ISO week
+ *
+ * @example
+ * // The last day of an ISO week for 2 September 2014 11:55:00:
+ * const result = lastDayOfISOWeek(new Date(2014, 8, 2, 11, 55, 0))
+ * //=> Sun Sep 07 2014 00:00:00
+ */
+export default function lastDayOfISOWeek<DateType extends Date>(dirtyDate: DateType | number): DateType {
+  return lastDayOfWeek(dirtyDate, { weekStartsOn: 1 });
+}