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

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

@@ -0,0 +1,31 @@
+import constructFrom from '../constructFrom/index';
+import toDate from '../toDate/index';
+
+/**
+ * @name setYear
+ * @category Year Helpers
+ * @summary Set the year to the given date.
+ *
+ * @description
+ * Set the year to the given date.
+ *
+ * @param date - the date to be changed
+ * @param year - the year of the new date
+ * @returns the new date with the year set
+ *
+ * @example
+ * // Set year 2013 to 1 September 2014:
+ * const result = setYear(new Date(2014, 8, 1), 2013)
+ * //=> Sun Sep 01 2013 00:00:00
+ */
+export default function setYear<DateType extends Date>(dirtyDate: DateType | number, year: number): DateType {
+  const date = toDate(dirtyDate);
+
+  // Check if date is Invalid Date because Date.prototype.setFullYear ignores the value of Invalid Date
+  if (isNaN(date.getTime())) {
+    return constructFrom(dirtyDate, NaN);
+  }
+
+  date.setFullYear(year);
+  return date;
+}

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

@@ -0,0 +1,24 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name startOfDay
+ * @category Day Helpers
+ * @summary Return the start of a day for the given date.
+ *
+ * @description
+ * Return the start of a day for the given date.
+ * The result will be in the local timezone.
+ *
+ * @param date - the original date
+ * @returns the start of a day
+ *
+ * @example
+ * // The start of a day for 2 September 2014 11:55:00:
+ * const result = startOfDay(new Date(2014, 8, 2, 11, 55, 0))
+ * //=> Tue Sep 02 2014 00:00:00
+ */
+export default function startOfDay<DateType extends Date>(dirtyDate: DateType | number): DateType {
+  const date = toDate(dirtyDate);
+  date.setHours(0, 0, 0, 0);
+  return date;
+}

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

@@ -0,0 +1,26 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name startOfDecade
+ * @category Decade Helpers
+ * @summary Return the start of a decade for the given date.
+ *
+ * @description
+ * Return the start of a decade for the given date.
+ *
+ * @param date - the original date
+ * @returns the start of a decade
+ *
+ * @example
+ * // The start of a decade for 21 October 2015 00:00:00:
+ * const result = startOfDecade(new Date(2015, 9, 21, 00, 00, 00))
+ * //=> Jan 01 2010 00:00:00
+ */
+export default function startOfDecade<DateType extends Date>(dirtyDate: DateType | number): DateType {
+  const date = toDate(dirtyDate);
+  const year = date.getFullYear();
+  const decade = Math.floor(year / 10) * 10;
+  date.setFullYear(decade, 0, 1);
+  date.setHours(0, 0, 0, 0);
+  return date;
+}

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

@@ -0,0 +1,24 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name startOfHour
+ * @category Hour Helpers
+ * @summary Return the start of an hour for the given date.
+ *
+ * @description
+ * Return the start of an hour for the given date.
+ * The result will be in the local timezone.
+ *
+ * @param date - the original date
+ * @returns the start of an hour
+ *
+ * @example
+ * // The start of an hour for 2 September 2014 11:55:00:
+ * const result = startOfHour(new Date(2014, 8, 2, 11, 55))
+ * //=> Tue Sep 02 2014 11:00:00
+ */
+export default function startOfHour<DateType extends Date>(dirtyDate: DateType | number): DateType {
+  const date = toDate(dirtyDate);
+  date.setMinutes(0, 0, 0);
+  return date;
+}

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

@@ -0,0 +1,24 @@
+import startOfWeek from '../startOfWeek/index';
+
+/**
+ * @name startOfISOWeek
+ * @category ISO Week Helpers
+ * @summary Return the start of an ISO week for the given date.
+ *
+ * @description
+ * Return the start 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 start of an ISO week
+ *
+ * @example
+ * // The start of an ISO week for 2 September 2014 11:55:00:
+ * const result = startOfISOWeek(new Date(2014, 8, 2, 11, 55, 0))
+ * //=> Mon Sep 01 2014 00:00:00
+ */
+export default function startOfISOWeek<DateType extends Date>(dirtyDate: DateType | number): DateType {
+  return startOfWeek(dirtyDate, { weekStartsOn: 1 });
+}

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

@@ -0,0 +1,32 @@
+import getISOWeekYear from '../getISOWeekYear/index';
+import startOfISOWeek from '../startOfISOWeek/index';
+import constructFrom from '../constructFrom/index';
+
+/**
+ * @name startOfISOWeekYear
+ * @category ISO Week-Numbering Year Helpers
+ * @summary Return the start of an ISO week-numbering year for the given date.
+ *
+ * @description
+ * Return the start of an ISO week-numbering year,
+ * which always starts 3 days before the year's first Thursday.
+ * 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 start of an ISO week-numbering year
+ *
+ * @example
+ * // The start of an ISO week-numbering year for 2 July 2005:
+ * const result = startOfISOWeekYear(new Date(2005, 6, 2))
+ * //=> Mon Jan 03 2005 00:00:00
+ */
+export default function startOfISOWeekYear<DateType extends Date>(dirtyDate: DateType | number): DateType {
+  const year = getISOWeekYear(dirtyDate);
+  const fourthOfJanuary = constructFrom(dirtyDate, 0);
+  fourthOfJanuary.setFullYear(year, 0, 4);
+  fourthOfJanuary.setHours(0, 0, 0, 0);
+  const date = startOfISOWeek(fourthOfJanuary);
+  return date;
+}

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

@@ -0,0 +1,24 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name startOfMinute
+ * @category Minute Helpers
+ * @summary Return the start of a minute for the given date.
+ *
+ * @description
+ * Return the start of a minute for the given date.
+ * The result will be in the local timezone.
+ *
+ * @param date - the original date
+ * @returns the start of a minute
+ *
+ * @example
+ * // The start of a minute for 1 December 2014 22:15:45.400:
+ * const result = startOfMinute(new Date(2014, 11, 1, 22, 15, 45, 400))
+ * //=> Mon Dec 01 2014 22:15:00
+ */
+export default function startOfMinute<DateType extends Date>(dirtyDate: DateType | number): DateType {
+  const date = toDate(dirtyDate);
+  date.setSeconds(0, 0);
+  return date;
+}

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

@@ -0,0 +1,25 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name startOfMonth
+ * @category Month Helpers
+ * @summary Return the start of a month for the given date.
+ *
+ * @description
+ * Return the start of a month for the given date.
+ * The result will be in the local timezone.
+ *
+ * @param date - the original date
+ * @returns the start of a month
+ *
+ * @example
+ * // The start of a month for 2 September 2014 11:55:00:
+ * const result = startOfMonth(new Date(2014, 8, 2, 11, 55, 0))
+ * //=> Mon Sep 01 2014 00:00:00
+ */
+export default function startOfMonth<DateType extends Date>(dirtyDate: DateType | number): DateType {
+  const date = toDate(dirtyDate);
+  date.setDate(1);
+  date.setHours(0, 0, 0, 0);
+  return date;
+}

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

@@ -0,0 +1,27 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name startOfQuarter
+ * @category Quarter Helpers
+ * @summary Return the start of a year quarter for the given date.
+ *
+ * @description
+ * Return the start of a year quarter for the given date.
+ * The result will be in the local timezone.
+ *
+ * @param date - the original date
+ * @returns the start of a quarter
+ *
+ * @example
+ * // The start of a quarter for 2 September 2014 11:55:00:
+ * const result = startOfQuarter(new Date(2014, 8, 2, 11, 55, 0))
+ * //=> Tue Jul 01 2014 00:00:00
+ */
+export default function startOfQuarter<DateType extends Date>(dirtyDate: DateType | number): DateType {
+  const date = toDate(dirtyDate);
+  const currentMonth = date.getMonth();
+  const month = currentMonth - (currentMonth % 3);
+  date.setMonth(month, 1);
+  date.setHours(0, 0, 0, 0);
+  return date;
+}

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

@@ -0,0 +1,24 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name startOfSecond
+ * @category Second Helpers
+ * @summary Return the start of a second for the given date.
+ *
+ * @description
+ * Return the start of a second for the given date.
+ * The result will be in the local timezone.
+ *
+ * @param date - the original date
+ * @returns the start of a second
+ *
+ * @example
+ * // The start of a second for 1 December 2014 22:15:45.400:
+ * const result = startOfSecond(new Date(2014, 11, 1, 22, 15, 45, 400))
+ * //=> Mon Dec 01 2014 22:15:45.000
+ */
+export default function startOfSecond<DateType extends Date>(dirtyDate: DateType | number): DateType {
+  const date = toDate(dirtyDate);
+  date.setMilliseconds(0);
+  return date;
+}

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

@@ -0,0 +1,24 @@
+import startOfDay from '../startOfDay/index';
+
+/**
+ * @name startOfToday
+ * @category Day Helpers
+ * @summary Return the start of today.
+ * @pure false
+ *
+ * @description
+ * Return the start of 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.
+ *
+ * @returns the start of today
+ *
+ * @example
+ * // If today is 6 October 2014:
+ * const result = startOfToday()
+ * //=> Mon Oct 6 2014 00:00:00
+ */
+export default function startOfToday(): Date {
+  return startOfDay(Date.now());
+}

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

@@ -0,0 +1,30 @@
+/**
+ * @name startOfTomorrow
+ * @category Day Helpers
+ * @summary Return the start of tomorrow.
+ * @pure false
+ *
+ * @description
+ * Return the start of tomorrow.
+ *
+ * > ⚠️ Please note that this function is not present in the FP submodule as
+ * > it uses `new Date()` internally hence impure and can't be safely curried.
+ *
+ * @returns the start of tomorrow
+ *
+ * @example
+ * // If today is 6 October 2014:
+ * const result = startOfTomorrow()
+ * //=> Tue Oct 7 2014 00:00:00
+ */
+export default function startOfTomorrow(): Date {
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = now.getMonth();
+  const day = now.getDate();
+
+  const date = new Date(0);
+  date.setFullYear(year, month, day + 1);
+  date.setHours(0, 0, 0, 0);
+  return date;
+}

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

@@ -0,0 +1,52 @@
+import toDate from '../toDate/index';
+import type { LocaleOptions, WeekStartOptions } from '../types';
+import { getDefaultOptions } from '../_lib/defaultOptions/index';
+
+/**
+ * The {@link startOfWeek} function options.
+ */
+export interface StartOfWeekOptions extends LocaleOptions, WeekStartOptions {}
+
+/**
+ * @name startOfWeek
+ * @category Week Helpers
+ * @summary Return the start of a week for the given date.
+ *
+ * @description
+ * Return the start of a week for the given date.
+ * The result will be in the local timezone.
+ *
+ * @param date - the original date
+ * @param options - an object with options.
+ * @returns the start of a week
+ *
+ * @example
+ * // The start of a week for 2 September 2014 11:55:00:
+ * const result = startOfWeek(new Date(2014, 8, 2, 11, 55, 0))
+ * //=> Sun Aug 31 2014 00:00:00
+ *
+ * @example
+ * // If the week starts on Monday, the start of the week for 2 September 2014 11:55:00:
+ * const result = startOfWeek(new Date(2014, 8, 2, 11, 55, 0), { weekStartsOn: 1 })
+ * //=> Mon Sep 01 2014 00:00:00
+ */
+export default function startOfWeek<DateType extends Date>(
+  dirtyDate: DateType | number,
+  options?: StartOfWeekOptions,
+): DateType {
+  const defaultOptions = getDefaultOptions();
+  const weekStartsOn =
+    options?.weekStartsOn ??
+    options?.locale?.options?.weekStartsOn ??
+    defaultOptions.weekStartsOn ??
+    defaultOptions.locale?.options?.weekStartsOn ??
+    0;
+
+  const date = toDate(dirtyDate);
+  const day = date.getDay();
+  const diff = (day < weekStartsOn ? 7 : 0) + day - weekStartsOn;
+
+  date.setDate(date.getDate() - diff);
+  date.setHours(0, 0, 0, 0);
+  return date;
+}

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

@@ -0,0 +1,63 @@
+import constructFrom from '../constructFrom/index';
+import getWeekYear from '../getWeekYear/index';
+import startOfWeek from '../startOfWeek/index';
+import type { FirstWeekContainsDateOptions, LocaleOptions, WeekStartOptions } from '../types';
+import { getDefaultOptions } from '../_lib/defaultOptions/index';
+
+/**
+ * The {@link startOfWeekYear} function options.
+ */
+export interface StartOfWeekYearOptions extends LocaleOptions, FirstWeekContainsDateOptions, WeekStartOptions {}
+
+/**
+ * @name startOfWeekYear
+ * @category Week-Numbering Year Helpers
+ * @summary Return the start of a local week-numbering year for the given date.
+ *
+ * @description
+ * Return the start of a local week-numbering year.
+ * The exact calculation depends on the values of
+ * `options.weekStartsOn` (which is the index of the first day of the week)
+ * and `options.firstWeekContainsDate` (which is the day of January, which is always in
+ * the first week of the week-numbering year)
+ *
+ * Week numbering: https://en.wikipedia.org/wiki/Week#Week_numbering
+ *
+ * @param date - the original date
+ * @param options - an object with options.
+ * @returns the start of a week-numbering year
+ *
+ * @example
+ * // The start of an a week-numbering year for 2 July 2005 with default settings:
+ * const result = startOfWeekYear(new Date(2005, 6, 2))
+ * //=> Sun Dec 26 2004 00:00:00
+ *
+ * @example
+ * // The start of a week-numbering year for 2 July 2005
+ * // if Monday is the first day of week
+ * // and 4 January is always in the first week of the year:
+ * const result = startOfWeekYear(new Date(2005, 6, 2), {
+ *   weekStartsOn: 1,
+ *   firstWeekContainsDate: 4
+ * })
+ * //=> Mon Jan 03 2005 00:00:00
+ */
+export default function startOfWeekYear<DateType extends Date>(
+  dirtyDate: DateType | number,
+  options?: StartOfWeekYearOptions,
+): DateType {
+  const defaultOptions = getDefaultOptions();
+  const firstWeekContainsDate =
+    options?.firstWeekContainsDate ??
+    options?.locale?.options?.firstWeekContainsDate ??
+    defaultOptions.firstWeekContainsDate ??
+    defaultOptions.locale?.options?.firstWeekContainsDate ??
+    1;
+
+  const year = getWeekYear(dirtyDate, options);
+  const firstWeek = constructFrom(dirtyDate, 0);
+  firstWeek.setFullYear(year, 0, firstWeekContainsDate);
+  firstWeek.setHours(0, 0, 0, 0);
+  const date = startOfWeek(firstWeek, options);
+  return date;
+}

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

@@ -0,0 +1,27 @@
+import toDate from '../toDate/index';
+import constructFrom from '../constructFrom/index';
+
+/**
+ * @name startOfYear
+ * @category Year Helpers
+ * @summary Return the start of a year for the given date.
+ *
+ * @description
+ * Return the start of a year for the given date.
+ * The result will be in the local timezone.
+ *
+ * @param date - the original date
+ * @returns the start of a year
+ *
+ * @example
+ * // The start of a year for 2 September 2014 11:55:00:
+ * const result = startOfYear(new Date(2014, 8, 2, 11, 55, 00))
+ * //=> Wed Jan 01 2014 00:00:00
+ */
+export default function startOfYear<DateType extends Date>(dirtyDate: DateType | number): DateType {
+  const cleanDate = toDate(dirtyDate);
+  const date = constructFrom(dirtyDate, 0);
+  date.setFullYear(cleanDate.getFullYear(), 0, 1);
+  date.setHours(0, 0, 0, 0);
+  return date;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * @name startOfYesterday
+ * @category Day Helpers
+ * @summary Return the start of yesterday.
+ * @pure false
+ *
+ * @description
+ * Return the start of yesterday.
+ *
+ * > ⚠️ Please note that this function is not present in the FP submodule as
+ * > it uses `new Date()` internally hence impure and can't be safely curried.
+ *
+ * @returns the start of yesterday
+ *
+ * @example
+ * // If today is 6 October 2014:
+ * const result = startOfYesterday()
+ * //=> Sun Oct 5 2014 00:00:00
+ */
+export default function startOfYesterday(): Date {
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = now.getMonth();
+  const day = now.getDate();
+
+  const date = new Date(0);
+  date.setFullYear(year, month, day - 1);
+  date.setHours(0, 0, 0, 0);
+  return date;
+}

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

@@ -0,0 +1,60 @@
+import subDays from '../subDays/index';
+import subMonths from '../subMonths/index';
+import type { Duration } from '../types';
+import constructFrom from '../constructFrom/index';
+
+/**
+ * @name sub
+ * @category Common Helpers
+ * @summary Subtract the specified years, months, weeks, days, hours, minutes and seconds from the given date.
+ *
+ * @description
+ * Subtract the specified years, months, weeks, days, hours, minutes and seconds from the given date.
+ *
+ * @param date - the date to be changed
+ * @param duration - the object with years, months, weeks, days, hours, minutes and seconds to be subtracted
+ *
+ * | Key     | Description                        |
+ * |---------|------------------------------------|
+ * | years   | Amount of years to be subtracted   |
+ * | months  | Amount of months to be subtracted  |
+ * | weeks   | Amount of weeks to be subtracted   |
+ * | days    | Amount of days to be subtracted    |
+ * | hours   | Amount of hours to be subtracted   |
+ * | minutes | Amount of minutes to be subtracted |
+ * | seconds | Amount of seconds to be subtracted |
+ *
+ * All values default to 0
+ *
+ * @returns the new date with the seconds subtracted
+ *
+ * @example
+ * // Subtract the following duration from 15 June 2017 15:29:20
+ * const result = sub(new Date(2017, 5, 15, 15, 29, 20), {
+ *   years: 2,
+ *   months: 9,
+ *   weeks: 1,
+ *   days: 7,
+ *   hours: 5,
+ *   minutes: 9,
+ *   seconds: 30
+ * })
+ * //=> Mon Sep 1 2014 10:19:50
+ */
+export default function sub<DateType extends Date>(date: DateType | number, duration: Duration): DateType {
+  const { years = 0, months = 0, weeks = 0, days = 0, hours = 0, minutes = 0, seconds = 0 } = duration;
+
+  // Subtract years and months
+  const dateWithoutMonths = subMonths(date, months + years * 12);
+
+  // Subtract weeks and days
+  const dateWithoutDays = subDays(dateWithoutMonths, days + weeks * 7);
+
+  // Subtract hours, minutes and seconds
+  const minutestoSub = minutes + hours * 60;
+  const secondstoSub = seconds + minutestoSub * 60;
+  const mstoSub = secondstoSub * 1000;
+  const finalDate = constructFrom(date, dateWithoutDays.getTime() - mstoSub);
+
+  return finalDate;
+}

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

@@ -0,0 +1,22 @@
+import addBusinessDays from '../addBusinessDays/index';
+
+/**
+ * @name subBusinessDays
+ * @category Day Helpers
+ * @summary Substract the specified number of business days (mon - fri) to the given date.
+ *
+ * @description
+ * Substract the specified number of business days (mon - fri) to the given date, ignoring weekends.
+ *
+ * @param date - the date to be changed
+ * @param amount - the amount of business days to be subtracted. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
+ * @returns the new date with the business days subtracted
+ *
+ * @example
+ * // Substract 10 business days from 1 September 2014:
+ * const result = subBusinessDays(new Date(2014, 8, 1), 10)
+ * //=> Mon Aug 18 2014 00:00:00 (skipped weekend days)
+ */
+export default function subBusinessDays<DateType extends Date>(dirtyDate: DateType | number, amount: number): DateType {
+  return addBusinessDays(dirtyDate, -amount);
+}

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

@@ -0,0 +1,22 @@
+import addDays from '../addDays/index';
+
+/**
+ * @name subDays
+ * @category Day Helpers
+ * @summary Subtract the specified number of days from the given date.
+ *
+ * @description
+ * Subtract the specified number of days from the given date.
+ *
+ * @param date - the date to be changed
+ * @param amount - the amount of days to be subtracted. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
+ * @returns the new date with the days subtracted
+ *
+ * @example
+ * // Subtract 10 days from 1 September 2014:
+ * const result = subDays(new Date(2014, 8, 1), 10)
+ * //=> Fri Aug 22 2014 00:00:00
+ */
+export default function subDays<DateType extends Date>(dirtyDate: DateType | number, amount: number): DateType {
+  return addDays(dirtyDate, -amount);
+}

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

@@ -0,0 +1,22 @@
+import addHours from '../addHours/index';
+
+/**
+ * @name subHours
+ * @category Hour Helpers
+ * @summary Subtract the specified number of hours from the given date.
+ *
+ * @description
+ * Subtract the specified number of hours from the given date.
+ *
+ * @param date - the date to be changed
+ * @param amount - the amount of hours to be subtracted. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
+ * @returns the new date with the hours subtracted
+ *
+ * @example
+ * // Subtract 2 hours from 11 July 2014 01:00:00:
+ * const result = subHours(new Date(2014, 6, 11, 1, 0), 2)
+ * //=> Thu Jul 10 2014 23:00:00
+ */
+export default function subHours<DateType extends Date>(dirtyDate: DateType | number, amount: number): DateType {
+  return addHours(dirtyDate, -amount);
+}

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

@@ -0,0 +1,24 @@
+import addISOWeekYears from '../addISOWeekYears/index';
+
+/**
+ * @name subISOWeekYears
+ * @category ISO Week-Numbering Year Helpers
+ * @summary Subtract the specified number of ISO week-numbering years from the given date.
+ *
+ * @description
+ * Subtract the specified number of ISO week-numbering years from the given date.
+ *
+ * ISO week-numbering year: http://en.wikipedia.org/wiki/ISO_week_date
+ *
+ * @param date - the date to be changed
+ * @param amount - the amount of ISO week-numbering years to be subtracted. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
+ * @returns the new date with the ISO week-numbering years subtracted
+ *
+ * @example
+ * // Subtract 5 ISO week-numbering years from 1 September 2014:
+ * const result = subISOWeekYears(new Date(2014, 8, 1), 5)
+ * //=> Mon Aug 31 2009 00:00:00
+ */
+export default function subISOWeekYears<DateType extends Date>(dirtyDate: DateType | number, amount: number): DateType {
+  return addISOWeekYears(dirtyDate, -amount);
+}