@formkit/tempo 0.1.2 → 1.1.0

package/dist/bundle.d.ts

@@ -2,10 +2,18 @@
  * The date format used as an input value. Either a date or an ISO8601 string.
  */
 type DateInput = Date | string;
+/**
+ * The date format used as a maybe input value. Either a date, ISO8601 string or null for current time
+ */
+type MaybeDateInput = DateInput | null;
 /**
  * Format parts with text names use these descriptors:
  */
 type NamedFormatOption = "long" | "short" | "narrow";
+/**
+ * Extended part types that include custom tokens not in Intl.DateTimeFormatPartTypes.
+ */
+type ExtendedPartTypes = Intl.DateTimeFormatPartTypes | "fractionalSecond";
 /**
  * A registry of named format parts. Each type of part has every option.
  */
@@ -28,11 +36,11 @@ interface Part {
     option: FormatPattern[1];
     /**
      * The name of the part, these must be valid parts of a date format as
-     * specified in Intl.DateTimeFormatPartTypes. Valid values are:
-     * day, dayPeriod, era, hour, literal, minute, month, second, timeZoneName,
-     * weekday, year
+     * specified in Intl.DateTimeFormatPartTypes, plus custom extensions.
+     * Valid values are: day, dayPeriod, era, hour, literal, minute, month,
+     * second, timeZoneName, weekday, year, fractionalSecond
      */
-    partName: Intl.DateTimeFormatPartTypes;
+    partName: ExtendedPartTypes;
     /**
      * The value of a given part. For example "2-digit", or "narrow".
      */
@@ -61,7 +69,7 @@ type FilledPart = Part & {
  */
 type FormatPattern = [
     pattern: FormatToken | string,
-    option: Partial<Record<Intl.DateTimeFormatPartTypes, string>>,
+    option: Partial<Record<ExtendedPartTypes, string>>,
     exp?: RegExp
 ];
 /**
@@ -83,7 +91,7 @@ type Format = FormatStyle | FormatStyleObj | (string & {});
 /**
  * A union of all available formatting tokens.
  */
-type FormatToken = "YYYY" | "YY" | "MMMM" | "MMM" | "MM" | "M" | "DD" | "D" | "dddd" | "ddd" | "d" | "mm" | "m" | "ss" | "s" | "HH" | "H" | "hh" | "h" | "a" | "A" | "ZZ" | "Z";
+type FormatToken = "YYYY" | "YY" | "MMMM" | "MMM" | "MM" | "M" | "DD" | "D" | "dddd" | "ddd" | "d" | "mm" | "m" | "ss" | "s" | "SSS" | "HH" | "H" | "hh" | "h" | "a" | "A" | "ZZ" | "Z";
 interface ParseOptions {
     /**
      * A string representing a date.
@@ -139,50 +147,83 @@ interface FormatOptions {
      */
     partFilter?: (part: Part) => boolean;
 }
+interface Duration {
+    years?: number;
+    months?: number;
+    weeks?: number;
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+    milliseconds?: number;
+}
+interface DurationObj extends Duration {
+    microseconds?: number;
+    nanoseconds?: number;
+}
+
+/**
+ * Returns a new Date object with the duration applied.
+ * @param [inputDate] - A date to increment or null to increment from the current time.
+ * @param duration - An object with values for the amount of time to add to the original date.
+ * @param [dateOverflow] - Whether to allow month/year changes to overflow into a later month.
+ */
+declare function add(inputDate: MaybeDateInput, duration: Duration, dateOverflow?: boolean): Date;
 
 /**
  * Returns a new date object 1/n days after the original one.
- * @param inputDate - A date to increment by 1 day.
+ * @param [inputDate] - A date to increment or null to increment from the current time.
+ * @param [count] - The quantity to add.
  */
-declare function addDay(inputDate: DateInput, count?: number): Date;
+declare function addDay(inputDate?: MaybeDateInput, count?: number): Date;
 
 /**
  * Returns a new date object 1/n months after the original one. Keep in mind if you
  * start with a date late in a given month you could get a date after the next
  * month.
- * @param inputDate - A date to increment by 1 or more months.
- * @param count - The quantity to add.
- * @param dateOverflow - Whether or not to allow the date to overflow to another month if the inputDate’s month is out of range of the new month.
+ * @param [inputDate] - A date to increment or null to increment from the current time
+ * @param [count] - The quantity to add.
+ * @param [dateOverflow] - Whether or not to allow the date to overflow to another month if the inputDate’s month is out of range of the new month.
  */
-declare function addMonth(inputDate: DateInput, count?: number, dateOverflow?: boolean): Date;
+declare function addMonth(inputDate?: MaybeDateInput, count?: number, dateOverflow?: boolean): Date;
 
 /**
  * Returns a new date object 1/n years after the original one. Keep in mind if
  * you start with a date late in a given month you could get a date after the
  * next month.
- * @param inputDate - A date to increment by 1 day.
- * @param count - The quantity of years add.
- * @param dateOverflow - Whether or not to allow the date to overflow to another month if the inputDate’s month is out of range of the new month.
+ * @param [inputDate] - A date to increment or null to increment from the current time.
+ * @param [count] - The quantity of years add.
+ * @param [dateOverflow] - Whether or not to allow the date to overflow to another month if the inputDate’s month is out of range of the new month.
  */
-declare function addYear(inputDate: DateInput, count?: number, dateOverflow?: boolean): Date;
+declare function addYear(inputDate?: MaybeDateInput, count?: number, dateOverflow?: boolean): Date;
 
 /**
  * Returns a new date object 1/n hours after the original one.
- * @param inputDate - A date to increment by 1 day.
+ * @param [inputDate] - A date to increment or null to increment from the current time.
+ * @param [count] - The quantity to add.
  */
-declare function addHour(inputDate: DateInput, count?: number): Date;
+declare function addHour(inputDate?: MaybeDateInput, count?: number): Date;
 
 /**
- * Returns a new date object 1/n seconds after the original one.
- * @param inputDate - A date to increment by 1 day.
+ * Returns a new date object 1/n minutes after the original one.
+ * @param [inputDate] - A date to increment or null to increment from the current time.
+ * @param [count] - The quantity to add.
  */
-declare function addMinute(inputDate: DateInput, count?: number): Date;
+declare function addMinute(inputDate?: MaybeDateInput, count?: number): Date;
 
 /**
  * Returns a new date object 1/n seconds after the original one.
- * @param inputDate - A date to increment by 1 day.
+ * @param [inputDate] - A date to increment or null to increment from the current time.
+ * @param [count] - The quantity to add.
+ */
+declare function addSecond(inputDate?: MaybeDateInput, count?: number): Date;
+
+/**
+ * Returns a new date object 1/n milliseconds after the original one.
+ * @param [inputDate] - A date to increment or null to increment from the current time.
+ * @param [count] - The quantity to add.
  */
-declare function addSecond(inputDate: DateInput, count?: number): Date;
+declare function addMillisecond(inputDate?: MaybeDateInput, count?: number): Date;
 
 /**
  * Determines the correct value for am/pm by locale and memoizes it.
@@ -193,17 +234,17 @@ declare function ap(ampm: "am" | "pm", locale: string): string;
 
 /**
  * Apply a given offset to a date, returning a new date with the offset
- * applied by adding or subtracting the given number of minutes.
- * @param dateInput - The date to apply the offset to.
- * @param offset - The offset to apply in the +-HHmm or +-HH:mm format.
+ * applied by adding or subtracting the given number of seconds.
+ * @param [dateInput] - The date to apply the offset to. (default: current time)
+ * @param [offset] - The offset to apply in the +-HHmm, +-HH:mm, +-HHmmss, or +-HH:mm:ss format.
  */
-declare function applyOffset(dateInput: DateInput, offset?: string): Date;
+declare function applyOffset(dateInput?: MaybeDateInput, offset?: string): Date;
 
 /**
  * A date to parse.
  * @param date - A Date object or an ISO 8601 date.
  */
-declare function date(date?: DateInput): Date;
+declare function date(date?: MaybeDateInput): Date;
 
 /**
  * Creates a date object for the input date at the given timezone. For example
@@ -212,29 +253,31 @@ declare function date(date?: DateInput): Date;
  *
  * If given a Date object it will use local time and convert it to the given
  * timezone, thus "changing" the date.
- * @param inputDate - An iso8601 date string with no timezone
+ *
+ * if given no string or date object, it'll use the current locale time and convert to the given timezone
+ * @param [inputDate] - An iso8601 date string with no timezone
  * @param tz - A timezone string
  */
-declare function tzDate(inputDate: DateInput, tz: string): Date;
+declare function tzDate(inputDate: MaybeDateInput, tz: string): Date;
 
 /**
  * Gets the what day of the year a given date is. For example, August 1st is
  * the 213th day of the year on non- years and 214th on leap years.
- * @param inputDate - The input date.
+ * @param [inputDate] - The input date or nothing for the current day.
  */
-declare function dayOfYear(inputDate: DateInput): number;
+declare function dayOfYear(inputDate?: MaybeDateInput): number;
 
 /**
  * Returns a Date object for end of the given day.
- * @param inputDate - A string or Date object
+ * @param [inputDate] - A string, Date object or nothing for the current day
  */
-declare function dayEnd(inputDate: DateInput): Date;
+declare function dayEnd(inputDate?: MaybeDateInput): Date;
 
 /**
  * Returns a Date object for start of the given day.
- * @param inputDate - A string or Date object
+ * @param [inputDate] - A string, Date object or nothing for the current day
  */
-declare function dayStart(inputDate: DateInput): Date;
+declare function dayStart(inputDate?: MaybeDateInput): Date;
 
 /**
  * Produce a formatted string. Available strings:
@@ -290,15 +333,15 @@ declare function fourDigitYear(value: string): number;
 
 /**
  * Returns a Date object for end of the given hour.
- * @param inputDate - A string or Date object
+ * @param [inputDate] - A string, Date object or nothing for the current time
  */
-declare function hourEnd(inputDate: DateInput): Date;
+declare function hourEnd(inputDate?: MaybeDateInput): Date;
 
 /**
  * Returns a Date object for start of the given hour.
- * @param inputDate - A string or Date object
+ * @param [inputDate] - A string, Date object or nothing for the current time
  */
-declare function hourStart(inputDate: DateInput): Date;
+declare function hourStart(inputDate?: MaybeDateInput): Date;
 
 /**
  * True when the date string is valid ISO 8601.
@@ -308,43 +351,43 @@ declare function iso8601(date: string): boolean;
 
 /**
  * Returns a Date object for end of the given minute.
- * @param inputDate - A string or Date object
+ * @param [inputDate] - A string, Date object or nothing for the current time
  */
-declare function minuteEnd(inputDate: DateInput): Date;
+declare function minuteEnd(inputDate?: MaybeDateInput): Date;
 
 /**
  * Returns a Date object for start of the given minute.
- * @param inputDate - A string or Date object
+ * @param [inputDate] - A string, Date object or nothing for the current time
  */
-declare function minuteStart(inputDate: DateInput): Date;
+declare function minuteStart(inputDate?: MaybeDateInput): Date;
 
 /**
  * Returns the total number of days from a given month.
- * @param inputDate - A string or Date object
+ * @param [inputDate] - A string, Date object or nothing for the current month
  */
-declare function monthDays(inputDate: DateInput): number;
+declare function monthDays(inputDate?: MaybeDateInput): number;
 
 /**
  * Returns a Date object for the with the input date set to the last day of
  * the current month. Does not change the time.
- * @param inputDate - A string or Date object
+ * @param [inputDate] - A string, Date object or nothing for the current month
  */
-declare function monthEnd(inputDate: DateInput): Date;
+declare function monthEnd(inputDate?: MaybeDateInput): Date;
 
 /**
  * Returns a Date object for the first day of a month.
- * @param inputDate - A string or Date object
+ * @param [inputDate] - A string, Date object or nothing for the current time
  */
-declare function monthStart(inputDate: DateInput): Date;
+declare function monthStart(inputDate?: MaybeDateInput): Date;
 
 /**
  * Performs a bidirectional search for the nearest date that passes a function.
- * @param target - Performs a search for the nearest passing date.
+ * @param [inputDate] - Performs a search for the nearest passing date.
  * @param search - The search function to use, given a date returns a boolean.
  * @param constraint - The number of iterations to perform before giving up, or logical constraint like "month", or "week".
  *
  */
-declare function nearestDay(inputDate: DateInput, search: (date: Date) => boolean, constraint?: number | "month" | "week" | "year"): Date | null;
+declare function nearestDay(inputDate: MaybeDateInput, search: (date: Date) => boolean, constraint?: number | "month" | "week" | "year"): Date | null;
 
 /**
  * Timezone tokens.
@@ -359,11 +402,11 @@ type TimezoneToken = (typeof timeZoneTokens)[number];
  * Returns the offset between two timezones on a given date. The results are
  * ISO8601 compatible offsets like -0800 or +0530.
  *
- * @param dateInput - The date on which to determine the offset.
- * @param tzA - (default: UTC) The second timezone to compare determine the offset between.
- * @param tzB - (default: device) The first timezone to compare determine the offset between.
+ * @param [dateInput] - (default: current time) The date on which to determine the offset
+ * @param [tzA] - (default: UTC) The second timezone to compare determine the offset between.
+ * @param [tzB] - (default: device) The first timezone to compare determine the offset between.
  */
-declare function offset(utcTime: DateInput, tzA?: string, tzB?: string, timeZoneToken?: TimezoneToken): string;
+declare function offset(utcTime?: MaybeDateInput, tzA?: string, tzB?: string, timeZoneToken?: TimezoneToken): string;
 
 declare function parse(options: ParseOptions): Date | never;
 declare function parse(dateStr: string, format?: Format, locale?: string): Date | never;
@@ -393,177 +436,384 @@ declare function range(token: FormatToken, locale?: string, genitive?: boolean):
 
 /**
  * Inverts the offset and applies it to the given date, returning a new date.
- * @param dateInput - The date to remove the offset from.
- * @param offset - The offset to remove in the +-HHmm or +-HH:mm format.
+ * @param [dateInput] - The date to remove the offset from. (default: current time)
+ * @param [offset] - The offset to remove in the +-HHmm or +-HH:mm format.
  */
-declare function removeOffset(dateInput: DateInput, offset?: string): Date;
+declare function removeOffset(dateInput?: MaybeDateInput, offset?: string): Date;
 
 /**
  * Checks if two date objects refer to the same date. Ignores time.
  * @param inputDateA - First date to compare
+ * @param [inputDateB] - Second date to compare or the current time if nothing given
+ */
+declare function sameDay(inputDateA: DateInput, inputDateB?: MaybeDateInput): boolean;
+/**
+ * Checks if two date objects refer to the same date. Ignores time.
+ * @param [inputDateA] - First date to compare or the current time if null given
  * @param inputDateB - Second date to compare
  */
-declare function sameDay(inputDateA: DateInput, inputDateB: DateInput): boolean;
+declare function sameDay(inputDateA: MaybeDateInput, inputDateB: DateInput): boolean;
 
 /**
  * Checks if two date objects refer to the same time seconds. Ignores date.
  * @param inputDateA - First date to compare
+ * @param [inputDateB] - Second date to compare or the current time if nothing given
+ */
+declare function sameSecond(inputDateA: DateInput, inputDateB?: MaybeDateInput): boolean;
+/**
+ * Checks if two date objects refer to the same time seconds. Ignores date.
+ * @param [inputDateA] - First date to compare or the current time if null given
+ * @param inputDateB - Second date to compare
+ */
+declare function sameSecond(inputDateA: MaybeDateInput, inputDateB: DateInput): boolean;
+
+/**
+ * Checks if two date objects refer to the same millisecond. Ignores date.
+ * @param inputDateA - First date to compare
+ * @param [inputDateB] - Second date to compare or the current time if nothing given
+ */
+declare function sameMillisecond(inputDateA: DateInput, inputDateB?: MaybeDateInput): boolean;
+/**
+ * Checks if two date objects refer to the same millisecond. Ignores date.
+ * @param [inputDateA] - First date to compare or the current time if null given
  * @param inputDateB - Second date to compare
  */
-declare function sameSecond(inputDateA: DateInput, inputDateB: DateInput): boolean;
+declare function sameMillisecond(inputDateA: MaybeDateInput, inputDateB: DateInput): boolean;
 
 /**
  * Checks if two date objects refer to the same time minutes. Ignores date.
  * @param inputDateA - First date to compare
+ * @param [inputDateB] - Second date to compare or the current time if nothing given
+ */
+declare function sameMinute(inputDateA: DateInput, inputDateB?: MaybeDateInput): boolean;
+/**
+ * Checks if two date objects refer to the same time minutes. Ignores date.
+ * @param [inputDateA] - First date to compare or the current time if null given
  * @param inputDateB - Second date to compare
  */
-declare function sameMinute(inputDateA: DateInput, inputDateB: DateInput): boolean;
+declare function sameMinute(inputDateA: MaybeDateInput, inputDateB: DateInput): boolean;
 
 /**
  * Checks if two date objects refer to the same time hour. Ignores date.
  * @param inputDateA - First date to compare
+ * @param [inputDateB] - Second date to compare or the current time if nothing given
+ */
+declare function sameHour(inputDateA: DateInput, inputDateB?: MaybeDateInput): boolean;
+/**
+ * Checks if two date objects refer to the same time hour. Ignores date.
+ * @param [inputDateA] - First date to compare or the current time if null given
  * @param inputDateB - Second date to compare
  */
-declare function sameHour(inputDateA: DateInput, inputDateB: DateInput): boolean;
+declare function sameHour(inputDateA: MaybeDateInput, inputDateB: DateInput): boolean;
 
 /**
  * Checks if two date objects refer to the same year.
  * @param inputDateA - First date to compare
+ * @param [inputDateB] - Second date to compare or the current time if null given
+ */
+declare function sameYear(inputDateA: DateInput, inputDateB?: MaybeDateInput): boolean;
+/**
+ * Checks if two date objects refer to the same year.
+ * @param [inputDateA] - First date to compare or the current time if null given
  * @param inputDateB - Second date to compare
  */
-declare function sameYear(inputDateA: DateInput, inputDateB: DateInput): boolean;
+declare function sameYear(inputDateA: MaybeDateInput, inputDateB: DateInput): boolean;
+
+/**
+ * set the millisecond of a date object
+ * @param [inputDate] - a date or null for current time
+ * @param ms - the milliseconds you want the date set to (0 - 999) (can over/underflow)
+ */
+declare function setMilliseconds(inputDate: MaybeDateInput, ms: number): Date;
+
+/**
+ * set the second of a date object
+ * @param [inputDate] - a date or null for current time
+ * @param second - the second you want the date set to (0 - 59) (can over/underflow)
+ */
+declare function setSeconds(inputDate: MaybeDateInput, second: number): Date;
+
+/**
+ * set the minute of a date object
+ * @param [inputDate] - a date or null for current time
+ * @param minute - the minute you want the date set to (0 - 59) (can over/underflow)
+ */
+declare function setMinutes(inputDate: MaybeDateInput, minute: number): Date;
+
+/**
+ * set the hour of a date object
+ * @param [inputDate] - a date or null for current time
+ * @param hour - the hour you want the date set to (0 - 23) (can over/underflow)
+ */
+declare function setHour(inputDate: MaybeDateInput, hour: number): Date;
+
+/**
+ * set the day of the month in a date object
+ * @param [inputDate] - a date or null for current time
+ * @param day - the day of the month you want the date set to (1-28/29/30/31) (can over/underflow)
+ * @param [dateOverflow] - Whether or not to allow the date to overflow to another month if the given day isn't in the current month
+ */
+declare function setDayOfMonth(inputDate: MaybeDateInput, day: number, dateOverflow?: boolean): Date;
+
+/**
+ * set the month of a date
+ * @param [inputDate] - a date or null for current time
+ * @param month - the zero-based month to set (0-11, where 0 is January) (can over/underflow)
+ * @param [dateOverflow] - Whether or not to allow the date to overflow to another month if the inputDate’s month is out of range of the new month.
+ */
+declare function setMonth(inputDate: MaybeDateInput, month: number, dateOverflow?: boolean): Date;
+
+/**
+ * set the year of a date object
+ * @param inputDate - a date or null for current time
+ * @param year - the full year you want the date to be set to
+ * @param [dateOverflow] - Whether or not to allow the date to overflow to another month if the inputDate’s month is out of range of the new month.
+ */
+declare function setYear(inputDate: MaybeDateInput, year: number, dateOverflow?: boolean): Date;
 
 /**
  * Returns a Date object for the last day at the last second of the given week.
  * Defaults to Sunday as the first day of the week:
  * 0 = Sunday ... 6 = Saturday
- * @param inputDate - Gets the last day of the week
- * @param startOfWeekDay - The first day of the week
+ * @param [inputDate] - Gets the last day of the week
+ * @param [startOfWeekDay] - The first day of the week
  */
-declare function weekEnd(inputDate: DateInput, startOfWeekDay?: number): Date;
+declare function weekEnd(inputDate?: MaybeDateInput, startOfWeekDay?: number): Date;
 
 /**
  * Returns a Date object for start of the given week. Defaults to Sunday as the
  * first day of the week:
  * 0 = Sunday ... 6 = Saturday
- * @param inputDate - A string or Date object
- * @param startOfWeekDay - Determines which day of the week is the first
+ * @param [inputDate] - A string, Date object or nothing for current week
+ * @param [startOfWeekDay] - Determines which day of the week is the first
  */
-declare function weekStart(inputDate: DateInput, startOfWeekDay?: number): Date;
+declare function weekStart(inputDate?: MaybeDateInput, startOfWeekDay?: number): Date;
 
 /**
  * Get the number of days in the given date’s year.
- * @param inputDate - A string or Date object
+ * @param [inputDate] -  A string, Date object or nothing for the current year
  */
-declare function yearDays(inputDate: DateInput): number;
+declare function yearDays(inputDate?: MaybeDateInput): number;
 
 /**
  * Returns a Date object for the with the input date set to the start of the current year.
- * @param inputDate - A string or Date object
+ * @param [inputDate] - A string, Date object or nothing for the current year
  */
-declare function yearStart(inputDate: DateInput): Date;
+declare function yearStart(inputDate?: MaybeDateInput): Date;
 
 /**
  * Returns a Date object for the with the input date set to the end of the current year.
- * @param inputDate - A string or Date object
+ * @param [inputDate] - A string, Date object or nothing for the current year
  */
-declare function yearEnd(inputDate: DateInput): Date;
+declare function yearEnd(inputDate?: MaybeDateInput): Date;
 
 /**
- * Is the first date before the second one?
+ * Is the first date before the second one or the current time?
  *
  * @param inputDate - The date that should be before the other one to return true
- * @param dateToCompare - The date to compare with
+ * @param [dateToCompare] - The date to compare with or the current time if nothing given
  *
- * @returns The first date is before the second date.
+ * @returns The first date is before the second date or the current time.
  */
-declare function isBefore(inputDate: DateInput, dateToCompare: DateInput): boolean;
+declare function isBefore(inputDate: DateInput, dateToCompare?: MaybeDateInput): boolean;
 
 /**
  * @name isAfter
  * @category Common Helpers
- * @summary Is the first date after the second one?
+ * @summary Is the first date after the second one or the current time?
  *
  * @description
- * Is the first date after the second one?
+ * Is the first date after the second one or the current time?
  *
  * @param inputDate - The date that should be after the other one to return true
- * @param dateToCompare - The date to compare with
+ * @param [dateToCompare] - The date to compare with or the current time if nothing given
  *
- * @returns The first date is after the second date.
+ * @returns The first date is after the second date or the current time.
  */
-declare function isAfter(inputDate: DateInput, dateToCompare: DateInput): boolean;
+declare function isAfter(inputDate: DateInput, dateToCompare?: MaybeDateInput): boolean;
 
 /**
- * Are the given dates equal?
+ * Are the given dates equal or given date to the current time?
  *
  * @param dateLeft - The first date to compare
+ * @param [dateRight] - The second date to compare or the current time of nothing given
+ *
+ * @returns The dates are equal or date to the current time
+ */
+declare function isEqual(dateLeft: DateInput, dateRight?: MaybeDateInput): boolean;
+/**
+ * Are the given dates equal or given date to the current time?
+ *
+ * @param [dateLeft] - The first date to compare or the current time if null given
  * @param dateRight - The second date to compare
  *
- * @returns The dates are equal.
+ * @returns The dates are equal or date to the current time
+ */
+declare function isEqual(dateLeft: MaybeDateInput, dateRight: DateInput): boolean;
+
+/**
+ * is the date in the past compared to the current time
+ * @param inputDate - The date that should be in the past
+ * @returns the given date is in the past compared to the current time
+ */
+declare function isPast(inputDate: DateInput): boolean;
+
+/**
+ * is the date in the future compared to the current time
+ * @param inputDate - The date that should be in the future
+ * @returns the given date is in the future compared to the current time
  */
-declare function isEqual(dateLeft: DateInput, dateRight: DateInput): boolean;
+declare function isFuture(inputDate: DateInput): boolean;
 
 /**
  * Returns the difference between 2 dates in milliseconds.
- * @param dateA A date to compare with the right date
- * @param dateB A date to compare with the left date
+ * @param dateA - A date to compare with the right date
+ * @param [dateB] - A date to compare with the left date or nothing to compare with the current time
  */
-declare function diffMilliseconds(dateA: DateInput, dateB: DateInput): number;
+declare function diffMilliseconds(dateA: DateInput, dateB?: MaybeDateInput): number;
+/**
+ * Returns the difference between 2 dates in milliseconds.
+ * @param [dateA] - A date to compare with the right date or null to compare with the current time
+ * @param dateB - A date to compare with the left date
+ */
+declare function diffMilliseconds(dateA: MaybeDateInput, dateB: DateInput): number;
 
 type DiffRoundingMethod = "trunc" | "round" | "floor" | "ceil";
 
 /**
  * Returns the difference between 2 dates in seconds.
- * @param dateA A date to compare with the right date
- * @param dateB A date to compare with the left date
- * @param roundingMethod the rounding method to use, default: trunc
+ * @param dateA - A date to compare with the right date
+ * @param [dateB] - A date to compare with the left date or nothing to compare with the current time.
+ * @param [roundingMethod] - the rounding method to use, default: trunc
  */
-declare function diffSeconds(dateA: DateInput, dateB: DateInput, roundingMethod?: DiffRoundingMethod): number;
+declare function diffSeconds(dateA: DateInput, dateB?: MaybeDateInput, roundingMethod?: DiffRoundingMethod): number;
+/**
+ * Returns the difference between 2 dates in seconds.
+ * @param [dateA] - A date to compare with the right date or null to compare with the current time
+ * @param dateB - A date to compare with the left date
+ * @param [roundingMethod] - the rounding method to use, default: trunc
+ */
+declare function diffSeconds(dateA: MaybeDateInput, dateB: DateInput, roundingMethod?: DiffRoundingMethod): number;
 
 /**
  * Returns the difference between 2 dates in minutes.
- * @param dateA A date to compare with the right date
- * @param roundingMethod the rounding method to use, default: trunc
+ * @param dateA - A date to compare with the right date
+ * @param [dateB] - A Date to compare with the left date or nothing to compare with the current time
+ * @param [roundingMethod] the rounding method to use, default: trunc
+ */
+declare function diffMinutes(dateA: DateInput, dateB?: MaybeDateInput, roundingMethod?: DiffRoundingMethod): number;
+/**
+ * Returns the difference between 2 dates in minutes.
+ * @param [dateA] - A date to compare with the right date or null to compare with the current time
+ * @param dateB - A Date to compare with the left date
+ * @param [roundingMethod] the rounding method to use, default: trunc
  */
 declare function diffMinutes(dateA: DateInput, dateB: DateInput, roundingMethod?: DiffRoundingMethod): number;
 
 /**
  * Returns the difference between 2 dates in hours.
- * @param dateA A date to compare with the right date
- * @param dateB A date to compare with the left date
- * @param roundingMethod the rounding method to use, default: trunc
+ * @param dateA - A date to compare with the right date
+ * @param [dateB] - A date to compare with the left date or nothing to compare with the current time
+ * @param [roundingMethod] - the rounding method to use, default: trunc
+ */
+declare function diffHours(dateA: DateInput, dateB?: MaybeDateInput, roundingMethod?: DiffRoundingMethod): number;
+/**
+ * Returns the difference between 2 dates in hours.
+ * @param [dateA] - A date to compare with the right date or null to compare with the current time
+ * @param dateB - A date to compare with the left date
+ * @param [roundingMethod] - the rounding method to use, default: trunc
  */
-declare function diffHours(dateA: DateInput, dateB: DateInput, roundingMethod?: DiffRoundingMethod): number;
+declare function diffHours(dateA: MaybeDateInput, dateB: DateInput, roundingMethod?: DiffRoundingMethod): number;
 
 /**
  * Returns the difference between 2 dates in days.
- * @param dateA A date to compare with the right date
- * @param dateB A date to compare with the left date
- * @param roundingMethod the rounding method to use, default: trunc
+ * @param dateA - A date to compare with the right date
+ * @param [dateB] - A date to compare with the left date or nothing to compare with the current time
+ * @param [roundingMethod] - the rounding method to use, default: trunc
+ */
+declare function diffDays(dateA: DateInput, dateB?: MaybeDateInput, roundingMethod?: DiffRoundingMethod): number;
+/**
+ * Returns the difference between 2 dates in days.
+ * @param [dateA] - A date to compare with the right date or null to compare with the current time
+ * @param dateB - A date to compare with the left date
+ * @param [roundingMethod] - the rounding method to use, default: trunc
  */
-declare function diffDays(dateA: DateInput, dateB: DateInput, roundingMethod?: DiffRoundingMethod): number;
+declare function diffDays(dateA: MaybeDateInput, dateB: DateInput, roundingMethod?: DiffRoundingMethod): number;
 
 /**
  * Returns the difference between 2 dates in days.
- * @param dateA A date to compare with the right date
- * @param dateB A date to compare with the left date
- * @param roundingMethod the rounding method to use, default: trunc
+ * @param dateA - A date to compare with the right date
+ * @param [dateB] - A date to compare with the left date or nothing to compare with the current time
+ * @param [roundingMethod] - the rounding method to use, default: trunc
+ */
+declare function diffWeeks(dateA: DateInput, dateB: DateInput, roundingMethod?: DiffRoundingMethod): number;
+/**
+ * Returns the difference between 2 dates in days.
+ * @param [dateA] - A date to compare with the right date or null to compare with the current time
+ * @param dateB - A date to compare with the left date
+ * @param [roundingMethod] - the rounding method to use, default: trunc
  */
 declare function diffWeeks(dateA: DateInput, dateB: DateInput, roundingMethod?: DiffRoundingMethod): number;
 
 /**
  * Returns the difference between 2 dates in months.
- * @param dateA A date to compare with the dateB date
- * @param dateB A date to compare with the dateA date
+ * @param dateA - A date to compare with the dateB date
+ * @param [dateB] - A date to compare with the dateA date or nothing to compare with the current time
+ */
+declare function diffMonths(dateA: DateInput, dateB?: MaybeDateInput): number;
+/**
+ * Returns the difference between 2 dates in months.
+ * @param [dateA] - A date to compare with the dateB date or null to compare with the current time
+ * @param dateB - A date to compare with the dateA date
  */
-declare function diffMonths(dateA: DateInput, dateB: DateInput): number;
+declare function diffMonths(dateA: MaybeDateInput, dateB: DateInput): number;
 
 /**
  * Returns the difference between 2 dates in years.
- * @param dateA A date to compare with the dateB date
- * @param dateB A date to compare with the dateA date
+ * @param dateA - A date to compare with the dateB date
+ * @param [dateB] - A date to compare with the dateA date or nothing to compare with the current time
+ */
+declare function diffYears(dateA: DateInput, dateB?: MaybeDateInput): number;
+/**
+ * Returns the difference between 2 dates in years.
+ * @param [dateA] - A date to compare with the dateB date or null to compare with the current time
+ * @param dateB - A date to compare with the dateA date
+ */
+declare function diffYears(dateA: MaybeDateInput, dateB: DateInput): number;
+
+type DurationKey = keyof Duration;
+/**
+ * Options for `diff` function
+ */
+interface DiffOptions {
+    /**
+     * whether the difference should be absolute (not negative)
+     */
+    abs?: boolean;
+    /**
+     * units you want to skip, for example weeks
+     */
+    skip?: DurationKey[] | Set<DurationKey>;
+}
+/**
+ * Returns the difference between 2 dates in an object
+ * @param dateA - A date to compare with the right date
+ * @param [dateB] - A date to compare with the left date or nothing to compare with the current time
+ * @param [options] additional options
+ * @param [options.skip] units you want skip
+ * @param [options.abs] whether the difference should be absolute
+ * @returns an object which could be used with `Intl.DurationFormat.format'`
+ */
+declare function diff(dateA: DateInput, dateB?: MaybeDateInput, options?: DiffOptions): Duration;
+/**
+ * Returns the difference between 2 dates in an object
+ * @param [dateA] - A date to compare with the right date or null to compare with the current time
+ * @param dateB - A date to compare with the left date
+ * @param [options] additional options
+ * @param [options.skip] units you want skip
+ * @param [options.abs] whether the difference should be absolute
+ * @returns an object which could be used with `Intl.DurationFormat.format'`
  */
-declare function diffYears(dateA: DateInput, dateB: DateInput): number;
+declare function diff(dateA: MaybeDateInput, dateB: DateInput, options?: DiffOptions): Duration;
 
-export { type DateInput, type FilledPart, type Format, type FormatOptions, type FormatPattern, type FormatStyle, type FormatStyleObj, type FormatToken, type NamedFormatOption, type NamedFormats, type ParseOptions, type Part, addDay, addHour, addMinute, addMonth, addSecond, addYear, ap, applyOffset, date, dayEnd, dayOfYear, dayStart, diffDays, diffHours, diffMilliseconds, diffMinutes, diffMonths, diffSeconds, diffWeeks, diffYears, format, formatStr, fourDigitYear, hourEnd, hourStart, isAfter, isBefore, isEqual, iso8601, minuteEnd, minuteStart, monthDays, monthEnd, monthStart, nearestDay, offset, parse, parseParts, parts, range, removeOffset, sameDay, sameHour, sameMinute, sameSecond, sameYear, tzDate, weekEnd, weekStart, yearDays, yearEnd, yearStart };
+export { type DateInput, type DiffOptions, type Duration, type DurationObj, type ExtendedPartTypes, type FilledPart, type Format, type FormatOptions, type FormatPattern, type FormatStyle, type FormatStyleObj, type FormatToken, type MaybeDateInput, type NamedFormatOption, type NamedFormats, type ParseOptions, type Part, add, addDay, addHour, addMillisecond, addMinute, addMonth, addSecond, addYear, ap, applyOffset, date, dayEnd, dayOfYear, dayStart, diff, diffDays, diffHours, diffMilliseconds, diffMinutes, diffMonths, diffSeconds, diffWeeks, diffYears, format, formatStr, fourDigitYear, hourEnd, hourStart, isAfter, isBefore, isEqual, isFuture, isPast, iso8601, minuteEnd, minuteStart, monthDays, monthEnd, monthStart, nearestDay, offset, parse, parseParts, parts, range, removeOffset, sameDay, sameHour, sameMillisecond, sameMinute, sameSecond, sameYear, setDayOfMonth, setHour, setMilliseconds, setMinutes, setMonth, setSeconds, setYear, tzDate, weekEnd, weekStart, yearDays, yearEnd, yearStart };