@trackunit/date-and-time-utils 0.0.25 → 0.0.27

package/src/DateAndTimeUtils.d.ts

@@ -1,19 +1,43 @@
+import "@formatjs/intl-durationformat/polyfill";
 import { Temporal } from "@js-temporal/polyfill";
 export type TemporalDate = Temporal.Instant | Temporal.ZonedDateTime | Date;
 type TemporalFormatTypes = Intl.DateTimeFormatOptions;
+type TemporalTimeTypes = Extract<Intl.RelativeTimeFormatUnit, "days" | "hours" | "minutes">;
 type TemporalFormatSelector = "dateOnly" | "timeOnly";
 export type TemporalFormatStyle = Intl.ListFormatStyle;
+export interface DateRange {
+    start: Date;
+    end: Date;
+}
 export interface TemporalFormat {
     selectFormat?: TemporalFormatSelector;
     dateFormat?: TemporalFormatTypes["dateStyle"];
     timeFormat?: TemporalFormatTypes["timeStyle"];
+    dayFormat?: TemporalFormatTypes["dayPeriod"];
 }
+/**
+ * converts timZoneId to TimeZone object with default to current user timezone
+ *
+ * @param timeZoneId - The time zone to use for the conversion.
+ * returns A time zone object. { id: string, offset: string, name: string }
+ */
+export declare const getTimeZone: (timeZoneId?: string) => {
+    id: string;
+    offset: string;
+    name: string;
+};
+/**
+ * get the offset count for a given timezone. Europe/Berlin would return +2:00
+ *
+ * @param timeZone - The time zone to use for the conversion.
+ */
+export declare const getTimeZoneOffset: (timeZone: string) => string;
 /**
  * Returns a list of all supported time zones.
  *
  * @returns {string[]}
  */
-export declare const timeZonesAvailable: any;
+export declare const timeZonesAvailable: string[];
 /**
  * Formats a temporal date according to the specified format, time zone, and locale.
  *
@@ -58,20 +82,19 @@ export declare const formatDateUtil: (date: TemporalDate, format?: TemporalForma
 /**
  * Formats a date range.
  *
- * @param {Date} start - The start date of the range.
- * @param {Date} end - The end date of the range.
+ * @param {DateRange} range - The start date of the range.
  * @param {string} locale - The locale identifier (e.g., 'en-US', 'fr-FR') used for formatting.
  * @param {Intl.DateTimeFormatOptions} [format] - Optional formatting options for the date and time.
  * @returns {string} A formatted string representing the date range.
  */
-export declare const formatRangeUtil: (start: Date, end: Date, locale: string, format?: TemporalFormatTypes) => string;
+export declare const formatRangeUtil: (range: DateRange, locale: string, format?: TemporalFormatTypes) => string;
 /**
  * Subtracts a specified number of minutes from a date.
  *
  * @param {TemporalDate} date - The temporal date from which to subtract minutes.
  * @param {number} amount - The number of minutes to subtract.
  * @param {string} [timeZone] - The time zone to use for the subtraction. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The resulting temporal date after subtracting the specified number of minutes.
+ * @returns {Temporal.ZonedDateTime} The resulting temporal date after subtracting the specified number of minutes.
  * @example
  * const dateString = "2023-05-10T10:30:00.000Z"
  * const date = new Date(dateString);
@@ -86,7 +109,7 @@ export declare const subtractMinutesUtil: (date: TemporalDate, amount: number, t
  * @param {TemporalDate} date - The temporal date from which to subtract hours.
  * @param {number} amount - The number of hours to subtract.
  * @param {string} [timeZone] - The time zone to use for the subtraction. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The resulting temporal date after subtracting the specified number of hours.
+ * @returns {Temporal.ZonedDateTime} The resulting temporal date after subtracting the specified number of hours.
  * @example
  * const dateString = "2023-05-10T10:30:00.000Z"
  * const date = new Date(dateString);
@@ -101,7 +124,7 @@ export declare const subtractHoursUtil: (date: TemporalDate, amount: number, tim
  * @param {TemporalDate} date - The temporal date from which to subtract days.
  * @param {number} amount - The number of days to subtract.
  * @param {string} [timeZone] - The time zone to use for the subtraction. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The resulting temporal date after subtracting the specified number of days.
+ * @returns {Temporal.ZonedDateTime} The resulting temporal date after subtracting the specified number of days.
  * @example
  * const dateString = "2023-05-10"
  * const date = new Date(dateString);
@@ -116,7 +139,7 @@ export declare const subtractDaysUtil: (date: TemporalDate, amount: number, time
  * @param {TemporalDate} date - The temporal date from which to subtract weeks.
  * @param {number} amount - The number of weeks to subtract.
  * @param {string} [timeZone] - The time zone to use for the subtraction. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The resulting temporal date after subtracting the specified number of weeks.
+ * @returns {Temporal.ZonedDateTime} The resulting temporal date after subtracting the specified number of weeks.
  * @example
  * const dateString = "2023-05-10"
  * const date = new Date(dateString);
@@ -131,7 +154,7 @@ export declare const subtractWeeksUtil: (date: TemporalDate, amount: number, tim
  * @param {TemporalDate} date - The temporal date from which to subtract months.
  * @param {number} amount - The number of months to subtract.
  * @param {string} [timeZone] - The time zone to use for the subtraction. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The resulting temporal date after subtracting the specified number of months.
+ * @returns {Temporal.ZonedDateTime} The resulting temporal date after subtracting the specified number of months.
  * @example
  * const dateString = "2023-05-10"
  * const date = new Date(dateString);
@@ -146,7 +169,7 @@ export declare const subtractMonthsUtil: (date: TemporalDate, amount: number, ti
  * @param {TemporalDate} date - The temporal date from which to subtract years.
  * @param {number} amount - The number of years to subtract.
  * @param {string} [timeZone] - The time zone to use for the subtraction. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The resulting temporal date after subtracting the specified number of years.
+ * @returns {Temporal.ZonedDateTime} The resulting temporal date after subtracting the specified number of years.
  * @example
  * const dateString = "2023-05-10"
  * const date = new Date(dateString);
@@ -161,7 +184,7 @@ export declare const subtractYearsUtil: (date: TemporalDate, amount: number, tim
  * @param {TemporalDate} date - The temporal date to which minutes will be added.
  * @param {number} amount - The number of minutes to add.
  * @param {string} [timeZone] - The time zone to use for the addition. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The resulting temporal date after adding the specified number of minutes.
+ * @returns {Temporal.ZonedDateTime} The resulting temporal date after adding the specified number of minutes.
  * @example
  * const dateString = "2023-05-10"
  * const date = new Date(dateString);
@@ -176,7 +199,7 @@ export declare const addMinutesUtil: (date: TemporalDate, amount: number, timeZo
  * @param {TemporalDate} date - The temporal date to which hours will be added.
  * @param {number} amount - The number of hours to add.
  * @param {string} [timeZone] - The time zone to use for the addition. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The resulting temporal date after adding the specified number of hours.
+ * @returns {Temporal.ZonedDateTime} The resulting temporal date after adding the specified number of hours.
  * @example
  * const dateString = "2023-05-10"
  * const date = new Date(dateString);
@@ -191,7 +214,7 @@ export declare const addHoursUtil: (date: TemporalDate, amount: number, timeZone
  * @param {TemporalDate} date - The temporal date to which days will be added.
  * @param {number} amount - The number of days to add.
  * @param {string} [timeZone] - The time zone to use for the addition. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The resulting temporal date after adding the specified number of days.
+ * @returns {Temporal.ZonedDateTime} The resulting temporal date after adding the specified number of days.
  * @example
  * const dateString = "2023-05-10"
  * const date = new Date(dateString);
@@ -206,7 +229,7 @@ export declare const addDaysUtil: (date: TemporalDate, amount: number, timeZone?
  * @param {TemporalDate} date - The temporal date to which weeks will be added.
  * @param {number} amount - The number of weeks to add.
  * @param {string} [timeZone] - The time zone to use for the addition. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The resulting temporal date after adding the specified number of weeks.
+ * @returns {Temporal.ZonedDateTime} The resulting temporal date after adding the specified number of weeks.
  * @example
  * const dateString = "2023-05-10"
  * const date = new Date(dateString);
@@ -221,7 +244,7 @@ export declare const addWeeksUtil: (date: TemporalDate, amount: number, timeZone
  * @param {TemporalDate} date - The temporal date to which months will be added.
  * @param {number} amount - The number of months to add.
  * @param {string} [timeZone] - The time zone to use for the addition. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The resulting temporal date after adding the specified number of months.
+ * @returns {Temporal.ZonedDateTime} The resulting temporal date after adding the specified number of months.
  * @example
  * const dateString = "2023-05-10"
  * const date = new Date(dateString);
@@ -236,7 +259,7 @@ export declare const addMonthsUtil: (date: TemporalDate, amount: number, timeZon
  * @param {TemporalDate} date - The temporal date to which years will be added.
  * @param {number} amount - The number of years to add.
  * @param {string} [timeZone] - The time zone to use for the addition. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The resulting temporal date after adding the specified number of years.
+ * @returns {Temporal.ZonedDateTime} The resulting temporal date after adding the specified number of years.
  * @example
  * const dateString = "2023-05-10"
  * const date = new Date(dateString);
@@ -250,33 +273,33 @@ export declare const addYearsUtil: (date: TemporalDate, amount: number, timeZone
  *
  * @param {TemporalDate} date - The temporal date for which to determine the start of the minute.
  * @param {string} [timeZone] - The time zone to use for determining the start of the minute. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The temporal date representing the start of the minute.
+ * @returns {Temporal.ZonedDateTime} The temporal date representing the start of the minute.
  * @example
  * const dateString = "2023-05-10T10:30:10.000Z"
  * const date = new Date(dateString);
  * const result = startOfMinuteUtil(date);
  * Output: Temporal.ZonedDateTime { year: 2023, month: 5, day: 10, hour: 10, minute: 30, second: 0, millisecond: 0, microsecond: 0, nanosecond: 0, timeZone: Temporal.TimeZone { id: "America/New_York" }, calendar: Temporal.Calendar { id: "iso8601" } }
  */
-export declare const startOfMinuteUtil: (date: TemporalDate, timeZone?: string) => Temporal.ZonedDateTime;
+export declare const startOfMinuteUtil: (date: TemporalDate, timeZone?: string) => TemporalDate;
 /**
  * Returns the end of the minute for a date.
  *
  * @param {TemporalDate} date - The temporal date for which to determine the end of the minute.
  * @param {string} [timeZone] - The time zone to use for determining the end of the minute. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The temporal date representing the end of the minute.
+ * @returns {Temporal.ZonedDateTime} The temporal date representing the end of the minute.
  * @example
  * const dateString = "2023-05-10T10:30:10.000Z"
  * const date = new Date(dateString);
  * const result = endOfMinuteUtil(date);
  * Output: Temporal.ZonedDateTime { year: 2023, month: 5, hour: 10, day: 10, minute: 30, second: 59, millisecond: 999, microsecond: 0, nanosecond: 0, timeZone: Temporal.TimeZone { id: "America/New_York" }, calendar: Temporal.Calendar { id: "iso8601" } }
  */
-export declare const endOfMinuteUtil: (date: TemporalDate, timeZone?: string) => Temporal.ZonedDateTime;
+export declare const endOfMinuteUtil: (date: TemporalDate, timeZone?: string) => TemporalDate;
 /**
  * Returns the start of the hour for a temporal date.
  *
  * @param {TemporalDate} date - The temporal date for which to determine the start of the hour.
  * @param {string} [timeZone] - The time zone to use for determining the start of the hour. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The temporal date representing the start of the hour.
+ * @returns {Temporal.ZonedDateTime} The temporal date representing the start of the hour.
  * @example
  * const dateString = "2023-05-10T10:30:30.000Z"
  * const date = new Date(dateString);
@@ -289,7 +312,7 @@ export declare const startOfHourUtil: (date: TemporalDate, timeZone?: string) =>
  *
  * @param {TemporalDate} date - The temporal date for which to determine the end of the hour.
  * @param {string} [timeZone] - The time zone to use for determining the end of the hour. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The temporal date representing the end of the hour.
+ * @returns {Temporal.ZonedDateTime} The temporal date representing the end of the hour.
  * @example
  * const dateString = "2023-05-10T10:30:00.000Z"
  * const date = new Date(dateString);
@@ -302,7 +325,7 @@ export declare const endOfHourUtil: (date: TemporalDate, timeZone?: string) => T
  *
  * @param {TemporalDate} date - The temporal date for which to determine the start of the day.
  * @param {string} [timeZone] - The time zone to use for determining the start of the day. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The temporal date representing the start of the day.
+ * @returns {Temporal.ZonedDateTime} The temporal date representing the start of the day.
  * @example
  * const dateString = "2023-05-10T10:30:00.000Z"
  * const date = new Date(dateString);
@@ -315,7 +338,7 @@ export declare const startOfDayUtil: (date: TemporalDate, timeZone?: string) =>
  *
  * @param {TemporalDate} date - The temporal date for which to determine the end of the day.
  * @param {string} [timeZone] - The time zone to use for determining the end of the day. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The temporal date representing the end of the day.
+ * @returns {Temporal.ZonedDateTime} The temporal date representing the end of the day.
  * @example
  * const dateString = "2023-05-10T10:30:00.000Z"
  * const date = new Date(dateString);
@@ -328,7 +351,7 @@ export declare const endOfDayUtil: (date: TemporalDate, timeZone?: string) => Te
  *
  * @param {TemporalDate} date - The temporal date for which to determine the start of the week.
  * @param {string} [timeZone] - The time zone to use for determining the start of the week. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The temporal date representing the start of the week.
+ * @returns {Temporal.ZonedDateTime} The temporal date representing the start of the week.
  * @example
  * const dateString = "2023-05-10T10:30:00.000Z"
  * const date = new Date(dateString);
@@ -341,7 +364,7 @@ export declare const startOfWeekUtil: (date: TemporalDate, timeZone?: string) =>
  *
  * @param {TemporalDate} date - The temporal date for which to determine the end of the week.
  * @param {string} [timeZone] - The time zone to use for determining the end of the week. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The temporal date representing the end of the week.
+ * @returns {Temporal.ZonedDateTime} The temporal date representing the end of the week.
  * @example
  * const dateString = "2023-05-10T10:30:00.000Z"
  * const date = new Date(dateString);
@@ -354,7 +377,7 @@ export declare const endOfWeekUtil: (date: TemporalDate, timeZone?: string) => T
  *
  * @param {TemporalDate} date - The temporal date for which to determine the start of the month.
  * @param {string} [timeZone] - The time zone to use for determining the start of the month. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The temporal date representing the start of the month.
+ * @returns {Temporal.ZonedDateTime} The temporal date representing the start of the month.
  * @example
  * const dateString = "2023-05-10T10:30:00.000Z"
  * const date = new Date(dateString);
@@ -367,7 +390,7 @@ export declare const startOfMonthUtil: (date: TemporalDate, timeZone?: string) =
  *
  * @param {TemporalDate} date - The temporal date for which to determine the end of the month.
  * @param {string} [timeZone] - The time zone to use for determining the end of the month. If not provided, the system's default time zone will be used.
- * @returns {TemporalDate} The temporal date representing the end of the month.
+ * @returns {Temporal.ZonedDateTime} The temporal date representing the end of the month.
  * @example
  * const dateString = "2023-05-10"
  * const date = new Date(dateString);
@@ -530,6 +553,14 @@ export declare const isPastUtil: (date: TemporalDate) => boolean;
  * Output: true (if date is same as Temporal.Now.instant())
  */
 export declare const isTodayUtil: (date: TemporalDate) => boolean;
+/**
+ *
+ *
+ * @param date - The date to check.
+ * @param start - The start date to compare against.
+ * @param end - The en date to compare against.
+ */
+export declare const isBetweenUtil: (date: TemporalDate, start?: TemporalDate, end?: TemporalDate) => boolean;
 /**
  * Checks if a date is same day as current.
  *
@@ -710,6 +741,23 @@ export declare const timeSinceInMonths: (from: TemporalDate, to: TemporalDate, t
  * Output: "1 year ago"
  */
 export declare const timeSinceInYears: (from: TemporalDate, to: TemporalDate, timeZone?: string, locale?: string) => string;
+/**
+ * Get duration in human-readable form
+ *
+ * @param duration - years, months, days, minutes, seconds
+ * @param locale - selected locale
+ * @param format - long, short, narrow
+ * @returns {string} human-readable string
+ */
+export declare const getDurationFormat: (duration: Intl.Duration, locale?: string, format?: TemporalFormat["dayFormat"]) => string;
+/**
+ * convert a number to a type
+ *
+ * @param {number} number - 230.45
+ * @param {TemporalTimeTypes} unit - "days | "hours" | minutes
+ * @param {Temporal.TimeUnit} roundAt - smallest unit to show
+ */
+export declare const toDuration: (number: number, unit: TemporalTimeTypes, roundAt?: Extract<Temporal.TimeUnit, "hour" | "minute" | "second">) => Intl.Duration;
 /**
  * Converts a JavaScript Date object to a Temporal Instant.
  *
@@ -720,7 +768,7 @@ export declare const timeSinceInYears: (from: TemporalDate, to: TemporalDate, ti
  * const result = toTemporalUtil(jsDate);
  * Output: Temporal.Instant { year: ..., month: ..., day: ..., hour: ..., minute: ..., second: ..., millisecond: ... }
  */
-export declare const toTemporalUtil: (date: Date) => Temporal.Instant;
+export declare const toTemporalUtil: (date: Date | string) => Temporal.Instant;
 /**
  * Converts a Temporal Instant or Temporal ZonedDateTime to a JavaScript Date object.
  *
@@ -736,7 +784,7 @@ export declare const toTemporalUtil: (date: Date) => Temporal.Instant;
  * const result2 = toDateUtil(temporalZonedDateTime);
  * Output: Date { ... } (equivalent JavaScript Date object)
  */
-export declare const toDateUtil: (date: Temporal.Instant | Temporal.ZonedDateTime) => Date;
+export declare const toDateUtil: (date: Temporal.Instant | Temporal.ZonedDateTime | Date | string | number) => Date;
 /**
  * Converts a Temporal ZonedDateTime to a Temporal Instant.
  *
@@ -747,7 +795,7 @@ export declare const toDateUtil: (date: Temporal.Instant | Temporal.ZonedDateTim
  * const result = toInstantUtil(zonedDateTime);
  * Output: Temporal.Instant { year: ..., month: ..., day: ..., hour: ..., minute: ..., second: ..., millisecond: ... }
  */
-export declare const toInstantUtil: (zonedDateTime: Temporal.ZonedDateTime) => Temporal.Instant;
+export declare const toInstantUtil: (zonedDateTime: Temporal.ZonedDateTime | Date | string) => Temporal.Instant;
 /**
  * Converts a date to a temporal zoned date-time.
  *
@@ -762,7 +810,7 @@ export declare const toInstantUtil: (zonedDateTime: Temporal.ZonedDateTime) => T
  * const result = toZonedDateTimeUtil(date, timeZoneId);
  * Output: Temporal.ZonedDateTime { year: 2023, month: 5, day: 10, hour: 10, minute: 30, second: 0, millisecond: 0, microsecond: 0, nanosecond: 0, timeZone: Temporal.TimeZone { id: "America/New_York" }, calendar: Temporal.Calendar { id: "iso8601" } }
  */
-export declare const toZonedDateTimeUtil: (date: TemporalDate, timeZoneId?: string, calendar?: string) => Temporal.ZonedDateTime;
+export declare const toZonedDateTimeUtil: (date: TemporalDate | string, timeZoneId?: string, calendar?: string) => Temporal.ZonedDateTime;
 /**
  * Returns the month name for the given date.
  *
@@ -787,6 +835,13 @@ export declare const toZonedDateTimeUtil: (date: TemporalDate, timeZoneId?: stri
  * Output: "A"
  */
 export declare const monthNameUtil: (date: TemporalDate, format: TemporalFormatStyle, locale?: string) => string;
+/**
+ * Returns a list of month names
+ *
+ * @param {TemporalFormatStyle} format - select the format of the month name
+ * @param {string} locale - The locale to use for formatting. If not provided, the system's default locale will be used.
+ */
+export declare const monthsUtil: (format?: TemporalFormatStyle, locale?: string) => string[];
 /**
  * Returns the day name for the given date.
  *
@@ -811,4 +866,11 @@ export declare const monthNameUtil: (date: TemporalDate, format: TemporalFormatS
  * Output: "M"
  */
 export declare const dayNameUtil: (date: TemporalDate, format: TemporalFormatStyle, locale?: string) => string;
+/**
+ * Returns a list of day names
+ *
+ * @param {TemporalFormatStyle} format - select the format of the day name
+ * @param {string} locale - The locale to use for formatting. If not provided, the system's default locale will be used.
+ */
+export declare const daysUtil: (format?: TemporalFormatStyle, locale?: string) => string[];
 export {};