@dereekb/date 10.1.30 → 10.2.0

package/src/lib/date/date.d.ts

@@ -1,4 +1,4 @@
-import { type DayOfWeekNameFunction, type DateOrDateString, type ISO8601DateString, type Maybe, type Minutes, type Seconds, type TimezoneString, type ArrayOrValue, type MapFunction, type ISO8601DateStringUTCFull, type UTCDateString, type DayOfWeek, type UnixDateTimeNumber } from '@dereekb/util';
+import { type DayOfWeekNameFunction, type DateOrDateString, type ISO8601DateString, type Maybe, type Minutes, type Seconds, type TimezoneString, type ArrayOrValue, type MapFunction, type ISO8601DateStringUTCFull, type UTCDateString, type DayOfWeek, type UnixDateTimeNumber, type DateOrUnixDateTimeNumber, type DateHourMinuteOrSecond, type FloorOrCeilRounding } from '@dereekb/util';
 export declare const MAX_FUTURE_DATE: Date;
 /**
  * Reads a date from the input value
@@ -108,18 +108,26 @@ export declare function utcDayForDate(date: Date): Date;
  * For example, if it is currently 9PM:
  * - if 10PM on any day is passed then 9PM the next day will be returned.
  * - if 11PM on any day is passed, 11PM today will be returned.
+ *
+ * @deprecated Fails in the rare case where it is the first two hours of a day in a daylight savings zone when daylight savings changes.
  */
 export declare function takeNextUpcomingTime(date: Date, roundDownToMinute?: boolean): Date;
 /**
  * Creates a new date and copies the hours/minutes from the previous date and applies them to a date for today.
+ *
+ * @deprecated Fails in the rare case where it is the first two hours of a day in a daylight savings zone when daylight savings changes.
  */
 export declare function copyHoursAndMinutesFromDateToToday(fromDate: Date, roundDownToMinute?: boolean): Date;
 /**
  * Copies the hours/minutes from now to the target date.
+ *
+ * @deprecated Fails in the rare case where it is the first two hours of a day in a daylight savings zone when daylight savings changes.
  */
 export declare function copyHoursAndMinutesFromNow(target: Date, roundDownToMinute?: boolean): Date;
 /**
  * Creates a new date and copies the hours/minutes from the input date to the target date.
+ *
+ * @deprecated Fails in the rare case where it is the first two hours of a day in a daylight savings zone when daylight savings changes.
  */
 export declare function copyHoursAndMinutesFromDate(target: Date, fromDate: Date, roundDownToMinute?: boolean): Date;
 /**
@@ -143,11 +151,22 @@ export declare const copyHoursAndMinutesToToday: typeof copyHoursAndMinutesToDat
  */
 export declare function roundDownToMinute(date?: Date): Date;
 /**
- * Removes all minutes,
+ * Removes the minutes, seconds and milliseconds from the input date, or returns the current date with no mkinutes, seconds or milliseconds.
+ */
+export declare function roundDownToHour(date?: Date): Date;
+export declare function roundDateDownTo(date: Date, roundToUnit: DateHourMinuteOrSecond): Date;
+export declare function roundDateTo(date: Date, roundToUnit: DateHourMinuteOrSecond, roundType?: FloorOrCeilRounding): Date;
+export declare function roundDateTo(unixDateTimeNumber: UnixDateTimeNumber, roundToUnit: DateHourMinuteOrSecond, roundType?: FloorOrCeilRounding): UnixDateTimeNumber;
+export declare function roundDateToDate(date: DateOrUnixDateTimeNumber, roundToUnit: DateHourMinuteOrSecond, roundType?: FloorOrCeilRounding): Date;
+/**
+ * Rounds the input Date value down to the nearest hour, minute, or second.
+ *
  * @param date
+ * @param roundToUnit
+ * @param roundType
  * @returns
  */
-export declare function roundDownToHour(date: Date): Date;
+export declare function roundDateToUnixDateTimeNumber(date: DateOrUnixDateTimeNumber, roundToUnit: DateHourMinuteOrSecond, roundType?: FloorOrCeilRounding): UnixDateTimeNumber;
 export type ReduceDatesFunction = (inputDates: ArrayOrValue<Maybe<Date>>) => Maybe<Date>;
 export declare function reduceDatesFunction(reduceDates: (dates: Date[]) => Maybe<Date>): ReduceDatesFunction;
 /**

package/src/lib/date/date.timezone.d.ts

@@ -1,4 +1,4 @@
-import { type MapFunction, type Maybe, type Milliseconds, type TimezoneString, type ISO8601DayString, type YearNumber, type MapSameFunction, type Hours } from '@dereekb/util';
+import { type MapFunction, type Maybe, type Milliseconds, type TimezoneString, type ISO8601DayString, type YearNumber, type MapSameFunction, type Hours, type Minutes, type LogicalDate } from '@dereekb/util';
 import { type DateRange, type TransformDateRangeDatesFunction } from './date.range';
 /**
  * Inherited from the RRule library where RRule only deals with UTC date/times, dates going into it must always be in UTC.
@@ -72,31 +72,36 @@ export declare function isSameDateTimezoneConversionConfig(a: DateTimezoneConver
  * @param date Date is required to get the correct offset for the given date.
  * @returns
  */
-export declare function getCurrentSystemOffsetInMs(date: Date): number;
+export declare function getCurrentSystemOffsetInMs(date: Date): Milliseconds;
 /**
  * Returns the current system time offset in hours.
  *
  * @param date
  * @returns
  */
-export declare function getCurrentSystemOffsetInHours(date: Date): number;
+export declare function getCurrentSystemOffsetInHours(date: Date): Hours;
 /**
- * Equivalent to -date.getTimezoneOffset().
+ * Returns the system offset for the input date, in minutes.
+ *
+ * The offset corresponds positively with the UTC offset, so UTC-6 is negative 6 hours, in milliseconds.
  *
  * @param date
  * @returns
  */
-export declare function getCurrentSystemOffsetInMinutes(date: Date): number;
+export declare function getCurrentSystemOffsetInMinutes(date: Date): Minutes;
 /**
  * Returns the timezone offset in milliseconds.
  *
+ * This is preferential to Date.getTimezoneOffset() or date-fns's getTimezoneOffset() as those are currently wrong for the first
+ * two hours when daylight savings changes.
+ *
  * I.E. GMT-5 = -5 hours (in milliseconds)
  *
  * @param timezone
  * @param date
  * @returns
  */
-export declare function calculateTimezoneOffset(timezone: TimezoneString, date: Date): number;
+export declare function calculateTimezoneOffset(timezone: TimezoneString, date: Date): Milliseconds;
 export type DateTimezoneConversionTarget = 'target' | 'base' | 'system';
 export type DateTimezoneOffsetFunction = (date: Date, from: DateTimezoneConversionTarget, to: DateTimezoneConversionTarget) => Milliseconds;
 export interface DateTimezoneBaseDateConverter {
@@ -155,8 +160,26 @@ export declare class DateTimezoneUtcNormalInstance implements DateTimezoneBaseDa
     get usesSystemTimezone(): boolean;
     get configuredTimezoneString(): Maybe<TimezoneString>;
     private readonly _getOffset;
+    private readonly _setOnDate;
     constructor(config: DateTimezoneUtcNormalInstanceInput);
-    private _computeOffsetDate;
+    convertDate(date: Date, from: DateTimezoneConversionTarget, to: DateTimezoneConversionTarget): Date;
+    /**
+     * A "safer" conversion that will return a "mirrored" offset. Only functional with a "to" UTC value.
+     *
+     * This is required in cases where "reverse" offset will be used and must be consistent so they reverse in both directions the same amount compared to the base.
+     *
+     * For example, when daylight savings changed on November 3, 2024 the offset returned was 5 but to get back to the original an offset of 6 was required.
+     * This is where some contextual data was not being used. This function uses that contextual data to make sure the reverse will be consistent.
+     *
+     * @param baseDate The base date. Should have been derived from the originalContextDate using the convertDate() function
+     * @param originalContextDate Original date used to derive the baseDate.
+     * @param fromOrTo the "type" of date the originalContextDate is
+     */
+    safeMirroredConvertDate(baseDate: BaseDateAsUTC, originalContextDate: Date, contextType: DateTimezoneConversionTarget, safeConvert?: boolean): {
+        date: Date;
+        daylightSavingsOffset: number;
+    };
+    get setOnDate(): SetOnDateWithTimezoneNormalFunction;
     getCurrentOffset(date: Date, from: DateTimezoneConversionTarget, to: DateTimezoneConversionTarget): number;
     transform(date: Date, transform: DateTimezoneUtcNormalInstanceTransformType): Date;
     transformFunction(transform: DateTimezoneUtcNormalInstanceTransformType): MapFunction<Date, Date>;
@@ -176,6 +199,7 @@ export declare class DateTimezoneUtcNormalInstance implements DateTimezoneBaseDa
     systemDateToBaseDateOffset(date: Date): Milliseconds;
     targetDateToSystemDateOffset(date: Date): Milliseconds;
     systemDateToTargetDateOffset(date: Date): Milliseconds;
+    conversionOffset(date: Date, from: DateTimezoneConversionTarget, to: DateTimezoneConversionTarget): number;
     calculateAllOffsets<T = number>(date: Date, map?: DateTimezoneConversionFunction<T>): DateTimezoneConversionMap<T>;
     /**
      * Returns true if the input is midnight in the target timezone.
@@ -292,6 +316,68 @@ export declare function startOfDayInTimezoneDayStringFactory(timezone?: DateTime
  * @returns
  */
 export declare function startOfDayInTimezoneFromISO8601DayString(day: ISO8601DayString, timezone?: DateTimezoneUtcNormalFunctionInput): Date;
+export interface SetOnDateWithTimezoneNormalFunctionInput {
+    /**
+     * Date to update
+     *
+     * If not defined, will use "now".
+     */
+    readonly date?: Maybe<Date>;
+    /**
+     * The input date target type of the date and copyFrom values.
+     *
+     * Defaults to "target"
+     */
+    readonly inputType?: DateTimezoneConversionTarget;
+    /**
+     * The return date target type.
+     *
+     * Defaults to to the inputType, or to "target" if neither are defined.
+     */
+    readonly outputType?: DateTimezoneConversionTarget;
+    /**
+     * Hours to set
+     */
+    readonly hours?: Maybe<number>;
+    /**
+     * Minutes to set
+     */
+    readonly minutes?: Maybe<number>;
+    /**
+     * (Optional) date value to copy from.
+     *
+     * If hours or minutes are set, those values take priority over the value read from this.
+     */
+    readonly copyFrom?: Maybe<LogicalDate>;
+    /**
+     * If true, will copy the hours from the input date.
+     *
+     * Defaults to true.
+     */
+    readonly copyHours?: Maybe<boolean>;
+    /**
+     * If true, will copy the minutes from the input date.
+     *
+     * Defaults to true.
+     */
+    readonly copyMinutes?: Maybe<boolean>;
+    /**
+     * Whether or not to round down to the nearest minute.
+     *
+     * Defaults to false.
+     */
+    readonly roundDownToMinute?: Maybe<boolean>;
+}
+/**
+ * Sets the input values on the input date.
+ */
+export type SetOnDateWithTimezoneNormalFunction = ((input: SetOnDateWithTimezoneNormalFunctionInput) => Date) & {
+    readonly _timezoneInstance: DateTimezoneUtcNormalInstance;
+};
+/**
+ * Creates a new SetONDateFunction using the input
+ */
+export declare function setOnDateWithTimezoneNormalFunction(timezone: DateTimezoneUtcNormalFunctionInput): SetOnDateWithTimezoneNormalFunction;
 /**
  * Convenience function for calling copyHoursAndMinutesFromDatesWithTimezoneNormal() with now.
  *
@@ -301,7 +387,7 @@ export declare function startOfDayInTimezoneFromISO8601DayString(day: ISO8601Day
  */
 export declare function copyHoursAndMinutesFromNowWithTimezoneNormal(input: Date, timezone: DateTimezoneUtcNormalFunctionInput): Date;
 /**
- * Converts the two input dates, which are dates in the same timezone/normal but than the current system, using the input DateTimezoneUtcNormalFunctionInput.
+ * Converts the two input dates, which are dates in the same timezone/normal instead of the current system, using the input DateTimezoneUtcNormalFunctionInput.
  *
  * This converts the dates to the system timezone normal, copies the values, then back to the original timezone normal.
  *
@@ -309,4 +395,4 @@ export declare function copyHoursAndMinutesFromNowWithTimezoneNormal(input: Date
  * @param copyFrom
  * @param timezone
  */
-export declare function copyHoursAndMinutesFromDateWithTimezoneNormal(input: Date, copyFrom: Date, timezone: DateTimezoneUtcNormalFunctionInput): Date;
+export declare function copyHoursAndMinutesFromDateWithTimezoneNormal(input: Date, copyFrom: LogicalDate, timezone: DateTimezoneUtcNormalFunctionInput): Date;