sanity-plugin-recurring-dates 1.3.0 → 1.3.2

package/dist/index.js

@@ -11,6 +11,7 @@ var lodash = require('lodash');
 var React = require('react');
 var rrule = require('rrule');
 var sanityPluginUtils = require('sanity-plugin-utils');
+var dateFnsTz = require('date-fns-tz');
 var legacyDateFormat = require('@sanity/util/legacyDateFormat');
 function _interopNamespaceCompat(e) {
   if (e && typeof e === 'object' && 'default' in e) return e;
@@ -2731,20 +2732,84 @@ process.env.NODE_ENV !== "production" ? {
   children: PropTypes.node.isRequired,
   className: PropTypes.string
 } : {};
-function toInteger(dirtyNumber) {
-  if (dirtyNumber === null || dirtyNumber === true || dirtyNumber === false) {
-    return NaN;
-  }
-  var number = Number(dirtyNumber);
-  if (isNaN(number)) {
-    return number;
-  }
-  return number < 0 ? Math.ceil(number) : Math.floor(number);
-}
-function requiredArgs(required, args) {
-  if (args.length < required) {
-    throw new TypeError(required + ' argument' + (required > 1 ? 's' : '') + ' required, but only ' + args.length + ' present');
-  }
+
+/**
+ * @module constants
+ * @summary Useful constants
+ * @description
+ * Collection of useful date constants.
+ *
+ * The constants could be imported from `date-fns/constants`:
+ *
+ * ```ts
+ * import { maxTime, minTime } from "./constants/date-fns/constants";
+ *
+ * function isAllowedTime(time) {
+ *   return time <= maxTime && time >= minTime;
+ * }
+ * ```
+ */
+
+/**
+ * @constant
+ * @name millisecondsInWeek
+ * @summary Milliseconds in 1 week.
+ */
+const millisecondsInWeek = 604800000;
+
+/**
+ * @constant
+ * @name constructFromSymbol
+ * @summary Symbol enabling Date extensions to inherit properties from the reference date.
+ *
+ * The symbol is used to enable the `constructFrom` function to construct a date
+ * using a reference date and a value. It allows to transfer extra properties
+ * from the reference date to the new date. It's useful for extensions like
+ * [`TZDate`](https://github.com/date-fns/tz) that accept a time zone as
+ * a constructor argument.
+ */
+const constructFromSymbol = Symbol.for("constructDateFrom");
+
+/**
+ * @name constructFrom
+ * @category Generic Helpers
+ * @summary Constructs a date using the reference date and the value
+ *
+ * @description
+ * The function constructs a new date using the constructor from the reference
+ * date and the given value. It helps to build generic functions that accept
+ * date extensions.
+ *
+ * It defaults to `Date` if the passed reference date is a number or a string.
+ *
+ * Starting from v3.7.0, it allows to construct a date using `[Symbol.for("constructDateFrom")]`
+ * enabling to transfer extra properties from the reference date to the new date.
+ * It's useful for extensions like [`TZDate`](https://github.com/date-fns/tz)
+ * that accept a time zone as a constructor argument.
+ *
+ * @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 reference date to take constructor from
+ * @param value - The value to create the date
+ *
+ * @returns Date initialized using the given date and value
+ *
+ * @example
+ * import { constructFrom } from "./constructFrom/date-fns";
+ *
+ * // A function that clones a date preserving the original type
+ * function cloneDate<DateType extends Date>(date: DateType): DateType {
+ *   return constructFrom(
+ *     date, // Use constructor from the given date
+ *     date.getTime() // Use the date value to create a new date
+ *   );
+ * }
+ */
+function constructFrom(date, value) {
+  if (typeof date === "function") return date(value);
+  if (date && typeof date === "object" && constructFromSymbol in date) return date[constructFromSymbol](value);
+  if (date instanceof Date) return new date.constructor(value);
+  return new Date(value);
 }
 
 /**
@@ -2761,11 +2826,19 @@ function requiredArgs(required, args) {
  *
  * If the argument is none of the above, the function returns Invalid Date.
  *
+ * Starting from v3.7.0, it clones a date using `[Symbol.for("constructDateFrom")]`
+ * enabling to transfer extra properties from the reference date to the new date.
+ * It's useful for extensions like [`TZDate`](https://github.com/date-fns/tz)
+ * that accept a time zone as a constructor argument.
+ *
  * **Note**: *all* Date arguments passed to any *date-fns* function is processed by `toDate`.
  *
- * @param {Date|Number} argument - the value to convert
- * @returns {Date} the parsed date in the local time zone
- * @throws {TypeError} 1 argument required
+ * @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).
+ * @typeParam ResultDate - The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.
+ *
+ * @param argument - The value to convert
+ *
+ * @returns The parsed date in the local time zone
  *
  * @example
  * // Clone the date:
@@ -2777,27 +2850,15 @@ function requiredArgs(required, args) {
  * const result = toDate(1392098430000)
  * //=> Tue Feb 11 2014 11:30:30
  */
-function toDate(argument) {
-  requiredArgs(1, arguments);
-  var argStr = Object.prototype.toString.call(argument);
-
-  // Clone the date
-  if (argument instanceof Date || _typeof(argument) === 'object' && argStr === '[object Date]') {
-    // Prevent the date to lose the milliseconds when passed to new Date() in IE10
-    return new Date(argument.getTime());
-  } else if (typeof argument === 'number' || argStr === '[object Number]') {
-    return new Date(argument);
-  } else {
-    if ((typeof argument === 'string' || argStr === '[object String]') && typeof console !== 'undefined') {
-      // eslint-disable-next-line no-console
-      console.warn("Starting with v2.0.0-beta.1 date-fns doesn't accept strings as date arguments. Please use `parseISO` to parse strings. See: https://github.com/date-fns/date-fns/blob/master/docs/upgradeGuide.md#string-arguments");
-      // eslint-disable-next-line no-console
-      console.warn(new Error().stack);
-    }
-    return new Date(NaN);
-  }
+function toDate(argument, context) {
+  // [TODO] Get rid of `toDate` or `constructFrom`?
+  return constructFrom(argument, argument);
 }
 
+/**
+ * The {@link addDays} function options.
+ */
+
 /**
  * @name addDays
  * @category Day Helpers
@@ -2806,31 +2867,34 @@ function toDate(argument) {
  * @description
  * Add the specified number of days to the given date.
  *
- * @param {Date|Number} date - the date to be changed
- * @param {Number} amount - the amount of days to be added. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
- * @returns {Date} - the new date with the days added
- * @throws {TypeError} - 2 arguments required
+ * @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).
+ * @typeParam ResultDate - The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.
+ *
+ * @param date - The date to be changed
+ * @param amount - The amount of days to be added.
+ * @param options - An object with options
+ *
+ * @returns The new date with the days added
  *
  * @example
  * // Add 10 days to 1 September 2014:
  * const result = addDays(new Date(2014, 8, 1), 10)
  * //=> Thu Sep 11 2014 00:00:00
  */
-function addDays(dirtyDate, dirtyAmount) {
-  requiredArgs(2, arguments);
-  var date = toDate(dirtyDate);
-  var amount = toInteger(dirtyAmount);
-  if (isNaN(amount)) {
-    return new Date(NaN);
-  }
-  if (!amount) {
-    // If 0 days, no-op to avoid changing times in the hour before end of DST
-    return date;
-  }
-  date.setDate(date.getDate() + amount);
-  return date;
+function addDays(date, amount, options) {
+  const _date = toDate(date);
+  if (isNaN(amount)) return constructFrom(date, NaN);
+
+  // If 0 days, no-op to avoid changing times in the hour before end of DST
+  if (!amount) return _date;
+  _date.setDate(_date.getDate() + amount);
+  return _date;
 }
 
+/**
+ * The {@link addMonths} function options.
+ */
+
 /**
  * @name addMonths
  * @category Month Helpers
@@ -2839,28 +2903,32 @@ function addDays(dirtyDate, dirtyAmount) {
  * @description
  * Add the specified number of months to the given date.
  *
- * @param {Date|Number} date - the date to be changed
- * @param {Number} amount - the amount of months to be added. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
- * @returns {Date} the new date with the months added
- * @throws {TypeError} 2 arguments required
+ * @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).
+ * @typeParam ResultDate - The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.
+ *
+ * @param date - The date to be changed
+ * @param amount - The amount of months to be added.
+ * @param options - The options object
+ *
+ * @returns The new date with the months added
  *
  * @example
  * // Add 5 months to 1 September 2014:
  * const result = addMonths(new Date(2014, 8, 1), 5)
  * //=> Sun Feb 01 2015 00:00:00
+ *
+ * // Add one month to 30 January 2023:
+ * const result = addMonths(new Date(2023, 0, 30), 1)
+ * //=> Tue Feb 28 2023 00:00:00
  */
-function addMonths(dirtyDate, dirtyAmount) {
-  requiredArgs(2, arguments);
-  var date = toDate(dirtyDate);
-  var amount = toInteger(dirtyAmount);
-  if (isNaN(amount)) {
-    return new Date(NaN);
-  }
+function addMonths(date, amount, options) {
+  const _date = toDate(date);
+  if (isNaN(amount)) return constructFrom(date, NaN);
   if (!amount) {
     // If 0 months, no-op to avoid changing times in the hour before end of DST
-    return date;
+    return _date;
   }
-  var dayOfMonth = date.getDate();
+  const dayOfMonth = _date.getDate();
 
   // The JS Date object supports date math by accepting out-of-bounds values for
   // month, day, etc. For example, new Date(2020, 0, 0) returns 31 Dec 2019 and
@@ -2870,9 +2938,9 @@ function addMonths(dirtyDate, dirtyAmount) {
   // we'll default to the end of the desired month by adding 1 to the desired
   // month and using a date of 0 to back up one day to the end of the desired
   // month.
-  var endOfDesiredMonth = new Date(date.getTime());
-  endOfDesiredMonth.setMonth(date.getMonth() + amount + 1, 0);
-  var daysInMonth = endOfDesiredMonth.getDate();
+  const endOfDesiredMonth = constructFrom(date, _date.getTime());
+  endOfDesiredMonth.setMonth(_date.getMonth() + amount + 1, 0);
+  const daysInMonth = endOfDesiredMonth.getDate();
   if (dayOfMonth >= daysInMonth) {
     // If we're already at the end of the month, then this is the correct date
     // and we're done.
@@ -2885,15 +2953,19 @@ function addMonths(dirtyDate, dirtyAmount) {
     // the last day of the month and its local time was in the hour skipped or
     // repeated next to a DST transition.  So we use `date` instead which is
     // guaranteed to still have the original time.
-    date.setFullYear(endOfDesiredMonth.getFullYear(), endOfDesiredMonth.getMonth(), dayOfMonth);
-    return date;
+    _date.setFullYear(endOfDesiredMonth.getFullYear(), endOfDesiredMonth.getMonth(), dayOfMonth);
+    return _date;
   }
 }
-var defaultOptions = {};
+let defaultOptions = {};
 function getDefaultOptions() {
   return defaultOptions;
 }
 
+/**
+ * The {@link startOfWeek} function options.
+ */
+
 /**
  * @name startOfWeek
  * @category Week Helpers
@@ -2903,13 +2975,13 @@ function getDefaultOptions() {
  * Return the start of a week for the given date.
  * The result will be in the local timezone.
  *
- * @param {Date|Number} date - the original date
- * @param {Object} [options] - an object with options.
- * @param {Locale} [options.locale=defaultLocale] - the locale object. See [Locale]{@link https://date-fns.org/docs/Locale}
- * @param {0|1|2|3|4|5|6} [options.weekStartsOn=0] - the index of the first day of the week (0 - Sunday)
- * @returns {Date} the start of a week
- * @throws {TypeError} 1 argument required
- * @throws {RangeError} `options.weekStartsOn` must be between 0 and 6
+ * @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).
+ * @typeParam ResultDate - The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.
+ *
+ * @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:
@@ -2921,24 +2993,28 @@ function getDefaultOptions() {
  * const result = startOfWeek(new Date(2014, 8, 2, 11, 55, 0), { weekStartsOn: 1 })
  * //=> Mon Sep 01 2014 00:00:00
  */
-function startOfWeek(dirtyDate, options) {
-  var _ref, _ref2, _ref3, _options$weekStartsOn, _defaultOptions$local, _defaultOptions$local2;
-  requiredArgs(1, arguments);
-  var defaultOptions = getDefaultOptions();
-  var weekStartsOn = toInteger((_ref = (_ref2 = (_ref3 = (_options$weekStartsOn = void 0) !== null && _options$weekStartsOn !== void 0 ? _options$weekStartsOn : void 0) !== null && _ref3 !== void 0 ? _ref3 : defaultOptions.weekStartsOn) !== null && _ref2 !== void 0 ? _ref2 : (_defaultOptions$local = defaultOptions.locale) === null || _defaultOptions$local === void 0 ? void 0 : (_defaultOptions$local2 = _defaultOptions$local.options) === null || _defaultOptions$local2 === void 0 ? void 0 : _defaultOptions$local2.weekStartsOn) !== null && _ref !== void 0 ? _ref : 0);
-
-  // Test if weekStartsOn is between 0 and 6 _and_ is not NaN
-  if (!(weekStartsOn >= 0 && weekStartsOn <= 6)) {
-    throw new RangeError('weekStartsOn must be between 0 and 6 inclusively');
+function startOfWeek(date, options) {
+  const defaultOptions = getDefaultOptions();
+  const weekStartsOn = defaultOptions.weekStartsOn ?? defaultOptions.locale?.options?.weekStartsOn ?? 0;
+  const _date = toDate(date);
+  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;
+}
+function normalizeDates(context) {
+  for (var _len = arguments.length, dates = new Array(_len > 1 ? _len - 1 : 0), _key = 1; _key < _len; _key++) {
+    dates[_key - 1] = arguments[_key];
   }
-  var date = toDate(dirtyDate);
-  var day = date.getDay();
-  var diff = (day < weekStartsOn ? 7 : 0) + day - weekStartsOn;
-  date.setDate(date.getDate() - diff);
-  date.setHours(0, 0, 0, 0);
-  return date;
+  const normalize = constructFrom.bind(null, dates.find(date => typeof date === "object"));
+  return dates.map(normalize);
 }
 
+/**
+ * The {@link startOfDay} function options.
+ */
+
 /**
  * @name startOfDay
  * @category Day Helpers
@@ -2948,47 +3024,59 @@ function startOfWeek(dirtyDate, options) {
  * Return the start of a day for the given date.
  * The result will be in the local timezone.
  *
- * @param {Date|Number} date - the original date
- * @returns {Date} the start of a day
- * @throws {TypeError} 1 argument required
+ * @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).
+ * @typeParam ResultDate - The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.
+ *
+ * @param date - The original date
+ * @param options - The options
+ *
+ * @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
  */
-function startOfDay(dirtyDate) {
-  requiredArgs(1, arguments);
-  var date = toDate(dirtyDate);
-  date.setHours(0, 0, 0, 0);
-  return date;
+function startOfDay(date, options) {
+  const _date = toDate(date);
+  _date.setHours(0, 0, 0, 0);
+  return _date;
 }
 
+/**
+ * The {@link addWeeks} function options.
+ */
+
 /**
  * @name addWeeks
  * @category Week Helpers
  * @summary Add the specified number of weeks to the given date.
  *
  * @description
- * Add the specified number of week to the given date.
+ * Add the specified number of weeks to the given 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).
+ * @typeParam ResultDate - The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.
  *
- * @param {Date|Number} date - the date to be changed
- * @param {Number} amount - the amount of weeks to be added. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
- * @returns {Date} the new date with the weeks added
- * @throws {TypeError} 2 arguments required
+ * @param date - The date to be changed
+ * @param amount - The amount of weeks to be added.
+ * @param options - An object with options
+ *
+ * @returns The new date with the weeks added
  *
  * @example
  * // Add 4 weeks to 1 September 2014:
  * const result = addWeeks(new Date(2014, 8, 1), 4)
  * //=> Mon Sep 29 2014 00:00:00
  */
-function addWeeks(dirtyDate, dirtyAmount) {
-  requiredArgs(2, arguments);
-  var amount = toInteger(dirtyAmount);
-  var days = amount * 7;
-  return addDays(dirtyDate, days);
+function addWeeks(date, amount, options) {
+  return addDays(date, amount * 7);
 }
 
+/**
+ * The {@link isSameDay} function options.
+ */
+
 /**
  * @name isSameDay
  * @category Day Helpers
@@ -2997,10 +3085,11 @@ function addWeeks(dirtyDate, dirtyAmount) {
  * @description
  * Are the given dates in the same day (and year and month)?
  *
- * @param {Date|Number} dateLeft - the first date to check
- * @param {Date|Number} dateRight - the second date to check
- * @returns {Boolean} the dates are in the same day (and year and month)
- * @throws {TypeError} 2 arguments required
+ * @param laterDate - The first date to check
+ * @param earlierDate - The second date to check
+ * @param options - An object with options
+ *
+ * @returns The dates are in the same day (and year and month)
  *
  * @example
  * // Are 4 September 06:00:00 and 4 September 18:00:00 in the same day?
@@ -3017,13 +3106,28 @@ function addWeeks(dirtyDate, dirtyAmount) {
  * const result = isSameDay(new Date(2014, 8, 4), new Date(2015, 8, 4))
  * //=> false
  */
-function isSameDay(dirtyDateLeft, dirtyDateRight) {
-  requiredArgs(2, arguments);
-  var dateLeftStartOfDay = startOfDay(dirtyDateLeft);
-  var dateRightStartOfDay = startOfDay(dirtyDateRight);
-  return dateLeftStartOfDay.getTime() === dateRightStartOfDay.getTime();
+function isSameDay(laterDate, earlierDate, options) {
+  const [dateLeft_, dateRight_] = normalizeDates(options?.in, laterDate, earlierDate);
+  return +startOfDay(dateLeft_) === +startOfDay(dateRight_);
+}
+function normalizeInterval(context, interval) {
+  const [start, end] = normalizeDates(context, interval.start, interval.end);
+  return {
+    start,
+    end
+  };
 }
 
+/**
+ * The {@link eachWeekOfInterval} function options.
+ */
+
+/**
+ * The {@link eachWeekOfInterval} function result type. It resolves the proper data type.
+ * It uses the first argument date object type, starting from the interval start date,
+ * then the end interval date. If a context function is passed, it uses the context function return type.
+ */
+
 /**
  * @name eachWeekOfInterval
  * @category Interval Helpers
@@ -3032,15 +3136,10 @@ function isSameDay(dirtyDateLeft, dirtyDateRight) {
  * @description
  * Return the array of weeks within the specified time interval.
  *
- * @param {Interval} interval - the interval. See [Interval]{@link https://date-fns.org/docs/Interval}
- * @param {Object} [options] - an object with options.
- * @param {Locale} [options.locale=defaultLocale] - the locale object. See [Locale]{@link https://date-fns.org/docs/Locale}
- * @param {0|1|2|3|4|5|6} [options.weekStartsOn=0] - the index of the first day of the week (0 - Sunday)
- * @returns {Date[]} the array with starts of weeks from the week of the interval start to the week of the interval end
- * @throws {TypeError} 1 argument required
- * @throws {RangeError} `options.weekStartsOn` must be 0, 1, ..., 6
- * @throws {RangeError} The start of an interval cannot be after its end
- * @throws {RangeError} Date in interval cannot be `Invalid Date`
+ * @param interval - The interval.
+ * @param options - An object with options.
+ *
+ * @returns The array with starts of weeks from the week of the interval start to the week of the interval end
  *
  * @example
  * // Each week within interval 6 October 2014 - 23 November 2014:
@@ -3059,88 +3158,66 @@ function isSameDay(dirtyDateLeft, dirtyDateRight) {
  * //   Sun Nov 23 2014 00:00:00
  * // ]
  */
-function eachWeekOfInterval(dirtyInterval, options) {
-  requiredArgs(1, arguments);
-  var interval = dirtyInterval || {};
-  var startDate = toDate(interval.start);
-  var endDate = toDate(interval.end);
-  var endTime = endDate.getTime();
-
-  // Throw an exception if start date is after end date or if any date is `Invalid Date`
-  if (!(startDate.getTime() <= endTime)) {
-    throw new RangeError('Invalid interval');
-  }
-  var startDateWeek = startOfWeek(startDate, options);
-  var endDateWeek = startOfWeek(endDate, options);
-
-  // Some timezones switch DST at midnight, making start of day unreliable in these timezones, 3pm is a safe bet
+function eachWeekOfInterval(interval, options) {
+  const {
+    start,
+    end
+  } = normalizeInterval(options?.in, interval);
+  let reversed = +start > +end;
+  const startDateWeek = reversed ? startOfWeek(end) : startOfWeek(start);
+  const endDateWeek = reversed ? startOfWeek(start) : startOfWeek(end);
   startDateWeek.setHours(15);
   endDateWeek.setHours(15);
-  endTime = endDateWeek.getTime();
-  var weeks = [];
-  var currentWeek = startDateWeek;
-  while (currentWeek.getTime() <= endTime) {
-    currentWeek.setHours(0);
-    weeks.push(toDate(currentWeek));
-    currentWeek = addWeeks(currentWeek, 1);
-    currentWeek.setHours(15);
+  const endTime = +endDateWeek.getTime();
+  let currentDate = startDateWeek;
+  let step = 1;
+  const dates = [];
+  while (+currentDate <= endTime) {
+    currentDate.setHours(0);
+    dates.push(constructFrom(start, currentDate));
+    currentDate = addWeeks(currentDate, step);
+    currentDate.setHours(15);
   }
-  return weeks;
+  return reversed ? dates.reverse() : dates;
 }
 
+/**
+ * The {@link startOfMonth} function options.
+ */
+
 /**
  * @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.
+ * Return the start of a month for the given date. The result will be in the local timezone.
  *
- * @param {Date|Number} date - the original date
- * @returns {Date} the start of a month
- * @throws {TypeError} 1 argument required
+ * @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).
+ * @typeParam ResultDate - The result `Date` type, it is the type returned from the context function if it is passed,
+ * or inferred from the arguments.
+ *
+ * @param date - The original date
+ * @param options - An object with options
+ *
+ * @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
  */
-function startOfMonth(dirtyDate) {
-  requiredArgs(1, arguments);
-  var date = toDate(dirtyDate);
-  date.setDate(1);
-  date.setHours(0, 0, 0, 0);
-  return date;
+function startOfMonth(date, options) {
+  const _date = toDate(date);
+  _date.setDate(1);
+  _date.setHours(0, 0, 0, 0);
+  return _date;
 }
 
 /**
- * @name getDaysInMonth
- * @category Month Helpers
- * @summary Get the number of days in a month of the given date.
- *
- * @description
- * Get the number of days in a month of the given date.
- *
- * @param {Date|Number} date - the given date
- * @returns {Number} the number of days in a month
- * @throws {TypeError} 1 argument required
- *
- * @example
- * // How many days are in February 2000?
- * const result = getDaysInMonth(new Date(2000, 1))
- * //=> 29
+ * The {@link getWeekYear} function options.
  */
-function getDaysInMonth(dirtyDate) {
-  requiredArgs(1, arguments);
-  var date = toDate(dirtyDate);
-  var year = date.getFullYear();
-  var monthIndex = date.getMonth();
-  var lastDayOfMonth = new Date(0);
-  lastDayOfMonth.setFullYear(year, monthIndex + 1, 0);
-  lastDayOfMonth.setHours(0, 0, 0, 0);
-  return lastDayOfMonth.getDate();
-}
 
 /**
  * @name getWeekYear
@@ -3154,17 +3231,12 @@ function getDaysInMonth(dirtyDate) {
  * 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
+ * Week numbering: https://en.wikipedia.org/wiki/Week#The_ISO_week_date_system
+ *
+ * @param date - The given date
+ * @param options - An object with options.
  *
- * @param {Date|Number} date - the given date
- * @param {Object} [options] - an object with options.
- * @param {Locale} [options.locale=defaultLocale] - the locale object. See [Locale]{@link https://date-fns.org/docs/Locale}
- * @param {0|1|2|3|4|5|6} [options.weekStartsOn=0] - the index of the first day of the week (0 - Sunday)
- * @param {1|2|3|4|5|6|7} [options.firstWeekContainsDate=1] - the day of January, which is always in the first week of the year
- * @returns {Number} the local week-numbering year
- * @throws {TypeError} 1 argument required
- * @throws {RangeError} `options.weekStartsOn` must be between 0 and 6
- * @throws {RangeError} `options.firstWeekContainsDate` must be between 1 and 7
+ * @returns The local week-numbering year
  *
  * @example
  * // Which week numbering year is 26 December 2004 with the default settings?
@@ -3181,35 +3253,32 @@ function getDaysInMonth(dirtyDate) {
  * const result = getWeekYear(new Date(2004, 11, 26), { firstWeekContainsDate: 4 })
  * //=> 2004
  */
-function getWeekYear(dirtyDate, options) {
-  var _ref, _ref2, _ref3, _options$firstWeekCon, _defaultOptions$local, _defaultOptions$local2;
-  requiredArgs(1, arguments);
-  var date = toDate(dirtyDate);
-  var year = date.getFullYear();
-  var defaultOptions = getDefaultOptions();
-  var firstWeekContainsDate = toInteger((_ref = (_ref2 = (_ref3 = (_options$firstWeekCon = void 0) !== null && _options$firstWeekCon !== void 0 ? _options$firstWeekCon : void 0) !== null && _ref3 !== void 0 ? _ref3 : defaultOptions.firstWeekContainsDate) !== null && _ref2 !== void 0 ? _ref2 : (_defaultOptions$local = defaultOptions.locale) === null || _defaultOptions$local === void 0 ? void 0 : (_defaultOptions$local2 = _defaultOptions$local.options) === null || _defaultOptions$local2 === void 0 ? void 0 : _defaultOptions$local2.firstWeekContainsDate) !== null && _ref !== void 0 ? _ref : 1);
-
-  // Test if weekStartsOn is between 1 and 7 _and_ is not NaN
-  if (!(firstWeekContainsDate >= 1 && firstWeekContainsDate <= 7)) {
-    throw new RangeError('firstWeekContainsDate must be between 1 and 7 inclusively');
-  }
-  var firstWeekOfNextYear = new Date(0);
+function getWeekYear(date, options) {
+  const _date = toDate(date);
+  const year = _date.getFullYear();
+  const defaultOptions = getDefaultOptions();
+  const firstWeekContainsDate = defaultOptions.firstWeekContainsDate ?? defaultOptions.locale?.options?.firstWeekContainsDate ?? 1;
+  const firstWeekOfNextYear = constructFrom(date, 0);
   firstWeekOfNextYear.setFullYear(year + 1, 0, firstWeekContainsDate);
   firstWeekOfNextYear.setHours(0, 0, 0, 0);
-  var startOfNextYear = startOfWeek(firstWeekOfNextYear, options);
-  var firstWeekOfThisYear = new Date(0);
+  const startOfNextYear = startOfWeek(firstWeekOfNextYear);
+  const firstWeekOfThisYear = constructFrom(date, 0);
   firstWeekOfThisYear.setFullYear(year, 0, firstWeekContainsDate);
   firstWeekOfThisYear.setHours(0, 0, 0, 0);
-  var startOfThisYear = startOfWeek(firstWeekOfThisYear, options);
-  if (date.getTime() >= startOfNextYear.getTime()) {
+  const startOfThisYear = startOfWeek(firstWeekOfThisYear);
+  if (+_date >= +startOfNextYear) {
     return year + 1;
-  } else if (date.getTime() >= startOfThisYear.getTime()) {
+  } else if (+_date >= +startOfThisYear) {
     return year;
   } else {
     return year - 1;
   }
 }
 
+/**
+ * The {@link startOfWeekYear} function options.
+ */
+
 /**
  * @name startOfWeekYear
  * @category Week-Numbering Year Helpers
@@ -3222,17 +3291,15 @@ function getWeekYear(dirtyDate, options) {
  * 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
+ * Week numbering: https://en.wikipedia.org/wiki/Week#The_ISO_week_date_system
+ *
+ * @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).
+ * @typeParam ResultDate - The result `Date` type.
  *
- * @param {Date|Number} date - the original date
- * @param {Object} [options] - an object with options.
- * @param {Locale} [options.locale=defaultLocale] - the locale object. See [Locale]{@link https://date-fns.org/docs/Locale}
- * @param {0|1|2|3|4|5|6} [options.weekStartsOn=0] - the index of the first day of the week (0 - Sunday)
- * @param {1|2|3|4|5|6|7} [options.firstWeekContainsDate=1] - the day of January, which is always in the first week of the year
- * @returns {Date} the start of a week-numbering year
- * @throws {TypeError} 1 argument required
- * @throws {RangeError} `options.weekStartsOn` must be between 0 and 6
- * @throws {RangeError} `options.firstWeekContainsDate` must be between 1 and 7
+ * @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:
@@ -3249,19 +3316,20 @@ function getWeekYear(dirtyDate, options) {
  * })
  * //=> Mon Jan 03 2005 00:00:00
  */
-function startOfWeekYear(dirtyDate, options) {
-  var _ref, _ref2, _ref3, _options$firstWeekCon, _defaultOptions$local, _defaultOptions$local2;
-  requiredArgs(1, arguments);
-  var defaultOptions = getDefaultOptions();
-  var firstWeekContainsDate = toInteger((_ref = (_ref2 = (_ref3 = (_options$firstWeekCon = void 0) !== null && _options$firstWeekCon !== void 0 ? _options$firstWeekCon : void 0) !== null && _ref3 !== void 0 ? _ref3 : defaultOptions.firstWeekContainsDate) !== null && _ref2 !== void 0 ? _ref2 : (_defaultOptions$local = defaultOptions.locale) === null || _defaultOptions$local === void 0 ? void 0 : (_defaultOptions$local2 = _defaultOptions$local.options) === null || _defaultOptions$local2 === void 0 ? void 0 : _defaultOptions$local2.firstWeekContainsDate) !== null && _ref !== void 0 ? _ref : 1);
-  var year = getWeekYear(dirtyDate, options);
-  var firstWeek = new Date(0);
+function startOfWeekYear(date, options) {
+  const defaultOptions = getDefaultOptions();
+  const firstWeekContainsDate = defaultOptions.firstWeekContainsDate ?? defaultOptions.locale?.options?.firstWeekContainsDate ?? 1;
+  const year = getWeekYear(date);
+  const firstWeek = constructFrom(date, 0);
   firstWeek.setFullYear(year, 0, firstWeekContainsDate);
   firstWeek.setHours(0, 0, 0, 0);
-  var date = startOfWeek(firstWeek, options);
-  return date;
+  const _date = startOfWeek(firstWeek);
+  return _date;
 }
-var MILLISECONDS_IN_WEEK = 604800000;
+
+/**
+ * The {@link getWeek} function options.
+ */
 
 /**
  * @name getWeek
@@ -3275,23 +3343,19 @@ var MILLISECONDS_IN_WEEK = 604800000;
  * 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
+ * Week numbering: https://en.wikipedia.org/wiki/Week#The_ISO_week_date_system
+ *
+ * @param date - The given date
+ * @param options - An object with options
  *
- * @param {Date|Number} date - the given date
- * @param {Object} [options] - an object with options.
- * @param {Locale} [options.locale=defaultLocale] - the locale object. See [Locale]{@link https://date-fns.org/docs/Locale}
- * @param {0|1|2|3|4|5|6} [options.weekStartsOn=0] - the index of the first day of the week (0 - Sunday)
- * @param {1|2|3|4|5|6|7} [options.firstWeekContainsDate=1] - the day of January, which is always in the first week of the year
- * @returns {Number} the week
- * @throws {TypeError} 1 argument required
- * @throws {RangeError} `options.weekStartsOn` must be between 0 and 6
- * @throws {RangeError} `options.firstWeekContainsDate` must be between 1 and 7
+ * @returns The week
  *
  * @example
  * // Which week of the local week numbering year is 2 January 2005 with default options?
  * const result = getWeek(new Date(2005, 0, 2))
  * //=> 2
  *
+ * @example
  * // Which week of the local week numbering year is 2 January 2005,
  * // if Monday is the first day of the week,
  * // and the first week of the year always contains 4 January?
@@ -3301,18 +3365,52 @@ var MILLISECONDS_IN_WEEK = 604800000;
  * })
  * //=> 53
  */
+function getWeek(date, options) {
+  const _date = toDate(date);
+  const diff = +startOfWeek(_date) - +startOfWeekYear(_date);
 
-function getWeek(dirtyDate, options) {
-  requiredArgs(1, arguments);
-  var date = toDate(dirtyDate);
-  var diff = startOfWeek(date, options).getTime() - startOfWeekYear(date, options).getTime();
+  // Round the number of weeks to the nearest integer because the number of
+  // milliseconds in a week is not constant (e.g. it's different in the week of
+  // the daylight saving time clock shift).
+  return Math.round(diff / millisecondsInWeek) + 1;
+}
 
-  // Round the number of days to the nearest integer
-  // because the number of milliseconds in a week is not constant
-  // (e.g. it's different in the week of the daylight saving time clock shift)
-  return Math.round(diff / MILLISECONDS_IN_WEEK) + 1;
+/**
+ * The {@link getDaysInMonth} function options.
+ */
+
+/**
+ * @name getDaysInMonth
+ * @category Month Helpers
+ * @summary Get the number of days in a month of the given date.
+ *
+ * @description
+ * Get the number of days in a month of the given date, considering the context if provided.
+ *
+ * @param date - The given date
+ * @param options - An object with options
+ *
+ * @returns The number of days in a month
+ *
+ * @example
+ * // How many days are in February 2000?
+ * const result = getDaysInMonth(new Date(2000, 1))
+ * //=> 29
+ */
+function getDaysInMonth(date, options) {
+  const _date = toDate(date);
+  const year = _date.getFullYear();
+  const monthIndex = _date.getMonth();
+  const lastDayOfMonth = constructFrom(_date, 0);
+  lastDayOfMonth.setFullYear(year, monthIndex + 1, 0);
+  lastDayOfMonth.setHours(0, 0, 0, 0);
+  return lastDayOfMonth.getDate();
 }
 
+/**
+ * The {@link lastDayOfMonth} function options.
+ */
+
 /**
  * @name lastDayOfMonth
  * @category Month Helpers
@@ -3322,24 +3420,31 @@ function getWeek(dirtyDate, options) {
  * Return the last day of a month for the given date.
  * The result will be in the local timezone.
  *
- * @param {Date|Number} date - the original date
- * @returns {Date} the last day of a month
- * @throws {TypeError} 1 argument required
+ * @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).
+ * @typeParam ResultDate - The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.
+ *
+ * @param date - The original date
+ * @param options - An object with options
+ *
+ * @returns The last day of a month
  *
  * @example
  * // The last day of a month for 2 September 2014 11:55:00:
  * const result = lastDayOfMonth(new Date(2014, 8, 2, 11, 55, 0))
  * //=> Tue Sep 30 2014 00:00:00
  */
-function lastDayOfMonth(dirtyDate) {
-  requiredArgs(1, arguments);
-  var date = toDate(dirtyDate);
-  var month = date.getMonth();
-  date.setFullYear(date.getFullYear(), month + 1, 0);
-  date.setHours(0, 0, 0, 0);
-  return date;
+function lastDayOfMonth(date, options) {
+  const _date = toDate(date);
+  const month = _date.getMonth();
+  _date.setFullYear(_date.getFullYear(), month + 1, 0);
+  _date.setHours(0, 0, 0, 0);
+  return toDate(_date);
 }
 
+/**
+ * The {@link isSameMonth} function options.
+ */
+
 /**
  * @name isSameMonth
  * @category Month Helpers
@@ -3348,10 +3453,11 @@ function lastDayOfMonth(dirtyDate) {
  * @description
  * Are the given dates in the same month (and year)?
  *
- * @param {Date|Number} dateLeft - the first date to check
- * @param {Date|Number} dateRight - the second date to check
- * @returns {Boolean} the dates are in the same month (and year)
- * @throws {TypeError} 2 arguments required
+ * @param laterDate - The first date to check
+ * @param earlierDate - The second date to check
+ * @param options - An object with options
+ *
+ * @returns The dates are in the same month (and year)
  *
  * @example
  * // Are 2 September 2014 and 25 September 2014 in the same month?
@@ -3363,13 +3469,15 @@ function lastDayOfMonth(dirtyDate) {
  * const result = isSameMonth(new Date(2014, 8, 2), new Date(2015, 8, 25))
  * //=> false
  */
-function isSameMonth(dirtyDateLeft, dirtyDateRight) {
-  requiredArgs(2, arguments);
-  var dateLeft = toDate(dirtyDateLeft);
-  var dateRight = toDate(dirtyDateRight);
-  return dateLeft.getFullYear() === dateRight.getFullYear() && dateLeft.getMonth() === dateRight.getMonth();
+function isSameMonth(laterDate, earlierDate, options) {
+  const [laterDate_, earlierDate_] = normalizeDates(options?.in, laterDate, earlierDate);
+  return laterDate_.getFullYear() === earlierDate_.getFullYear() && laterDate_.getMonth() === earlierDate_.getMonth();
 }
 
+/**
+ * The {@link setMonth} function options.
+ */
+
 /**
  * @name setMonth
  * @category Month Helpers
@@ -3378,32 +3486,38 @@ function isSameMonth(dirtyDateLeft, dirtyDateRight) {
  * @description
  * Set the month to the given date.
  *
- * @param {Date|Number} date - the date to be changed
- * @param {Number} month - the month of the new date
- * @returns {Date} the new date with the month set
- * @throws {TypeError} 2 arguments required
+ * @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).
+ * @typeParam ResultDate - The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.
+ *
+ * @param date - The date to be changed
+ * @param month - The month index to set (0-11)
+ * @param options - The options
+ *
+ * @returns The new date with the month set
  *
  * @example
  * // Set February to 1 September 2014:
  * const result = setMonth(new Date(2014, 8, 1), 1)
  * //=> Sat Feb 01 2014 00:00:00
  */
-function setMonth(dirtyDate, dirtyMonth) {
-  requiredArgs(2, arguments);
-  var date = toDate(dirtyDate);
-  var month = toInteger(dirtyMonth);
-  var year = date.getFullYear();
-  var day = date.getDate();
-  var dateWithDesiredMonth = new Date(0);
-  dateWithDesiredMonth.setFullYear(year, month, 15);
-  dateWithDesiredMonth.setHours(0, 0, 0, 0);
-  var daysInMonth = getDaysInMonth(dateWithDesiredMonth);
-  // Set the last day of the new month
-  // if the original date was the last day of the longer month
-  date.setMonth(month, Math.min(day, daysInMonth));
-  return date;
+function setMonth(date, month, options) {
+  const _date = toDate(date);
+  const year = _date.getFullYear();
+  const day = _date.getDate();
+  const midMonth = constructFrom(date, 0);
+  midMonth.setFullYear(year, month, 15);
+  midMonth.setHours(0, 0, 0, 0);
+  const daysInMonth = getDaysInMonth(midMonth);
+
+  // Set the earlier date, allows to wrap Jan 31 to Feb 28
+  _date.setMonth(month, Math.min(day, daysInMonth));
+  return _date;
 }
 
+/**
+ * The {@link setDate} function options.
+ */
+
 /**
  * @name setDate
  * @category Day Helpers
@@ -3412,24 +3526,30 @@ function setMonth(dirtyDate, dirtyMonth) {
  * @description
  * Set the day of the month to the given date.
  *
- * @param {Date|Number} date - the date to be changed
- * @param {Number} dayOfMonth - the day of the month of the new date
- * @returns {Date} the new date with the day of the month set
- * @throws {TypeError} 2 arguments required
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows using extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ * @typeParam ResultDate - The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.
+ *
+ * @param date - The date to be changed
+ * @param dayOfMonth - The day of the month of the new date
+ * @param options - The options
+ *
+ * @returns The new date with the day of the month set
  *
  * @example
  * // Set the 30th day of the month to 1 September 2014:
  * const result = setDate(new Date(2014, 8, 1), 30)
  * //=> Tue Sep 30 2014 00:00:00
  */
-function setDate(dirtyDate, dirtyDayOfMonth) {
-  requiredArgs(2, arguments);
-  var date = toDate(dirtyDate);
-  var dayOfMonth = toInteger(dirtyDayOfMonth);
-  date.setDate(dayOfMonth);
-  return date;
+function setDate(date, dayOfMonth, options) {
+  const _date = toDate(date);
+  _date.setDate(dayOfMonth);
+  return _date;
 }
 
+/**
+ * The {@link setHours} function options.
+ */
+
 /**
  * @name setHours
  * @category Hour Helpers
@@ -3438,24 +3558,30 @@ function setDate(dirtyDate, dirtyDayOfMonth) {
  * @description
  * Set the hours to the given date.
  *
- * @param {Date|Number} date - the date to be changed
- * @param {Number} hours - the hours of the new date
- * @returns {Date} the new date with the hours set
- * @throws {TypeError} 2 arguments required
+ * @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).
+ * @typeParam ResultDate - The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.
+ *
+ * @param date - The date to be changed
+ * @param hours - The hours of the new date
+ * @param options - An object with options
+ *
+ * @returns The new date with the hours set
  *
  * @example
  * // Set 4 hours to 1 September 2014 11:30:00:
  * const result = setHours(new Date(2014, 8, 1, 11, 30), 4)
  * //=> Mon Sep 01 2014 04:30:00
  */
-function setHours(dirtyDate, dirtyHours) {
-  requiredArgs(2, arguments);
-  var date = toDate(dirtyDate);
-  var hours = toInteger(dirtyHours);
-  date.setHours(hours);
-  return date;
+function setHours(date, hours, options) {
+  const _date = toDate(date);
+  _date.setHours(hours);
+  return _date;
 }
 
+/**
+ * The {@link setMinutes} function options.
+ */
+
 /**
  * @name setMinutes
  * @category Minute Helpers
@@ -3464,24 +3590,30 @@ function setHours(dirtyDate, dirtyHours) {
  * @description
  * Set the minutes to the given date.
  *
- * @param {Date|Number} date - the date to be changed
- * @param {Number} minutes - the minutes of the new date
- * @returns {Date} the new date with the minutes set
- * @throws {TypeError} 2 arguments required
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows using extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ * @typeParam ResultDate - The result `Date` type, returned from the context function, or inferred from the arguments.
+ *
+ * @param date - The date to be changed
+ * @param minutes - The minutes of the new date
+ * @param options - An object with options
+ *
+ * @returns The new date with the minutes set
  *
  * @example
  * // Set 45 minutes to 1 September 2014 11:30:40:
  * const result = setMinutes(new Date(2014, 8, 1, 11, 30, 40), 45)
  * //=> Mon Sep 01 2014 11:45:40
  */
-function setMinutes(dirtyDate, dirtyMinutes) {
-  requiredArgs(2, arguments);
-  var date = toDate(dirtyDate);
-  var minutes = toInteger(dirtyMinutes);
-  date.setMinutes(minutes);
-  return date;
+function setMinutes(date, minutes, options) {
+  const date_ = toDate(date);
+  date_.setMinutes(minutes);
+  return date_;
 }
 
+/**
+ * The {@link setYear} function options.
+ */
+
 /**
  * @name setYear
  * @category Year Helpers
@@ -3490,27 +3622,27 @@ function setMinutes(dirtyDate, dirtyMinutes) {
  * @description
  * Set the year to the given date.
  *
- * @param {Date|Number} date - the date to be changed
- * @param {Number} year - the year of the new date
- * @returns {Date} the new date with the year set
- * @throws {TypeError} 2 arguments required
+ * @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).
+ * @typeParam ResultDate - The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.
+ *
+ * @param date - The date to be changed
+ * @param year - The year of the new date
+ * @param options - An object with options.
+ *
+ * @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
  */
-function setYear(dirtyDate, dirtyYear) {
-  requiredArgs(2, arguments);
-  var date = toDate(dirtyDate);
-  var year = toInteger(dirtyYear);
+function setYear(date, year, options) {
+  const date_ = toDate(date);
 
   // Check if date is Invalid Date because Date.prototype.setFullYear ignores the value of Invalid Date
-  if (isNaN(date.getTime())) {
-    return new Date(NaN);
-  }
-  date.setFullYear(year);
-  return date;
+  if (isNaN(+date_)) return constructFrom(date, NaN);
+  date_.setFullYear(year);
+  return date_;
 }
 function CalendarDay(props) {
   const {
@@ -4093,14 +4225,14 @@ function DateInput(props) {
     onChange,
     type,
     value,
-    disabled,
+    readOnly,
     ...rest
   } = props;
   const {
     dateFormat
   } = parseOptions(type.options);
   const handleChange = React.useCallback(nextDate => {
-    onChange(nextDate);
+    onChange(nextDate || null);
   }, [onChange]);
   const formatInputValue = React.useCallback(date => legacyDateFormat.format(date, dateFormat), [dateFormat]);
   const parseInputValue = React.useCallback(inputValue => legacyDateFormat.parse(inputValue, dateFormat), [dateFormat]);
@@ -4111,7 +4243,7 @@ function DateInput(props) {
     formatInputValue,
     onChange: handleChange,
     parseInputValue,
-    readOnly: disabled,
+    readOnly,
     selectTime: false,
     serialize,
     value
@@ -4255,7 +4387,7 @@ function CustomRule(_ref8) {
     return initialValue ? rrule.rrulestr(initialValue) : new rrule.RRule();
   }, [initialValue]);
   const [frequency, setFrequency] = React.useState(initialRule.origOptions.freq || 1);
-  const [interval, setInterval] = React.useState(initialRule.origOptions.interval || 1);
+  const [interval, setInterval] = React.useState(initialRule.origOptions.interval && initialRule.origOptions.interval > 0 ? initialRule.origOptions.interval : 1);
   const [count, setCount] = React.useState(initialRule.origOptions.count || null);
   const [until, setUntil] = React.useState(initialRule.origOptions.until || null);
   const [byweekday, setByweekday] = React.useState(initialRule.origOptions.byweekday || null);
@@ -4267,7 +4399,7 @@ function CustomRule(_ref8) {
     if (name === "freq") {
       setFrequency(Number(value));
     } else if (name === "interval") {
-      setInterval(Number(value));
+      setInterval(Number(value) > 1 ? Number(value) : 1);
     } else if (name === "count") {
       setCount(Number(value));
     }
@@ -4283,11 +4415,12 @@ function CustomRule(_ref8) {
     } else if (frequency === rrule.RRule.DAILY) {
       fromDate.setDate(fromDate.getDate() + DEFAULT_COUNTS[frequency]);
     }
+    fromDate.setHours(23, 59, 59, 999);
     return fromDate;
   }, [frequency, startDate]);
   const handleUntilChange = React.useCallback(date => {
     if (date) {
-      setUntil(new Date(date));
+      setUntil(dateFnsTz.toDate(`${date}T23:59:59`));
     }
   }, []);
   const handleEndChange = React.useCallback(event => {
@@ -4318,6 +4451,7 @@ function CustomRule(_ref8) {
     onClose();
     onChange(sanity.set(newRule.toString(), ["rrule"]));
   }, [byweekday, count, frequency, interval, onChange, onClose, until]);
+  const formatUntilValue = React.useCallback(date => dateFnsTz.format(date, "yyyy-MM-dd"), []);
   return open ? /* @__PURE__ */jsxRuntime.jsx(ui.Dialog, {
     header: "Custom recurrence",
     id: "dialog-example",
@@ -4347,6 +4481,7 @@ function CustomRule(_ref8) {
               children: /* @__PURE__ */jsxRuntime.jsx(ui.TextInput, {
                 name: "interval",
                 type: "number",
+                min: 1,
                 value: interval,
                 onChange: handleChange
               })
@@ -4357,16 +4492,16 @@ function CustomRule(_ref8) {
                 onChange: handleChange,
                 children: [/* @__PURE__ */jsxRuntime.jsx("option", {
                   value: rrule.RRule.YEARLY,
-                  children: "years"
+                  children: "year(s)"
                 }), /* @__PURE__ */jsxRuntime.jsx("option", {
                   value: rrule.RRule.MONTHLY,
-                  children: "months"
+                  children: "month(s)"
                 }), /* @__PURE__ */jsxRuntime.jsx("option", {
                   value: rrule.RRule.WEEKLY,
-                  children: "weeks"
+                  children: "week(s)"
                 }), /* @__PURE__ */jsxRuntime.jsx("option", {
                   value: rrule.RRule.DAILY,
-                  children: "days"
+                  children: "day(s)"
                 })]
               })
             })]
@@ -4423,8 +4558,8 @@ function CustomRule(_ref8) {
                     title: "Date",
                     options: dateTimeOptions
                   },
-                  value: until ? new Date(until) : getUntilDate(),
-                  disabled: !until
+                  value: until ? formatUntilValue(new Date(until)) : formatUntilValue(getUntilDate()),
+                  readOnly: !until
                 })
               })]
             }), /* @__PURE__ */jsxRuntime.jsxs(ui.Flex, {
@@ -4458,7 +4593,7 @@ function CustomRule(_ref8) {
                 style: {
                   whiteSpace: "nowrap"
                 },
-                children: "occurrences"
+                children: "occurrence(s)"
               })]
             })]
           })]
@@ -4667,6 +4802,7 @@ function RecurringDates(props) {
           return null;
         }
         const rule = rrule.rrulestr(recurrence);
+        rule.options.until = rule?.options?.until && rrule.datetime(rule?.options?.until?.getFullYear(), rule?.options?.until?.getMonth() + 1, rule?.options?.until?.getDate(), rule?.options?.until?.getHours(), rule?.options?.until?.getMinutes(), rule?.options?.until?.getSeconds());
         return /* @__PURE__ */jsxRuntime.jsx("option", {
           value: recurrence,
           children: lodash.upperFirst(rule.toText())
@@ -4705,6 +4841,9 @@ function RecurringDatesPreview(props) {
     ...options
   };
   const rule = rrule$1 && rrule.rrulestr(rrule$1);
+  if (rule) {
+    rule.options.until = rule?.options?.until && rrule.datetime(rule?.options?.until?.getFullYear(), rule?.options?.until?.getMonth() + 1, rule?.options?.until?.getDate(), rule?.options?.until?.getHours(), rule?.options?.until?.getMinutes(), rule?.options?.until?.getSeconds());
+  }
   const dateFormat = dateTimeOptions?.dateFormat || legacyDateFormat.DEFAULT_DATE_FORMAT;
   const timeFormat = dateTimeOptions?.timeFormat || legacyDateFormat.DEFAULT_TIME_FORMAT;
   const start = startDate ? new Date(startDate) : void 0;