@checkdigit/time 4.0.0 → 5.0.0-PR.21-7813

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

@@ -1,5 +1,15 @@
-import { toDate } from '../toDate/index';
-import { constructFrom } from '../constructFrom/index';
+/* eslint-disable eslint-comments/no-unlimited-disable */
+/* eslint-disable */
+// @ts-nocheck
+
+import { constructFrom } from '../constructFrom/index.ts';
+import { toDate } from '../toDate/index.ts';
+import type { ContextOptions, DateArg } from '../types.ts';
+
+/**
+ * The {@link addDays} function options.
+ */
+export interface AddDaysOptions<DateType extends Date = Date> extends ContextOptions<DateType> {}
 
 /**
  * @name addDays
@@ -10,9 +20,11 @@ import { constructFrom } from '../constructFrom/index';
  * Add the specified number of days 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 - 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
  *
@@ -21,13 +33,19 @@ import { constructFrom } from '../constructFrom/index';
  * const result = addDays(new Date(2014, 8, 1), 10)
  * //=> Thu Sep 11 2014 00:00:00
  */
-export function addDays<DateType extends Date>(date: DateType | number | string, amount: number): DateType {
-  const _date = toDate(date);
-  if (isNaN(amount)) return constructFrom(date, NaN);
-  if (!amount) {
-    // If 0 days, no-op to avoid changing times in the hour before end of DST
-    return _date;
-  }
+export function addDays<DateType extends Date, ResultDate extends Date = DateType>(
+  date: DateArg<DateType>,
+  amount: number,
+  options?: AddDaysOptions<ResultDate> | undefined,
+): ResultDate {
+  const _date = toDate(date, options?.in);
+  if (isNaN(amount)) return constructFrom(options?.in || 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;
 }
+
+/* eslint-enable */

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

@@ -1,5 +1,15 @@
-import { addMilliseconds } from '../addMilliseconds/index';
-import { millisecondsInHour } from '../constants/index';
+/* eslint-disable eslint-comments/no-unlimited-disable */
+/* eslint-disable */
+// @ts-nocheck
+
+import { addMilliseconds } from '../addMilliseconds/index.ts';
+import { millisecondsInHour } from '../constants/index.ts';
+import type { ContextOptions, DateArg } from '../types.ts';
+
+/**
+ * The {@link addHours} function options.
+ */
+export interface AddHoursOptions<DateType extends Date = Date> extends ContextOptions<DateType> {}
 
 /**
  * @name addHours
@@ -10,9 +20,11 @@ import { millisecondsInHour } from '../constants/index';
  * Add the specified number of hours 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 - The date to be changed
- * @param amount - The amount of hours to be added.
+ * @param amount - The amount of hours to be added
+ * @param options - An object with options
  *
  * @returns The new date with the hours added
  *
@@ -21,6 +33,12 @@ import { millisecondsInHour } from '../constants/index';
  * const result = addHours(new Date(2014, 6, 10, 23, 0), 2)
  * //=> Fri Jul 11 2014 01:00:00
  */
-export function addHours<DateType extends Date>(date: DateType | number | string, amount: number): DateType {
-  return addMilliseconds(date, amount * millisecondsInHour);
+export function addHours<DateType extends Date, ResultDate extends Date = DateType>(
+  date: DateArg<DateType>,
+  amount: number,
+  options?: AddHoursOptions<ResultDate> | undefined,
+): ResultDate {
+  return addMilliseconds(date, amount * millisecondsInHour, options);
 }
+
+/* eslint-enable */

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

@@ -1,5 +1,15 @@
-import { getISOWeekYear } from '../getISOWeekYear/index';
-import { setISOWeekYear } from '../setISOWeekYear/index';
+/* eslint-disable eslint-comments/no-unlimited-disable */
+/* eslint-disable */
+// @ts-nocheck
+
+import { getISOWeekYear } from '../getISOWeekYear/index.ts';
+import { setISOWeekYear } from '../setISOWeekYear/index.ts';
+import type { ContextOptions, DateArg } from '../types.ts';
+
+/**
+ * The {@link addISOWeekYears} function options.
+ */
+export interface AddISOWeekYearsOptions<DateType extends Date = Date> extends ContextOptions<DateType> {}
 
 /**
  * @name addISOWeekYears
@@ -15,14 +25,21 @@ import { setISOWeekYear } from '../setISOWeekYear/index';
  *
  * @param date - The date to be changed
  * @param amount - The amount of ISO week-numbering years to be added.
+ * @param options - An object with options
  *
  * @returns The new date with the ISO week-numbering years added
  *
  * @example
  * // Add 5 ISO week-numbering years to 2 July 2010:
  * const result = addISOWeekYears(new Date(2010, 6, 2), 5)
- * //=> Fri Jn 26 2015 00:00:00
+ * //=> Fri Jun 26 2015 00:00:00
  */
-export function addISOWeekYears<DateType extends Date>(date: DateType | number | string, amount: number): DateType {
-  return setISOWeekYear(date, getISOWeekYear(date) + amount);
+export function addISOWeekYears<DateType extends Date, ResultDate extends Date = DateType>(
+  date: DateArg<DateType>,
+  amount: number,
+  options?: AddISOWeekYearsOptions<ResultDate> | undefined,
+): ResultDate {
+  return setISOWeekYear(date, getISOWeekYear(date, options) + amount, options);
 }
+
+/* eslint-enable */

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

@@ -1,5 +1,14 @@
-import { toDate } from '../toDate/index';
-import { constructFrom } from '../constructFrom/index';
+/* eslint-disable eslint-comments/no-unlimited-disable */
+/* eslint-disable */
+// @ts-nocheck
+
+import { constructFrom } from '../constructFrom/index.ts';
+import { toDate } from '../toDate/index.ts';
+import type { ContextOptions, DateArg } from '../types.ts';
+/**
+ * The {@link addMilliseconds} function options.
+ */
+export interface AddMillisecondsOptions<DateType extends Date = Date> extends ContextOptions<DateType> {}
 
 /**
  * @name addMilliseconds
@@ -10,9 +19,11 @@ import { constructFrom } from '../constructFrom/index';
  * Add the specified number of milliseconds 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 - The date to be changed
  * @param amount - The amount of milliseconds to be added.
+ * @param options - The options object
  *
  * @returns The new date with the milliseconds added
  *
@@ -21,7 +32,12 @@ import { constructFrom } from '../constructFrom/index';
  * const result = addMilliseconds(new Date(2014, 6, 10, 12, 45, 30, 0), 750)
  * //=> Thu Jul 10 2014 12:45:30.750
  */
-export function addMilliseconds<DateType extends Date>(date: DateType | number | string, amount: number): DateType {
-  const timestamp = +toDate(date);
-  return constructFrom(date, timestamp + amount);
+export function addMilliseconds<DateType extends Date, ResultDate extends Date = DateType>(
+  date: DateArg<DateType>,
+  amount: number,
+  options?: AddMillisecondsOptions<ResultDate> | undefined,
+): ResultDate {
+  return constructFrom(options?.in || date, +toDate(date) + amount);
 }
+
+/* eslint-enable */

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

@@ -1,5 +1,15 @@
-import { addMilliseconds } from '../addMilliseconds/index';
-import { millisecondsInMinute } from '../constants/index';
+/* eslint-disable eslint-comments/no-unlimited-disable */
+/* eslint-disable */
+// @ts-nocheck
+
+import { millisecondsInMinute } from '../constants/index.ts';
+import { toDate } from '../toDate/index.ts';
+import type { ContextOptions, DateArg } from '../types.ts';
+
+/**
+ * The {@link addMinutes} function options.
+ */
+export interface AddMinutesOptions<DateType extends Date = Date> extends ContextOptions<DateType> {}
 
 /**
  * @name addMinutes
@@ -10,9 +20,11 @@ import { millisecondsInMinute } from '../constants/index';
  * Add the specified number of minutes 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 - The date to be changed
  * @param amount - The amount of minutes to be added.
+ * @param options - An object with options
  *
  * @returns The new date with the minutes added
  *
@@ -21,6 +33,14 @@ import { millisecondsInMinute } from '../constants/index';
  * const result = addMinutes(new Date(2014, 6, 10, 12, 0), 30)
  * //=> Thu Jul 10 2014 12:30:00
  */
-export function addMinutes<DateType extends Date>(date: DateType | number | string, amount: number): DateType {
-  return addMilliseconds(date, amount * millisecondsInMinute);
+export function addMinutes<DateType extends Date, ResultDate extends Date = DateType>(
+  date: DateArg<DateType>,
+  amount: number,
+  options?: AddMinutesOptions<ResultDate> | undefined,
+): ResultDate {
+  const _date = toDate(date, options?.in);
+  _date.setTime(_date.getTime() + amount * millisecondsInMinute);
+  return _date;
 }
+
+/* eslint-enable */

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

@@ -1,5 +1,15 @@
-import { toDate } from '../toDate/index';
-import { constructFrom } from '../constructFrom/index';
+/* eslint-disable eslint-comments/no-unlimited-disable */
+/* eslint-disable */
+// @ts-nocheck
+
+import { constructFrom } from '../constructFrom/index.ts';
+import { toDate } from '../toDate/index.ts';
+import type { ContextOptions, DateArg } from '../types.ts';
+
+/**
+ * The {@link addMonths} function options.
+ */
+export interface AddMonthsOptions<DateType extends Date = Date> extends ContextOptions<DateType> {}
 
 /**
  * @name addMonths
@@ -10,9 +20,11 @@ import { constructFrom } from '../constructFrom/index';
  * Add the specified number of months 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 - 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
  *
@@ -25,9 +37,13 @@ import { constructFrom } from '../constructFrom/index';
  * const result = addMonths(new Date(2023, 0, 30), 1)
  * //=> Tue Feb 28 2023 00:00:00
  */
-export function addMonths<DateType extends Date>(date: DateType | number | string, amount: number): DateType {
-  const _date = toDate(date);
-  if (isNaN(amount)) return constructFrom(date, NaN);
+export function addMonths<DateType extends Date, ResultDate extends Date = DateType>(
+  date: DateArg<DateType>,
+  amount: number,
+  options?: AddMonthsOptions<ResultDate> | undefined,
+): ResultDate {
+  const _date = toDate(date, options?.in);
+  if (isNaN(amount)) return constructFrom(options?.in || date, NaN);
   if (!amount) {
     // If 0 months, no-op to avoid changing times in the hour before end of DST
     return _date;
@@ -42,7 +58,7 @@ export function addMonths<DateType extends Date>(date: DateType | number | strin
   // 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.
-  const endOfDesiredMonth = constructFrom(date, _date.getTime());
+  const endOfDesiredMonth = constructFrom(options?.in || date, _date.getTime());
   endOfDesiredMonth.setMonth(_date.getMonth() + amount + 1, 0);
   const daysInMonth = endOfDesiredMonth.getDate();
   if (dayOfMonth >= daysInMonth) {
@@ -61,3 +77,5 @@ export function addMonths<DateType extends Date>(date: DateType | number | strin
     return _date;
   }
 }
+
+/* eslint-enable */

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

@@ -1,4 +1,14 @@
-import { addMonths } from '../addMonths/index';
+/* eslint-disable eslint-comments/no-unlimited-disable */
+/* eslint-disable */
+// @ts-nocheck
+
+import { addMonths } from '../addMonths/index.ts';
+import type { ContextOptions, DateArg } from '../types.ts';
+
+/**
+ * The {@link addQuarters} function options.
+ */
+export interface AddQuartersOptions<DateType extends Date = Date> extends ContextOptions<DateType> {}
 
 /**
  * @name addQuarters
@@ -9,18 +19,25 @@ import { addMonths } from '../addMonths/index';
  * Add the specified number of year quarters 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 - The date to be changed
  * @param amount - The amount of quarters to be added.
+ * @param options - An object with options
  *
  * @returns The new date with the quarters added
  *
  * @example
  * // Add 1 quarter to 1 September 2014:
  * const result = addQuarters(new Date(2014, 8, 1), 1)
- * //=> Mon Dec 01 2014 00:00:00
+ * //=; Mon Dec 01 2014 00:00:00
  */
-export function addQuarters<DateType extends Date>(date: DateType | number | string, amount: number): DateType {
-  const months = amount * 3;
-  return addMonths(date, months);
+export function addQuarters<DateType extends Date, ResultDate extends Date = DateType>(
+  date: DateArg<DateType>,
+  amount: number,
+  options?: AddQuartersOptions<ResultDate> | undefined,
+): ResultDate {
+  return addMonths(date, amount * 3, options);
 }
+
+/* eslint-enable */

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

@@ -1,4 +1,14 @@
-import { addMilliseconds } from '../addMilliseconds/index';
+/* eslint-disable eslint-comments/no-unlimited-disable */
+/* eslint-disable */
+// @ts-nocheck
+
+import { addMilliseconds } from '../addMilliseconds/index.ts';
+import type { ContextOptions, DateArg } from '../types.ts';
+
+/**
+ * The {@link addSeconds} function options.
+ */
+export interface AddSecondsOptions<DateType extends Date = Date> extends ContextOptions<DateType> {}
 
 /**
  * @name addSeconds
@@ -9,9 +19,11 @@ import { addMilliseconds } from '../addMilliseconds/index';
  * Add the specified number of seconds 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 - The date to be changed
  * @param amount - The amount of seconds to be added.
+ * @param options - An object with options
  *
  * @returns The new date with the seconds added
  *
@@ -20,6 +32,12 @@ import { addMilliseconds } from '../addMilliseconds/index';
  * const result = addSeconds(new Date(2014, 6, 10, 12, 45, 0), 30)
  * //=> Thu Jul 10 2014 12:45:30
  */
-export function addSeconds<DateType extends Date>(date: DateType | number | string, amount: number): DateType {
-  return addMilliseconds(date, amount * 1000);
+export function addSeconds<DateType extends Date, ResultDate extends Date = DateType>(
+  date: DateArg<DateType>,
+  amount: number,
+  options?: AddSecondsOptions<ResultDate> | undefined,
+): ResultDate {
+  return addMilliseconds(date, amount * 1000, options);
 }
+
+/* eslint-enable */

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

@@ -1,4 +1,14 @@
-import { addDays } from '../addDays/index';
+/* eslint-disable eslint-comments/no-unlimited-disable */
+/* eslint-disable */
+// @ts-nocheck
+
+import { addDays } from '../addDays/index.ts';
+import type { ContextOptions, DateArg } from '../types.ts';
+
+/**
+ * The {@link addWeeks} function options.
+ */
+export interface AddWeeksOptions<DateType extends Date = Date> extends ContextOptions<DateType> {}
 
 /**
  * @name addWeeks
@@ -6,12 +16,14 @@ import { addDays } from '../addDays/index';
  * @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 - 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
  *
@@ -20,7 +32,12 @@ import { addDays } from '../addDays/index';
  * const result = addWeeks(new Date(2014, 8, 1), 4)
  * //=> Mon Sep 29 2014 00:00:00
  */
-export function addWeeks<DateType extends Date>(date: DateType | number | string, amount: number): DateType {
-  const days = amount * 7;
-  return addDays(date, days);
+export function addWeeks<DateType extends Date, ResultDate extends Date = DateType>(
+  date: DateArg<DateType>,
+  amount: number,
+  options?: AddWeeksOptions<ResultDate> | undefined,
+): ResultDate {
+  return addDays(date, amount * 7, options);
 }
+
+/* eslint-enable */

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

@@ -1,4 +1,14 @@
-import { addMonths } from '../addMonths/index';
+/* eslint-disable eslint-comments/no-unlimited-disable */
+/* eslint-disable */
+// @ts-nocheck
+
+import { addMonths } from '../addMonths/index.ts';
+import type { ContextOptions, DateArg } from '../types.ts';
+
+/**
+ * The {@link addYears} function options.
+ */
+export interface AddYearsOptions<DateType extends Date = Date> extends ContextOptions<DateType> {}
 
 /**
  * @name addYears
@@ -9,9 +19,11 @@ import { addMonths } from '../addMonths/index';
  * Add the specified number of years 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.
  *
  * @param date - The date to be changed
  * @param amount - The amount of years to be added.
+ * @param options - The options
  *
  * @returns The new date with the years added
  *
@@ -20,6 +32,12 @@ import { addMonths } from '../addMonths/index';
  * const result = addYears(new Date(2014, 8, 1), 5)
  * //=> Sun Sep 01 2019 00:00:00
  */
-export function addYears<DateType extends Date>(date: DateType | number | string, amount: number): DateType {
-  return addMonths(date, amount * 12);
+export function addYears<DateType extends Date, ResultDate extends Date = DateType>(
+  date: DateArg<DateType>,
+  amount: number,
+  options?: AddYearsOptions<ResultDate> | undefined,
+): ResultDate {
+  return addMonths(date, amount * 12, options);
 }
+
+/* eslint-enable */

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

@@ -1,10 +1,14 @@
-import { toDate } from '../toDate/index';
-import type { Interval } from '../types';
+/* eslint-disable eslint-comments/no-unlimited-disable */
+/* eslint-disable */
+// @ts-nocheck
+
+import { toDate } from '../toDate/index.ts';
+import type { ContextOptions, Interval } from '../types.ts';
 
 /**
  * The {@link areIntervalsOverlapping} function options.
  */
-export interface AreIntervalsOverlappingOptions {
+export interface AreIntervalsOverlappingOptions extends ContextOptions<Date> {
   /** Whether the comparison is inclusive or not */
   inclusive?: boolean;
 }
@@ -51,13 +55,6 @@ export interface AreIntervalsOverlappingOptions {
  * // Using the inclusive option:
  * areIntervalsOverlapping(
  *   { start: new Date(2014, 0, 10), end: new Date(2014, 0, 20) },
- *   { start: new Date(2014, 0, 20), end: new Date(2014, 0, 24) }
- * )
- * //=> false
- *
- * @example
- * areIntervalsOverlapping(
- *   { start: new Date(2014, 0, 10), end: new Date(2014, 0, 20) },
  *   { start: new Date(2014, 0, 20), end: new Date(2014, 0, 24) },
  *   { inclusive: true }
  * )
@@ -68,12 +65,18 @@ export function areIntervalsOverlapping(
   intervalRight: Interval,
   options?: AreIntervalsOverlappingOptions,
 ): boolean {
-  const [leftStartTime, leftEndTime] = [+toDate(intervalLeft.start), +toDate(intervalLeft.end)].sort((a, b) => a - b);
-  const [rightStartTime, rightEndTime] = [+toDate(intervalRight.start), +toDate(intervalRight.end)].sort(
-    (a, b) => a - b,
-  );
+  const [leftStartTime, leftEndTime] = [
+    +toDate(intervalLeft.start, options?.in),
+    +toDate(intervalLeft.end, options?.in),
+  ].sort((a, b) => a - b);
+  const [rightStartTime, rightEndTime] = [
+    +toDate(intervalRight.start, options?.in),
+    +toDate(intervalRight.end, options?.in),
+  ].sort((a, b) => a - b);
 
-  if (options?.inclusive) return leftStartTime! <= rightEndTime! && rightStartTime! <= leftEndTime!;
+  if (options?.inclusive) return leftStartTime <= rightEndTime && rightStartTime <= leftEndTime;
 
-  return leftStartTime! < rightEndTime! && rightStartTime! < leftEndTime!;
+  return leftStartTime < rightEndTime && rightStartTime < leftEndTime;
 }
+
+/* eslint-enable */

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

@@ -1,11 +1,42 @@
-import { max } from '../max/index';
-import { min } from '../min/index';
-import type { Interval } from '../types';
+/* eslint-disable eslint-comments/no-unlimited-disable */
+/* eslint-disable */
+// @ts-nocheck
+
+import { normalizeDates } from '../_lib/normalizeDates/index.ts';
+import { max } from '../max/index.ts';
+import { min } from '../min/index.ts';
+import type { ContextOptions, DateArg, Interval } from '../types.ts';
+
+/**
+ * The {@link clamp} function options.
+ */
+export interface ClampOptions<ContextDate extends Date = Date> extends ContextOptions<ContextDate> {}
+
+/**
+ * The {@link clamp} function result type. It resolves the proper data type.
+ * It uses the first argument date object type, starting from the date argument,
+ * then the start interval date, and finally the end interval date. If
+ * a context function is passed, it uses the context function return type.
+ */
+export type ClampResult<
+  DateType extends DateArg<Date>,
+  IntervalType extends Interval,
+  Options extends ClampOptions | undefined,
+> =
+  Options extends ClampOptions<infer DateType extends Date>
+    ? DateType
+    : DateType extends Date
+      ? DateType
+      : IntervalType['start'] extends Date
+        ? IntervalType['start']
+        : IntervalType['end'] extends Date
+          ? IntervalType['end']
+          : Date;
 
 /**
  * @name clamp
  * @category Interval Helpers
- * @summary Return a date bounded by the start and the end of the given interval
+ * @summary Return a date bounded by the start and the end of the given interval.
  *
  * @description
  * Clamps a date to the lower bound with the start of the interval and the upper
@@ -15,21 +46,32 @@ import type { Interval } from '../types';
  * - When the date is greater than the end of the interval, the end is returned.
  * - Otherwise the date is returned.
  *
- * @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 DateType - Date argument type.
+ * @typeParam IntervalType - Interval argument type.
+ * @typeParam Options - Options type.
  *
  * @param date - The date to be bounded
  * @param interval - The interval to bound to
+ * @param options - An object with options
  *
  * @returns The date bounded by the start and the end of the interval
  *
  * @example
- * // What is Mar, 21, 2021 bounded to an interval starting at Mar, 22, 2021 and ending at Apr, 01, 2021
+ * // What is Mar 21, 2021 bounded to an interval starting at Mar 22, 2021 and ending at Apr 01, 2021
  * const result = clamp(new Date(2021, 2, 21), {
  *   start: new Date(2021, 2, 22),
  *   end: new Date(2021, 3, 1),
  * })
  * //=> Mon Mar 22 2021 00:00:00
  */
-export function clamp<DateType extends Date>(date: DateType | number | string, interval: Interval): DateType | Date {
-  return min([max([date, interval.start]), interval.end]);
+export function clamp<
+  DateType extends DateArg<Date>,
+  IntervalType extends Interval,
+  Options extends ClampOptions | undefined = undefined,
+>(date: DateType, interval: IntervalType, options?: Options): ClampResult<DateType, IntervalType, Options> {
+  const [date_, start, end] = normalizeDates(options?.in, date, interval.start, interval.end);
+
+  return min([max([date_, start], options), end], options) as ClampResult<DateType, IntervalType, Options>;
 }
+
+/* eslint-enable */