@org-quicko/core 2.0.3 → 2.0.5

package/README.md

@@ -1,8 +1,33 @@
 # core
-Foundational Node.js library built with TypeScript used across Quicko
 
-## 📦 Installation
+Foundational Node.js library built with TypeScript used across Quicko.
+
+## Installation
 
 ```bash
 npm install @org-quicko/core
-```
+```
+
+## Release Flow
+
+This repository uses GitHub Actions to separate pull request validation, release drafting, and npm publishing.
+
+- Pull requests run install, date util tests, and build validation.
+- Pushes to `main` update the next draft release using Release Drafter.
+- Publishing happens only when a GitHub release is published.
+- PR titles are used directly in the drafted release notes, so keep them clear and specific.
+- PR labels influence both release note grouping and version bump resolution.
+
+### Publishing A New Version
+
+1. Update the version in `package.json`.
+2. Merge the change into `main`.
+3. Review the drafted GitHub release.
+4. Publish the release with a tag that matches the package version, for example `v2.0.4`.
+
+When the release is published, GitHub Actions will:
+
+- verify the release tag matches `package.json`
+- run install, tests, and build
+- skip publish if that version already exists on npm
+- publish the package to npm using the configured `NPM_TOKEN`

package/dist/browser/utils/date/DateUtil.js

@@ -1,5 +1,5 @@
 import { TZDate } from '@date-fns/tz';
-import { parse, isValid, format, startOfDay, endOfDay, differenceInCalendarDays, differenceInCalendarMonths, differenceInCalendarYears, compareAsc, add, isLeapYear } from 'date-fns';
+import { parse, isValid, format, startOfDay, endOfDay, differenceInCalendarDays, differenceInCalendarMonths, differenceInCalendarYears, differenceInHours, differenceInSeconds, compareAsc, add, isLeapYear } from 'date-fns';
 import { IllegalArgumentException } from '../../exceptions/IllegalArgumentException.js';
 
 /**
@@ -8,6 +8,7 @@ import { IllegalArgumentException } from '../../exceptions/IllegalArgumentExcept
  */
 class DateUtil {
     static { this.ISO_8601_FORMAT = "yyyy-MM-dd'T'HH:mm:ss.SSSxxx"; }
+    static { this.TIMEZONE = "UTC"; }
     /**
      * Gets the current date and time in the specified time zone.
      * @param timeZone The IANA time zone identifier.
@@ -39,15 +40,15 @@ class DateUtil {
         return date;
     }
     static printDate(date, timeZone, dateFormat = this.ISO_8601_FORMAT) {
-        const normalizedDate = typeof date === 'number' ? new Date(date) : date;
+        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;
         return format(new TZDate(normalizedDate, timeZone), dateFormat);
     }
     static getStartOfDay(date, timeZone) {
-        const normalizedDate = typeof date === 'number' ? new Date(date) : date;
+        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;
         return startOfDay(new TZDate(normalizedDate, timeZone));
     }
     static getEndOfDay(date, timeZone) {
-        const normalizedDate = typeof date === 'number' ? new Date(date) : date;
+        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;
         return endOfDay(new TZDate(normalizedDate, timeZone));
     }
     /**
@@ -60,35 +61,48 @@ class DateUtil {
         try {
             DateUtil.readDate(dateString, dateFormat, "UTC");
             return true;
-            // eslint-disable-next-line @typescript-eslint/no-unused-vars
         }
         catch (error) {
             return false;
         }
     }
-    static daysInBetween(firstDate, secondDate) {
-        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;
-        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;
-        return Math.abs(differenceInCalendarDays(first, second));
+    static daysInBetween(firstDate, secondDate, timeZone) {
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
+        const effectiveTimeZone = timeZone || this.TIMEZONE;
+        return Math.abs(differenceInCalendarDays(new TZDate(first, effectiveTimeZone), new TZDate(second, effectiveTimeZone)));
     }
-    static monthsInBetween(firstDate, secondDate) {
-        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;
-        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;
-        return Math.abs(differenceInCalendarMonths(first, second));
+    static monthsInBetween(firstDate, secondDate, timeZone) {
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
+        const effectiveTimeZone = timeZone || this.TIMEZONE;
+        return Math.abs(differenceInCalendarMonths(new TZDate(first, effectiveTimeZone), new TZDate(second, effectiveTimeZone)));
     }
-    static yearsInBetween(firstDate, secondDate) {
-        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;
-        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;
-        return Math.abs(differenceInCalendarYears(first, second));
+    static yearsInBetween(firstDate, secondDate, timeZone) {
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
+        const effectiveTimeZone = timeZone || this.TIMEZONE;
+        return Math.abs(differenceInCalendarYears(new TZDate(first, effectiveTimeZone), new TZDate(second, effectiveTimeZone)));
+    }
+    static hoursInBetween(firstDate, secondDate) {
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
+        return Math.abs(differenceInHours(first, second));
+    }
+    static secondsInBetween(firstDate, secondDate) {
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
+        return Math.abs(differenceInSeconds(first, second));
     }
     static compareDates(firstDate, secondDate) {
-        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;
-        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
         return compareAsc(first, second);
     }
-    static addDuration(date, duration) {
-        const normalizedDate = typeof date === 'number' ? new Date(date) : date;
-        return add(normalizedDate, duration);
+    static addDuration(date, duration, timeZone) {
+        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;
+        const effectiveTimeZone = timeZone || this.TIMEZONE;
+        return add(new TZDate(normalizedDate, effectiveTimeZone), duration);
     }
     /**
      * Determines whether a given year is a leap year.

package/dist/browser/utils/date/DateUtil.js.map

@@ -1 +1 @@
-{"version":3,"file":"DateUtil.js","sources":["../../../../src/utils/date/DateUtil.ts"],"sourcesContent":["import { TZDate } from '@date-fns/tz';\nimport { add, compareAsc, differenceInCalendarDays, differenceInCalendarMonths, differenceInCalendarYears, Duration, endOfDay, format, isLeapYear, isValid, parse, startOfDay } from 'date-fns';\nimport { IllegalArgumentException } from '../../exceptions';\n\n/**\n * Utility class for date and time operations. Provides methods for parsing,\n * formatting, and performing calculations with dates and times.\n */\nexport class DateUtil {\n\n    static readonly ISO_8601_FORMAT = \"yyyy-MM-dd'T'HH:mm:ss.SSSxxx\"\n\n    /**\n     * Gets the current date and time in the specified time zone.\n     * @param timeZone The IANA time zone identifier.\n     * @returns Current date and time in the specified time zone.\n     */\n    static now(timeZone: string): Date {\n        return new TZDate(new Date(), timeZone);\n    }\n\n    /**\n     * Gets the current time in milliseconds since the Unix epoch.\n     * @returns Current time in milliseconds.\n     */\n    static nowInMillis(): number {\n        return Date.now();\n    }\n\n    /**\n     * Parses a date string into a Date object.\n     * @param dateString The date string to parse.\n     * @param dateFormat The format of the date string (default: ISO_8601_FORMAT).\n     * @param timeZone The IANA time zone identifier.\n     * @throws {IllegalArgumentException} If the date string is invalid.\n     * @returns Parsed Date object.\n     */\n    static readDate(dateString: string, dateFormat = this.ISO_8601_FORMAT, timeZone: string): Date {\n        const date = parse(dateString, dateFormat, TZDate.tz(timeZone));\n        if (!isValid(date)) {\n            throw new IllegalArgumentException('Invalid date string or date format');\n        }\n        return date;\n    }\n\n    /**\n     * Formats a Date or timestamp into a string.\n     * @param date The date or timestamp to format.\n     * @param timeZone The IANA time zone identifier.\n     * @param dateFormat The desired output format (default: ISO_8601_FORMAT).\n     * @returns Formatted date string.\n     */\n    static printDate(date: Date, timeZone: string, dateFormat?: string): string;\n    static printDate(date: number, timeZone: string, dateFormat?: string): string;\n    static printDate(date: Date | number, timeZone: string, dateFormat: string = this.ISO_8601_FORMAT): string {\n        const normalizedDate = typeof date === 'number' ? new Date(date) : date;\n        return format(new TZDate(normalizedDate, timeZone), dateFormat);\n    }\n\n    /**\n     * Gets the start of the day for a given date or timestamp.\n     * @param date The date or timestamp to calculate from.\n     * @param timeZone The IANA time zone identifier.\n     * @returns The start of the day as a Date object.\n     */\n    static getStartOfDay(date: Date, timeZone: string): Date;\n    static getStartOfDay(date: number, timeZone: string): Date;\n    static getStartOfDay(date: Date | number, timeZone: string): Date {\n        const normalizedDate = typeof date === 'number' ? new Date(date) : date;\n        return startOfDay(new TZDate(normalizedDate, timeZone));\n    }\n\n    /**\n     * Gets the end of the day for a given date or timestamp.\n     * @param date The date or timestamp to calculate from.\n     * @param timeZone The IANA time zone identifier.\n     * @returns The end of the day as a Date object.\n     */\n    static getEndOfDay(date: Date, timeZone: string): Date;\n    static getEndOfDay(date: number, timeZone: string): Date;\n    static getEndOfDay(date: Date | number, timeZone: string): Date {\n        const normalizedDate = typeof date === 'number' ? new Date(date) : date;\n        return endOfDay(new TZDate(normalizedDate, timeZone));\n    }\n\n    /**\n     * Checks if a date string is valid according to the specified format.\n     * @param dateString The date string to validate.\n     * @param dateFormat Optional date format (default: ISO_8601_FORMAT).\n     * @returns True if the date is valid, false otherwise.\n     */\n    static isValidDate(dateString: string, dateFormat?: string): boolean {\n        try {\n            DateUtil.readDate(dateString, dateFormat, \"UTC\");\n            return true;\n            // eslint-disable-next-line @typescript-eslint/no-unused-vars\n        } catch (error) {\n            return false;\n        }\n    }\n\n    /**\n     * Calculates the absolute number of days between two dates or timestamps.\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns Number of days between the two dates.\n     */\n    static daysInBetween(firstDate: Date, secondDate: Date): number;\n    static daysInBetween(firstDate: number, secondDate: number): number;\n    static daysInBetween(firstDate: Date | number, secondDate: Date | number): number {\n        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;\n        return Math.abs(differenceInCalendarDays(first, second));\n    }\n\n    /**\n * Calculates the absolute number of months between two dates or timestamps.\n * @param firstDate The first date or timestamp.\n * @param secondDate The second date or timestamp.\n * @returns The number of months between the two dates.\n */\n    static monthsInBetween(firstDate: Date, secondDate: Date): number;\n    static monthsInBetween(firstDate: number, secondDate: number): number;\n    static monthsInBetween(firstDate: Date | number, secondDate: Date | number): number {\n        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;\n        return Math.abs(differenceInCalendarMonths(first, second));\n    }\n\n    /**\n     * Calculates the absolute number of years between two dates or timestamps.\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns The number of years between the two dates.\n     */\n    static yearsInBetween(firstDate: Date, secondDate: Date): number;\n    static yearsInBetween(firstDate: number, secondDate: number): number;\n    static yearsInBetween(firstDate: Date | number, secondDate: Date | number): number {\n        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;\n        return Math.abs(differenceInCalendarYears(first, second));\n    }\n\n    /**\n     * Compares two dates or timestamps.\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns `-1` if the first date is earlier, `1` if it is later, or `0` if the two dates are equal.\n     */\n    static compareDates(firstDate: Date, secondDate: Date): -1 | 0 | 1;\n    static compareDates(firstDate: number, secondDate: number): -1 | 0 | 1;\n    static compareDates(firstDate: Date | number, secondDate: Date | number): -1 | 0 | 1 {\n        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;\n\n        return compareAsc(first, second) as -1 | 0 | 1;\n    }\n\n    /**\n     * Adds a duration (e.g., days, months, years) to a given date or timestamp.\n     * @param date The base date or timestamp to which the duration will be added.\n     * @param duration An object specifying the duration (e.g., `{ days: 1, months: 2 }`).\n     * @returns A new Date object with the duration added.\n     */\n    static addDuration(date: Date, duration: Duration): Date;\n    static addDuration(date: number, duration: Duration): Date;\n    static addDuration(date: Date | number, duration: Duration): Date {\n        const normalizedDate = typeof date === 'number' ? new Date(date) : date;\n        return add(normalizedDate, duration);\n    }\n\n    /**\n     * Determines whether a given year is a leap year.\n     * @param year The year to check.\n     * @returns `true` if the year is a leap year, otherwise `false`.\n     */\n    static isLeapYear(year: number): boolean {\n        return isLeapYear(DateUtil.readDate(year.toString(), 'yyyy', \"UTC\"));\n    }\n\n\n    /**\n     * Converts a timestamp (in milliseconds) to a Date object.\n     * @param milliseconds The timestamp in milliseconds since the Unix epoch.\n     * @returns A Date object representing the provided timestamp.\n     */\n    static fromMillis(milliseconds: number): Date {\n        return new Date(milliseconds);\n    }\n\n    /**\n     * Converts a Date object to a timestamp (in milliseconds).\n     * @param date The Date object to convert.\n     * @returns The timestamp in milliseconds since the Unix epoch.\n     */\n    static toMillis(date: Date): number {\n        return date.getTime();\n    }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"DateUtil.js","sources":["../../../../src/utils/date/DateUtil.ts"],"sourcesContent":["import { TZDate } from '@date-fns/tz';\nimport { add, compareAsc, differenceInCalendarDays, differenceInCalendarMonths, differenceInCalendarYears, differenceInHours, differenceInSeconds, Duration, endOfDay, format, isLeapYear, isValid, parse, startOfDay } from 'date-fns';\nimport { IllegalArgumentException } from '../../exceptions';\n\n/**\n * Utility class for date and time operations. Provides methods for parsing,\n * formatting, and performing calculations with dates and times.\n */\nexport class DateUtil {\n\n    static readonly ISO_8601_FORMAT = \"yyyy-MM-dd'T'HH:mm:ss.SSSxxx\"\n    static readonly TIMEZONE = \"UTC\"\n\n    /**\n     * Gets the current date and time in the specified time zone.\n     * @param timeZone The IANA time zone identifier.\n     * @returns Current date and time in the specified time zone.\n     */\n    static now(timeZone: string): Date {\n        return new TZDate(new Date(), timeZone);\n    }\n\n    /**\n     * Gets the current time in milliseconds since the Unix epoch.\n     * @returns Current time in milliseconds.\n     */\n    static nowInMillis(): number {\n        return Date.now();\n    }\n\n    /**\n     * Parses a date string into a Date object.\n     * @param dateString The date string to parse.\n     * @param dateFormat The format of the date string (default: ISO_8601_FORMAT).\n     * @param timeZone The IANA time zone identifier.\n     * @throws {IllegalArgumentException} If the date string is invalid.\n     * @returns Parsed Date object.\n     */\n    static readDate(dateString: string, dateFormat = this.ISO_8601_FORMAT, timeZone: string): Date {\n        const date = parse(dateString, dateFormat, TZDate.tz(timeZone));\n        if (!isValid(date)) {\n            throw new IllegalArgumentException('Invalid date string or date format');\n        }\n        return date;\n    }\n\n    /**\n     * Formats a Date or timestamp into a string.\n     * @param date The date or timestamp to format.\n     * @param timeZone The IANA time zone identifier.\n     * @param dateFormat The desired output format (default: ISO_8601_FORMAT).\n     * @returns Formatted date string.\n     */\n    static printDate(date: Date, timeZone: string, dateFormat?: string): string;\n    static printDate(date: number, timeZone: string, dateFormat?: string): string;\n    static printDate(date: Date | number, timeZone: string, dateFormat: string = this.ISO_8601_FORMAT): string {\n        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;\n        return format(new TZDate(normalizedDate, timeZone), dateFormat);\n    }\n\n    /**\n     * Gets the start of the day for a given date or timestamp.\n     * @param date The date or timestamp to calculate from.\n     * @param timeZone The IANA time zone identifier.\n     * @returns The start of the day as a Date object.\n     */\n    static getStartOfDay(date: Date, timeZone: string): Date;\n    static getStartOfDay(date: number, timeZone: string): Date;\n    static getStartOfDay(date: Date | number, timeZone: string): Date {\n        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;\n        return startOfDay(new TZDate(normalizedDate, timeZone));\n    }\n\n    /**\n     * Gets the end of the day for a given date or timestamp.\n     * @param date The date or timestamp to calculate from.\n     * @param timeZone The IANA time zone identifier.\n     * @returns The end of the day as a Date object.\n     */\n    static getEndOfDay(date: Date, timeZone: string): Date;\n    static getEndOfDay(date: number, timeZone: string): Date;\n    static getEndOfDay(date: Date | number, timeZone: string): Date {\n        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;\n        return endOfDay(new TZDate(normalizedDate, timeZone));\n    }\n\n    /**\n     * Checks if a date string is valid according to the specified format.\n     * @param dateString The date string to validate.\n     * @param dateFormat Optional date format (default: ISO_8601_FORMAT).\n     * @returns True if the date is valid, false otherwise.\n     */\n    static isValidDate(dateString: string, dateFormat?: string): boolean {\n        try {\n            DateUtil.readDate(dateString, dateFormat, \"UTC\");\n            return true;\n        } catch (error) {\n            return false;\n        }\n    }\n\n    /**\n     * Calculates the absolute number of calendar days between two dates or timestamps.\n     * Since day boundaries depend on a calendar, callers can optionally provide a time zone\n     * so the same pair of instants is interpreted consistently across machines.\n     *\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @param timeZone Optional IANA time zone identifier used for calendar comparisons.\n     * @returns Number of days between the two dates.\n     */\n    static daysInBetween(firstDate: Date, secondDate: Date, timeZone?: string): number;\n    static daysInBetween(firstDate: number, secondDate: number, timeZone?: string): number;\n    static daysInBetween(firstDate: Date | number, secondDate: Date | number, timeZone?: string): number {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n        const effectiveTimeZone = timeZone || this.TIMEZONE;\n        return Math.abs(\n            differenceInCalendarDays(\n                new TZDate(first, effectiveTimeZone),\n                new TZDate(second, effectiveTimeZone),\n            )\n        );\n    }\n\n    /**\n     * Calculates the absolute number of calendar months between two dates or timestamps.\n     * Since month boundaries depend on a calendar, callers can optionally provide a time zone\n     * so the same pair of instants is interpreted consistently across machines.\n     *\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @param timeZone Optional IANA time zone identifier used for calendar comparisons.\n     * @returns The number of months between the two dates.\n     */\n    static monthsInBetween(firstDate: Date, secondDate: Date, timeZone?: string): number;\n    static monthsInBetween(firstDate: number, secondDate: number, timeZone?: string): number;\n    static monthsInBetween(firstDate: Date | number, secondDate: Date | number, timeZone?: string): number {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n        const effectiveTimeZone = timeZone || this.TIMEZONE;\n        return Math.abs(\n            differenceInCalendarMonths(\n                new TZDate(first, effectiveTimeZone),\n                new TZDate(second, effectiveTimeZone),\n            )\n        );\n    }\n\n    /**\n     * Calculates the absolute number of calendar years between two dates or timestamps.\n     * Since year boundaries depend on a calendar, callers can optionally provide a time zone\n     * so the same pair of instants is interpreted consistently across machines.\n     *\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @param timeZone Optional IANA time zone identifier used for calendar comparisons.\n     * @returns The number of years between the two dates.\n     */\n    static yearsInBetween(firstDate: Date, secondDate: Date, timeZone?: string): number;\n    static yearsInBetween(firstDate: number, secondDate: number, timeZone?: string): number;\n    static yearsInBetween(firstDate: Date | number, secondDate: Date | number, timeZone?: string): number {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n        const effectiveTimeZone = timeZone || this.TIMEZONE;\n        return Math.abs(\n            differenceInCalendarYears(\n                new TZDate(first, effectiveTimeZone),\n                new TZDate(second, effectiveTimeZone),\n            )\n        );\n    }\n\n    /**\n     * Calculates the absolute elapsed number of hours between two dates or timestamps.\n     * This is duration-based, not calendar-based, so it is independent of time zone.\n     *\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns The number of hours between the two dates.\n     */\n    static hoursInBetween(firstDate: Date, secondDate: Date): number;\n    static hoursInBetween(firstDate: number, secondDate: number): number;\n    static hoursInBetween(firstDate: Date | number, secondDate: Date | number): number {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n        return Math.abs(differenceInHours(first, second));\n    }\n\n    /**\n     * Calculates the absolute elapsed number of seconds between two dates or timestamps.\n     * This is duration-based, not calendar-based, so it is independent of time zone.\n     *\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns The number of seconds between the two dates.\n     */\n    static secondsInBetween(firstDate: Date, secondDate: Date): number;\n    static secondsInBetween(firstDate: number, secondDate: number): number;\n    static secondsInBetween(firstDate: Date | number, secondDate: Date | number): number {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n        return Math.abs(differenceInSeconds(first, second));\n    }\n\n    /**\n     * Compares two dates or timestamps.\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns `-1` if the first date is earlier, `1` if it is later, or `0` if the two dates are equal.\n     */\n    static compareDates(firstDate: Date, secondDate: Date): -1 | 0 | 1;\n    static compareDates(firstDate: number, secondDate: number): -1 | 0 | 1;\n    static compareDates(firstDate: Date | number, secondDate: Date | number): -1 | 0 | 1 {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n\n        return compareAsc(first, second) as -1 | 0 | 1;\n    }\n\n    /**\n     * Adds a duration (e.g., days, months, years) to a given date or timestamp.\n     * When a time zone is provided, the duration is applied using calendar arithmetic\n     * in that time zone so month-end or day-boundary business rules stay aligned locally.\n     *\n     * @param date The base date or timestamp to which the duration will be added.\n     * @param duration An object specifying the duration (e.g., `{ days: 1, months: 2 }`).\n     * @param timeZone Optional IANA time zone identifier used for calendar math.\n     * @returns A new Date object with the duration added.\n     */\n    static addDuration(date: Date, duration: Duration, timeZone?: string): Date;\n    static addDuration(date: number, duration: Duration, timeZone?: string): Date;\n    static addDuration(date: Date | number, duration: Duration, timeZone?: string): Date {\n        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;\n        const effectiveTimeZone = timeZone || this.TIMEZONE;\n        return add(new TZDate(normalizedDate, effectiveTimeZone), duration);\n    }\n\n    /**\n     * Determines whether a given year is a leap year.\n     * @param year The year to check.\n     * @returns `true` if the year is a leap year, otherwise `false`.\n     */\n    static isLeapYear(year: number): boolean {\n        return isLeapYear(DateUtil.readDate(year.toString(), 'yyyy', \"UTC\"));\n    }\n\n\n    /**\n     * Converts a timestamp (in milliseconds) to a Date object.\n     * @param milliseconds The timestamp in milliseconds since the Unix epoch.\n     * @returns A Date object representing the provided timestamp.\n     */\n    static fromMillis(milliseconds: number): Date {\n        return new Date(milliseconds);\n    }\n\n    /**\n     * Converts a Date object to a timestamp (in milliseconds).\n     * @param date The Date object to convert.\n     * @returns The timestamp in milliseconds since the Unix epoch.\n     */\n    static toMillis(date: Date): number {\n        return date.getTime();\n    }\n}\n"],"names":[],"mappings":"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"}

package/dist/cjs/utils/date/DateUtil.cjs

@@ -10,6 +10,7 @@ var IllegalArgumentException = require('../../exceptions/IllegalArgumentExceptio
  */
 class DateUtil {
     static { this.ISO_8601_FORMAT = "yyyy-MM-dd'T'HH:mm:ss.SSSxxx"; }
+    static { this.TIMEZONE = "UTC"; }
     /**
      * Gets the current date and time in the specified time zone.
      * @param timeZone The IANA time zone identifier.
@@ -41,15 +42,15 @@ class DateUtil {
         return date;
     }
     static printDate(date, timeZone, dateFormat = this.ISO_8601_FORMAT) {
-        const normalizedDate = typeof date === 'number' ? new Date(date) : date;
+        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;
         return dateFns.format(new tz.TZDate(normalizedDate, timeZone), dateFormat);
     }
     static getStartOfDay(date, timeZone) {
-        const normalizedDate = typeof date === 'number' ? new Date(date) : date;
+        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;
         return dateFns.startOfDay(new tz.TZDate(normalizedDate, timeZone));
     }
     static getEndOfDay(date, timeZone) {
-        const normalizedDate = typeof date === 'number' ? new Date(date) : date;
+        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;
         return dateFns.endOfDay(new tz.TZDate(normalizedDate, timeZone));
     }
     /**
@@ -62,35 +63,48 @@ class DateUtil {
         try {
             DateUtil.readDate(dateString, dateFormat, "UTC");
             return true;
-            // eslint-disable-next-line @typescript-eslint/no-unused-vars
         }
         catch (error) {
             return false;
         }
     }
-    static daysInBetween(firstDate, secondDate) {
-        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;
-        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;
-        return Math.abs(dateFns.differenceInCalendarDays(first, second));
+    static daysInBetween(firstDate, secondDate, timeZone) {
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
+        const effectiveTimeZone = timeZone || this.TIMEZONE;
+        return Math.abs(dateFns.differenceInCalendarDays(new tz.TZDate(first, effectiveTimeZone), new tz.TZDate(second, effectiveTimeZone)));
     }
-    static monthsInBetween(firstDate, secondDate) {
-        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;
-        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;
-        return Math.abs(dateFns.differenceInCalendarMonths(first, second));
+    static monthsInBetween(firstDate, secondDate, timeZone) {
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
+        const effectiveTimeZone = timeZone || this.TIMEZONE;
+        return Math.abs(dateFns.differenceInCalendarMonths(new tz.TZDate(first, effectiveTimeZone), new tz.TZDate(second, effectiveTimeZone)));
     }
-    static yearsInBetween(firstDate, secondDate) {
-        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;
-        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;
-        return Math.abs(dateFns.differenceInCalendarYears(first, second));
+    static yearsInBetween(firstDate, secondDate, timeZone) {
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
+        const effectiveTimeZone = timeZone || this.TIMEZONE;
+        return Math.abs(dateFns.differenceInCalendarYears(new tz.TZDate(first, effectiveTimeZone), new tz.TZDate(second, effectiveTimeZone)));
+    }
+    static hoursInBetween(firstDate, secondDate) {
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
+        return Math.abs(dateFns.differenceInHours(first, second));
+    }
+    static secondsInBetween(firstDate, secondDate) {
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
+        return Math.abs(dateFns.differenceInSeconds(first, second));
     }
     static compareDates(firstDate, secondDate) {
-        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;
-        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
         return dateFns.compareAsc(first, second);
     }
-    static addDuration(date, duration) {
-        const normalizedDate = typeof date === 'number' ? new Date(date) : date;
-        return dateFns.add(normalizedDate, duration);
+    static addDuration(date, duration, timeZone) {
+        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;
+        const effectiveTimeZone = timeZone || this.TIMEZONE;
+        return dateFns.add(new tz.TZDate(normalizedDate, effectiveTimeZone), duration);
     }
     /**
      * Determines whether a given year is a leap year.

package/dist/cjs/utils/date/DateUtil.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"DateUtil.cjs","sources":["../../../../src/utils/date/DateUtil.ts"],"sourcesContent":["import { TZDate } from '@date-fns/tz';\nimport { add, compareAsc, differenceInCalendarDays, differenceInCalendarMonths, differenceInCalendarYears, Duration, endOfDay, format, isLeapYear, isValid, parse, startOfDay } from 'date-fns';\nimport { IllegalArgumentException } from '../../exceptions';\n\n/**\n * Utility class for date and time operations. Provides methods for parsing,\n * formatting, and performing calculations with dates and times.\n */\nexport class DateUtil {\n\n    static readonly ISO_8601_FORMAT = \"yyyy-MM-dd'T'HH:mm:ss.SSSxxx\"\n\n    /**\n     * Gets the current date and time in the specified time zone.\n     * @param timeZone The IANA time zone identifier.\n     * @returns Current date and time in the specified time zone.\n     */\n    static now(timeZone: string): Date {\n        return new TZDate(new Date(), timeZone);\n    }\n\n    /**\n     * Gets the current time in milliseconds since the Unix epoch.\n     * @returns Current time in milliseconds.\n     */\n    static nowInMillis(): number {\n        return Date.now();\n    }\n\n    /**\n     * Parses a date string into a Date object.\n     * @param dateString The date string to parse.\n     * @param dateFormat The format of the date string (default: ISO_8601_FORMAT).\n     * @param timeZone The IANA time zone identifier.\n     * @throws {IllegalArgumentException} If the date string is invalid.\n     * @returns Parsed Date object.\n     */\n    static readDate(dateString: string, dateFormat = this.ISO_8601_FORMAT, timeZone: string): Date {\n        const date = parse(dateString, dateFormat, TZDate.tz(timeZone));\n        if (!isValid(date)) {\n            throw new IllegalArgumentException('Invalid date string or date format');\n        }\n        return date;\n    }\n\n    /**\n     * Formats a Date or timestamp into a string.\n     * @param date The date or timestamp to format.\n     * @param timeZone The IANA time zone identifier.\n     * @param dateFormat The desired output format (default: ISO_8601_FORMAT).\n     * @returns Formatted date string.\n     */\n    static printDate(date: Date, timeZone: string, dateFormat?: string): string;\n    static printDate(date: number, timeZone: string, dateFormat?: string): string;\n    static printDate(date: Date | number, timeZone: string, dateFormat: string = this.ISO_8601_FORMAT): string {\n        const normalizedDate = typeof date === 'number' ? new Date(date) : date;\n        return format(new TZDate(normalizedDate, timeZone), dateFormat);\n    }\n\n    /**\n     * Gets the start of the day for a given date or timestamp.\n     * @param date The date or timestamp to calculate from.\n     * @param timeZone The IANA time zone identifier.\n     * @returns The start of the day as a Date object.\n     */\n    static getStartOfDay(date: Date, timeZone: string): Date;\n    static getStartOfDay(date: number, timeZone: string): Date;\n    static getStartOfDay(date: Date | number, timeZone: string): Date {\n        const normalizedDate = typeof date === 'number' ? new Date(date) : date;\n        return startOfDay(new TZDate(normalizedDate, timeZone));\n    }\n\n    /**\n     * Gets the end of the day for a given date or timestamp.\n     * @param date The date or timestamp to calculate from.\n     * @param timeZone The IANA time zone identifier.\n     * @returns The end of the day as a Date object.\n     */\n    static getEndOfDay(date: Date, timeZone: string): Date;\n    static getEndOfDay(date: number, timeZone: string): Date;\n    static getEndOfDay(date: Date | number, timeZone: string): Date {\n        const normalizedDate = typeof date === 'number' ? new Date(date) : date;\n        return endOfDay(new TZDate(normalizedDate, timeZone));\n    }\n\n    /**\n     * Checks if a date string is valid according to the specified format.\n     * @param dateString The date string to validate.\n     * @param dateFormat Optional date format (default: ISO_8601_FORMAT).\n     * @returns True if the date is valid, false otherwise.\n     */\n    static isValidDate(dateString: string, dateFormat?: string): boolean {\n        try {\n            DateUtil.readDate(dateString, dateFormat, \"UTC\");\n            return true;\n            // eslint-disable-next-line @typescript-eslint/no-unused-vars\n        } catch (error) {\n            return false;\n        }\n    }\n\n    /**\n     * Calculates the absolute number of days between two dates or timestamps.\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns Number of days between the two dates.\n     */\n    static daysInBetween(firstDate: Date, secondDate: Date): number;\n    static daysInBetween(firstDate: number, secondDate: number): number;\n    static daysInBetween(firstDate: Date | number, secondDate: Date | number): number {\n        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;\n        return Math.abs(differenceInCalendarDays(first, second));\n    }\n\n    /**\n * Calculates the absolute number of months between two dates or timestamps.\n * @param firstDate The first date or timestamp.\n * @param secondDate The second date or timestamp.\n * @returns The number of months between the two dates.\n */\n    static monthsInBetween(firstDate: Date, secondDate: Date): number;\n    static monthsInBetween(firstDate: number, secondDate: number): number;\n    static monthsInBetween(firstDate: Date | number, secondDate: Date | number): number {\n        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;\n        return Math.abs(differenceInCalendarMonths(first, second));\n    }\n\n    /**\n     * Calculates the absolute number of years between two dates or timestamps.\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns The number of years between the two dates.\n     */\n    static yearsInBetween(firstDate: Date, secondDate: Date): number;\n    static yearsInBetween(firstDate: number, secondDate: number): number;\n    static yearsInBetween(firstDate: Date | number, secondDate: Date | number): number {\n        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;\n        return Math.abs(differenceInCalendarYears(first, second));\n    }\n\n    /**\n     * Compares two dates or timestamps.\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns `-1` if the first date is earlier, `1` if it is later, or `0` if the two dates are equal.\n     */\n    static compareDates(firstDate: Date, secondDate: Date): -1 | 0 | 1;\n    static compareDates(firstDate: number, secondDate: number): -1 | 0 | 1;\n    static compareDates(firstDate: Date | number, secondDate: Date | number): -1 | 0 | 1 {\n        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;\n\n        return compareAsc(first, second) as -1 | 0 | 1;\n    }\n\n    /**\n     * Adds a duration (e.g., days, months, years) to a given date or timestamp.\n     * @param date The base date or timestamp to which the duration will be added.\n     * @param duration An object specifying the duration (e.g., `{ days: 1, months: 2 }`).\n     * @returns A new Date object with the duration added.\n     */\n    static addDuration(date: Date, duration: Duration): Date;\n    static addDuration(date: number, duration: Duration): Date;\n    static addDuration(date: Date | number, duration: Duration): Date {\n        const normalizedDate = typeof date === 'number' ? new Date(date) : date;\n        return add(normalizedDate, duration);\n    }\n\n    /**\n     * Determines whether a given year is a leap year.\n     * @param year The year to check.\n     * @returns `true` if the year is a leap year, otherwise `false`.\n     */\n    static isLeapYear(year: number): boolean {\n        return isLeapYear(DateUtil.readDate(year.toString(), 'yyyy', \"UTC\"));\n    }\n\n\n    /**\n     * Converts a timestamp (in milliseconds) to a Date object.\n     * @param milliseconds The timestamp in milliseconds since the Unix epoch.\n     * @returns A Date object representing the provided timestamp.\n     */\n    static fromMillis(milliseconds: number): Date {\n        return new Date(milliseconds);\n    }\n\n    /**\n     * Converts a Date object to a timestamp (in milliseconds).\n     * @param date The Date object to convert.\n     * @returns The timestamp in milliseconds since the Unix epoch.\n     */\n    static toMillis(date: Date): number {\n        return date.getTime();\n    }\n}\n"],"names":["TZDate","parse","isValid","IllegalArgumentException","format","startOfDay","endOfDay","differenceInCalendarDays","differenceInCalendarMonths","differenceInCalendarYears","compareAsc","add","isLeapYear"],"mappings":"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"}
+{"version":3,"file":"DateUtil.cjs","sources":["../../../../src/utils/date/DateUtil.ts"],"sourcesContent":["import { TZDate } from '@date-fns/tz';\nimport { add, compareAsc, differenceInCalendarDays, differenceInCalendarMonths, differenceInCalendarYears, differenceInHours, differenceInSeconds, Duration, endOfDay, format, isLeapYear, isValid, parse, startOfDay } from 'date-fns';\nimport { IllegalArgumentException } from '../../exceptions';\n\n/**\n * Utility class for date and time operations. Provides methods for parsing,\n * formatting, and performing calculations with dates and times.\n */\nexport class DateUtil {\n\n    static readonly ISO_8601_FORMAT = \"yyyy-MM-dd'T'HH:mm:ss.SSSxxx\"\n    static readonly TIMEZONE = \"UTC\"\n\n    /**\n     * Gets the current date and time in the specified time zone.\n     * @param timeZone The IANA time zone identifier.\n     * @returns Current date and time in the specified time zone.\n     */\n    static now(timeZone: string): Date {\n        return new TZDate(new Date(), timeZone);\n    }\n\n    /**\n     * Gets the current time in milliseconds since the Unix epoch.\n     * @returns Current time in milliseconds.\n     */\n    static nowInMillis(): number {\n        return Date.now();\n    }\n\n    /**\n     * Parses a date string into a Date object.\n     * @param dateString The date string to parse.\n     * @param dateFormat The format of the date string (default: ISO_8601_FORMAT).\n     * @param timeZone The IANA time zone identifier.\n     * @throws {IllegalArgumentException} If the date string is invalid.\n     * @returns Parsed Date object.\n     */\n    static readDate(dateString: string, dateFormat = this.ISO_8601_FORMAT, timeZone: string): Date {\n        const date = parse(dateString, dateFormat, TZDate.tz(timeZone));\n        if (!isValid(date)) {\n            throw new IllegalArgumentException('Invalid date string or date format');\n        }\n        return date;\n    }\n\n    /**\n     * Formats a Date or timestamp into a string.\n     * @param date The date or timestamp to format.\n     * @param timeZone The IANA time zone identifier.\n     * @param dateFormat The desired output format (default: ISO_8601_FORMAT).\n     * @returns Formatted date string.\n     */\n    static printDate(date: Date, timeZone: string, dateFormat?: string): string;\n    static printDate(date: number, timeZone: string, dateFormat?: string): string;\n    static printDate(date: Date | number, timeZone: string, dateFormat: string = this.ISO_8601_FORMAT): string {\n        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;\n        return format(new TZDate(normalizedDate, timeZone), dateFormat);\n    }\n\n    /**\n     * Gets the start of the day for a given date or timestamp.\n     * @param date The date or timestamp to calculate from.\n     * @param timeZone The IANA time zone identifier.\n     * @returns The start of the day as a Date object.\n     */\n    static getStartOfDay(date: Date, timeZone: string): Date;\n    static getStartOfDay(date: number, timeZone: string): Date;\n    static getStartOfDay(date: Date | number, timeZone: string): Date {\n        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;\n        return startOfDay(new TZDate(normalizedDate, timeZone));\n    }\n\n    /**\n     * Gets the end of the day for a given date or timestamp.\n     * @param date The date or timestamp to calculate from.\n     * @param timeZone The IANA time zone identifier.\n     * @returns The end of the day as a Date object.\n     */\n    static getEndOfDay(date: Date, timeZone: string): Date;\n    static getEndOfDay(date: number, timeZone: string): Date;\n    static getEndOfDay(date: Date | number, timeZone: string): Date {\n        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;\n        return endOfDay(new TZDate(normalizedDate, timeZone));\n    }\n\n    /**\n     * Checks if a date string is valid according to the specified format.\n     * @param dateString The date string to validate.\n     * @param dateFormat Optional date format (default: ISO_8601_FORMAT).\n     * @returns True if the date is valid, false otherwise.\n     */\n    static isValidDate(dateString: string, dateFormat?: string): boolean {\n        try {\n            DateUtil.readDate(dateString, dateFormat, \"UTC\");\n            return true;\n        } catch (error) {\n            return false;\n        }\n    }\n\n    /**\n     * Calculates the absolute number of calendar days between two dates or timestamps.\n     * Since day boundaries depend on a calendar, callers can optionally provide a time zone\n     * so the same pair of instants is interpreted consistently across machines.\n     *\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @param timeZone Optional IANA time zone identifier used for calendar comparisons.\n     * @returns Number of days between the two dates.\n     */\n    static daysInBetween(firstDate: Date, secondDate: Date, timeZone?: string): number;\n    static daysInBetween(firstDate: number, secondDate: number, timeZone?: string): number;\n    static daysInBetween(firstDate: Date | number, secondDate: Date | number, timeZone?: string): number {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n        const effectiveTimeZone = timeZone || this.TIMEZONE;\n        return Math.abs(\n            differenceInCalendarDays(\n                new TZDate(first, effectiveTimeZone),\n                new TZDate(second, effectiveTimeZone),\n            )\n        );\n    }\n\n    /**\n     * Calculates the absolute number of calendar months between two dates or timestamps.\n     * Since month boundaries depend on a calendar, callers can optionally provide a time zone\n     * so the same pair of instants is interpreted consistently across machines.\n     *\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @param timeZone Optional IANA time zone identifier used for calendar comparisons.\n     * @returns The number of months between the two dates.\n     */\n    static monthsInBetween(firstDate: Date, secondDate: Date, timeZone?: string): number;\n    static monthsInBetween(firstDate: number, secondDate: number, timeZone?: string): number;\n    static monthsInBetween(firstDate: Date | number, secondDate: Date | number, timeZone?: string): number {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n        const effectiveTimeZone = timeZone || this.TIMEZONE;\n        return Math.abs(\n            differenceInCalendarMonths(\n                new TZDate(first, effectiveTimeZone),\n                new TZDate(second, effectiveTimeZone),\n            )\n        );\n    }\n\n    /**\n     * Calculates the absolute number of calendar years between two dates or timestamps.\n     * Since year boundaries depend on a calendar, callers can optionally provide a time zone\n     * so the same pair of instants is interpreted consistently across machines.\n     *\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @param timeZone Optional IANA time zone identifier used for calendar comparisons.\n     * @returns The number of years between the two dates.\n     */\n    static yearsInBetween(firstDate: Date, secondDate: Date, timeZone?: string): number;\n    static yearsInBetween(firstDate: number, secondDate: number, timeZone?: string): number;\n    static yearsInBetween(firstDate: Date | number, secondDate: Date | number, timeZone?: string): number {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n        const effectiveTimeZone = timeZone || this.TIMEZONE;\n        return Math.abs(\n            differenceInCalendarYears(\n                new TZDate(first, effectiveTimeZone),\n                new TZDate(second, effectiveTimeZone),\n            )\n        );\n    }\n\n    /**\n     * Calculates the absolute elapsed number of hours between two dates or timestamps.\n     * This is duration-based, not calendar-based, so it is independent of time zone.\n     *\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns The number of hours between the two dates.\n     */\n    static hoursInBetween(firstDate: Date, secondDate: Date): number;\n    static hoursInBetween(firstDate: number, secondDate: number): number;\n    static hoursInBetween(firstDate: Date | number, secondDate: Date | number): number {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n        return Math.abs(differenceInHours(first, second));\n    }\n\n    /**\n     * Calculates the absolute elapsed number of seconds between two dates or timestamps.\n     * This is duration-based, not calendar-based, so it is independent of time zone.\n     *\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns The number of seconds between the two dates.\n     */\n    static secondsInBetween(firstDate: Date, secondDate: Date): number;\n    static secondsInBetween(firstDate: number, secondDate: number): number;\n    static secondsInBetween(firstDate: Date | number, secondDate: Date | number): number {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n        return Math.abs(differenceInSeconds(first, second));\n    }\n\n    /**\n     * Compares two dates or timestamps.\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns `-1` if the first date is earlier, `1` if it is later, or `0` if the two dates are equal.\n     */\n    static compareDates(firstDate: Date, secondDate: Date): -1 | 0 | 1;\n    static compareDates(firstDate: number, secondDate: number): -1 | 0 | 1;\n    static compareDates(firstDate: Date | number, secondDate: Date | number): -1 | 0 | 1 {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n\n        return compareAsc(first, second) as -1 | 0 | 1;\n    }\n\n    /**\n     * Adds a duration (e.g., days, months, years) to a given date or timestamp.\n     * When a time zone is provided, the duration is applied using calendar arithmetic\n     * in that time zone so month-end or day-boundary business rules stay aligned locally.\n     *\n     * @param date The base date or timestamp to which the duration will be added.\n     * @param duration An object specifying the duration (e.g., `{ days: 1, months: 2 }`).\n     * @param timeZone Optional IANA time zone identifier used for calendar math.\n     * @returns A new Date object with the duration added.\n     */\n    static addDuration(date: Date, duration: Duration, timeZone?: string): Date;\n    static addDuration(date: number, duration: Duration, timeZone?: string): Date;\n    static addDuration(date: Date | number, duration: Duration, timeZone?: string): Date {\n        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;\n        const effectiveTimeZone = timeZone || this.TIMEZONE;\n        return add(new TZDate(normalizedDate, effectiveTimeZone), duration);\n    }\n\n    /**\n     * Determines whether a given year is a leap year.\n     * @param year The year to check.\n     * @returns `true` if the year is a leap year, otherwise `false`.\n     */\n    static isLeapYear(year: number): boolean {\n        return isLeapYear(DateUtil.readDate(year.toString(), 'yyyy', \"UTC\"));\n    }\n\n\n    /**\n     * Converts a timestamp (in milliseconds) to a Date object.\n     * @param milliseconds The timestamp in milliseconds since the Unix epoch.\n     * @returns A Date object representing the provided timestamp.\n     */\n    static fromMillis(milliseconds: number): Date {\n        return new Date(milliseconds);\n    }\n\n    /**\n     * Converts a Date object to a timestamp (in milliseconds).\n     * @param date The Date object to convert.\n     * @returns The timestamp in milliseconds since the Unix epoch.\n     */\n    static toMillis(date: Date): number {\n        return date.getTime();\n    }\n}\n"],"names":["TZDate","parse","isValid","IllegalArgumentException","format","startOfDay","endOfDay","differenceInCalendarDays","differenceInCalendarMonths","differenceInCalendarYears","differenceInHours","differenceInSeconds","compareAsc","add","isLeapYear"],"mappings":"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"}

package/dist/esm/utils/date/DateUtil.js

@@ -1,5 +1,5 @@
 import { TZDate } from '@date-fns/tz';
-import { parse, isValid, format, startOfDay, endOfDay, differenceInCalendarDays, differenceInCalendarMonths, differenceInCalendarYears, compareAsc, add, isLeapYear } from 'date-fns';
+import { parse, isValid, format, startOfDay, endOfDay, differenceInCalendarDays, differenceInCalendarMonths, differenceInCalendarYears, differenceInHours, differenceInSeconds, compareAsc, add, isLeapYear } from 'date-fns';
 import { IllegalArgumentException } from '../../exceptions/IllegalArgumentException.js';
 
 /**
@@ -8,6 +8,7 @@ import { IllegalArgumentException } from '../../exceptions/IllegalArgumentExcept
  */
 class DateUtil {
     static { this.ISO_8601_FORMAT = "yyyy-MM-dd'T'HH:mm:ss.SSSxxx"; }
+    static { this.TIMEZONE = "UTC"; }
     /**
      * Gets the current date and time in the specified time zone.
      * @param timeZone The IANA time zone identifier.
@@ -39,15 +40,15 @@ class DateUtil {
         return date;
     }
     static printDate(date, timeZone, dateFormat = this.ISO_8601_FORMAT) {
-        const normalizedDate = typeof date === 'number' ? new Date(date) : date;
+        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;
         return format(new TZDate(normalizedDate, timeZone), dateFormat);
     }
     static getStartOfDay(date, timeZone) {
-        const normalizedDate = typeof date === 'number' ? new Date(date) : date;
+        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;
         return startOfDay(new TZDate(normalizedDate, timeZone));
     }
     static getEndOfDay(date, timeZone) {
-        const normalizedDate = typeof date === 'number' ? new Date(date) : date;
+        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;
         return endOfDay(new TZDate(normalizedDate, timeZone));
     }
     /**
@@ -60,35 +61,48 @@ class DateUtil {
         try {
             DateUtil.readDate(dateString, dateFormat, "UTC");
             return true;
-            // eslint-disable-next-line @typescript-eslint/no-unused-vars
         }
         catch (error) {
             return false;
         }
     }
-    static daysInBetween(firstDate, secondDate) {
-        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;
-        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;
-        return Math.abs(differenceInCalendarDays(first, second));
+    static daysInBetween(firstDate, secondDate, timeZone) {
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
+        const effectiveTimeZone = timeZone || this.TIMEZONE;
+        return Math.abs(differenceInCalendarDays(new TZDate(first, effectiveTimeZone), new TZDate(second, effectiveTimeZone)));
     }
-    static monthsInBetween(firstDate, secondDate) {
-        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;
-        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;
-        return Math.abs(differenceInCalendarMonths(first, second));
+    static monthsInBetween(firstDate, secondDate, timeZone) {
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
+        const effectiveTimeZone = timeZone || this.TIMEZONE;
+        return Math.abs(differenceInCalendarMonths(new TZDate(first, effectiveTimeZone), new TZDate(second, effectiveTimeZone)));
     }
-    static yearsInBetween(firstDate, secondDate) {
-        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;
-        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;
-        return Math.abs(differenceInCalendarYears(first, second));
+    static yearsInBetween(firstDate, secondDate, timeZone) {
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
+        const effectiveTimeZone = timeZone || this.TIMEZONE;
+        return Math.abs(differenceInCalendarYears(new TZDate(first, effectiveTimeZone), new TZDate(second, effectiveTimeZone)));
+    }
+    static hoursInBetween(firstDate, secondDate) {
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
+        return Math.abs(differenceInHours(first, second));
+    }
+    static secondsInBetween(firstDate, secondDate) {
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
+        return Math.abs(differenceInSeconds(first, second));
     }
     static compareDates(firstDate, secondDate) {
-        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;
-        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;
+        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;
+        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;
         return compareAsc(first, second);
     }
-    static addDuration(date, duration) {
-        const normalizedDate = typeof date === 'number' ? new Date(date) : date;
-        return add(normalizedDate, duration);
+    static addDuration(date, duration, timeZone) {
+        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;
+        const effectiveTimeZone = timeZone || this.TIMEZONE;
+        return add(new TZDate(normalizedDate, effectiveTimeZone), duration);
     }
     /**
      * Determines whether a given year is a leap year.

package/dist/esm/utils/date/DateUtil.js.map

@@ -1 +1 @@
-{"version":3,"file":"DateUtil.js","sources":["../../../../src/utils/date/DateUtil.ts"],"sourcesContent":["import { TZDate } from '@date-fns/tz';\nimport { add, compareAsc, differenceInCalendarDays, differenceInCalendarMonths, differenceInCalendarYears, Duration, endOfDay, format, isLeapYear, isValid, parse, startOfDay } from 'date-fns';\nimport { IllegalArgumentException } from '../../exceptions';\n\n/**\n * Utility class for date and time operations. Provides methods for parsing,\n * formatting, and performing calculations with dates and times.\n */\nexport class DateUtil {\n\n    static readonly ISO_8601_FORMAT = \"yyyy-MM-dd'T'HH:mm:ss.SSSxxx\"\n\n    /**\n     * Gets the current date and time in the specified time zone.\n     * @param timeZone The IANA time zone identifier.\n     * @returns Current date and time in the specified time zone.\n     */\n    static now(timeZone: string): Date {\n        return new TZDate(new Date(), timeZone);\n    }\n\n    /**\n     * Gets the current time in milliseconds since the Unix epoch.\n     * @returns Current time in milliseconds.\n     */\n    static nowInMillis(): number {\n        return Date.now();\n    }\n\n    /**\n     * Parses a date string into a Date object.\n     * @param dateString The date string to parse.\n     * @param dateFormat The format of the date string (default: ISO_8601_FORMAT).\n     * @param timeZone The IANA time zone identifier.\n     * @throws {IllegalArgumentException} If the date string is invalid.\n     * @returns Parsed Date object.\n     */\n    static readDate(dateString: string, dateFormat = this.ISO_8601_FORMAT, timeZone: string): Date {\n        const date = parse(dateString, dateFormat, TZDate.tz(timeZone));\n        if (!isValid(date)) {\n            throw new IllegalArgumentException('Invalid date string or date format');\n        }\n        return date;\n    }\n\n    /**\n     * Formats a Date or timestamp into a string.\n     * @param date The date or timestamp to format.\n     * @param timeZone The IANA time zone identifier.\n     * @param dateFormat The desired output format (default: ISO_8601_FORMAT).\n     * @returns Formatted date string.\n     */\n    static printDate(date: Date, timeZone: string, dateFormat?: string): string;\n    static printDate(date: number, timeZone: string, dateFormat?: string): string;\n    static printDate(date: Date | number, timeZone: string, dateFormat: string = this.ISO_8601_FORMAT): string {\n        const normalizedDate = typeof date === 'number' ? new Date(date) : date;\n        return format(new TZDate(normalizedDate, timeZone), dateFormat);\n    }\n\n    /**\n     * Gets the start of the day for a given date or timestamp.\n     * @param date The date or timestamp to calculate from.\n     * @param timeZone The IANA time zone identifier.\n     * @returns The start of the day as a Date object.\n     */\n    static getStartOfDay(date: Date, timeZone: string): Date;\n    static getStartOfDay(date: number, timeZone: string): Date;\n    static getStartOfDay(date: Date | number, timeZone: string): Date {\n        const normalizedDate = typeof date === 'number' ? new Date(date) : date;\n        return startOfDay(new TZDate(normalizedDate, timeZone));\n    }\n\n    /**\n     * Gets the end of the day for a given date or timestamp.\n     * @param date The date or timestamp to calculate from.\n     * @param timeZone The IANA time zone identifier.\n     * @returns The end of the day as a Date object.\n     */\n    static getEndOfDay(date: Date, timeZone: string): Date;\n    static getEndOfDay(date: number, timeZone: string): Date;\n    static getEndOfDay(date: Date | number, timeZone: string): Date {\n        const normalizedDate = typeof date === 'number' ? new Date(date) : date;\n        return endOfDay(new TZDate(normalizedDate, timeZone));\n    }\n\n    /**\n     * Checks if a date string is valid according to the specified format.\n     * @param dateString The date string to validate.\n     * @param dateFormat Optional date format (default: ISO_8601_FORMAT).\n     * @returns True if the date is valid, false otherwise.\n     */\n    static isValidDate(dateString: string, dateFormat?: string): boolean {\n        try {\n            DateUtil.readDate(dateString, dateFormat, \"UTC\");\n            return true;\n            // eslint-disable-next-line @typescript-eslint/no-unused-vars\n        } catch (error) {\n            return false;\n        }\n    }\n\n    /**\n     * Calculates the absolute number of days between two dates or timestamps.\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns Number of days between the two dates.\n     */\n    static daysInBetween(firstDate: Date, secondDate: Date): number;\n    static daysInBetween(firstDate: number, secondDate: number): number;\n    static daysInBetween(firstDate: Date | number, secondDate: Date | number): number {\n        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;\n        return Math.abs(differenceInCalendarDays(first, second));\n    }\n\n    /**\n * Calculates the absolute number of months between two dates or timestamps.\n * @param firstDate The first date or timestamp.\n * @param secondDate The second date or timestamp.\n * @returns The number of months between the two dates.\n */\n    static monthsInBetween(firstDate: Date, secondDate: Date): number;\n    static monthsInBetween(firstDate: number, secondDate: number): number;\n    static monthsInBetween(firstDate: Date | number, secondDate: Date | number): number {\n        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;\n        return Math.abs(differenceInCalendarMonths(first, second));\n    }\n\n    /**\n     * Calculates the absolute number of years between two dates or timestamps.\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns The number of years between the two dates.\n     */\n    static yearsInBetween(firstDate: Date, secondDate: Date): number;\n    static yearsInBetween(firstDate: number, secondDate: number): number;\n    static yearsInBetween(firstDate: Date | number, secondDate: Date | number): number {\n        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;\n        return Math.abs(differenceInCalendarYears(first, second));\n    }\n\n    /**\n     * Compares two dates or timestamps.\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns `-1` if the first date is earlier, `1` if it is later, or `0` if the two dates are equal.\n     */\n    static compareDates(firstDate: Date, secondDate: Date): -1 | 0 | 1;\n    static compareDates(firstDate: number, secondDate: number): -1 | 0 | 1;\n    static compareDates(firstDate: Date | number, secondDate: Date | number): -1 | 0 | 1 {\n        const first = typeof firstDate === 'number' ? new Date(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? new Date(secondDate) : secondDate;\n\n        return compareAsc(first, second) as -1 | 0 | 1;\n    }\n\n    /**\n     * Adds a duration (e.g., days, months, years) to a given date or timestamp.\n     * @param date The base date or timestamp to which the duration will be added.\n     * @param duration An object specifying the duration (e.g., `{ days: 1, months: 2 }`).\n     * @returns A new Date object with the duration added.\n     */\n    static addDuration(date: Date, duration: Duration): Date;\n    static addDuration(date: number, duration: Duration): Date;\n    static addDuration(date: Date | number, duration: Duration): Date {\n        const normalizedDate = typeof date === 'number' ? new Date(date) : date;\n        return add(normalizedDate, duration);\n    }\n\n    /**\n     * Determines whether a given year is a leap year.\n     * @param year The year to check.\n     * @returns `true` if the year is a leap year, otherwise `false`.\n     */\n    static isLeapYear(year: number): boolean {\n        return isLeapYear(DateUtil.readDate(year.toString(), 'yyyy', \"UTC\"));\n    }\n\n\n    /**\n     * Converts a timestamp (in milliseconds) to a Date object.\n     * @param milliseconds The timestamp in milliseconds since the Unix epoch.\n     * @returns A Date object representing the provided timestamp.\n     */\n    static fromMillis(milliseconds: number): Date {\n        return new Date(milliseconds);\n    }\n\n    /**\n     * Converts a Date object to a timestamp (in milliseconds).\n     * @param date The Date object to convert.\n     * @returns The timestamp in milliseconds since the Unix epoch.\n     */\n    static toMillis(date: Date): number {\n        return date.getTime();\n    }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"DateUtil.js","sources":["../../../../src/utils/date/DateUtil.ts"],"sourcesContent":["import { TZDate } from '@date-fns/tz';\nimport { add, compareAsc, differenceInCalendarDays, differenceInCalendarMonths, differenceInCalendarYears, differenceInHours, differenceInSeconds, Duration, endOfDay, format, isLeapYear, isValid, parse, startOfDay } from 'date-fns';\nimport { IllegalArgumentException } from '../../exceptions';\n\n/**\n * Utility class for date and time operations. Provides methods for parsing,\n * formatting, and performing calculations with dates and times.\n */\nexport class DateUtil {\n\n    static readonly ISO_8601_FORMAT = \"yyyy-MM-dd'T'HH:mm:ss.SSSxxx\"\n    static readonly TIMEZONE = \"UTC\"\n\n    /**\n     * Gets the current date and time in the specified time zone.\n     * @param timeZone The IANA time zone identifier.\n     * @returns Current date and time in the specified time zone.\n     */\n    static now(timeZone: string): Date {\n        return new TZDate(new Date(), timeZone);\n    }\n\n    /**\n     * Gets the current time in milliseconds since the Unix epoch.\n     * @returns Current time in milliseconds.\n     */\n    static nowInMillis(): number {\n        return Date.now();\n    }\n\n    /**\n     * Parses a date string into a Date object.\n     * @param dateString The date string to parse.\n     * @param dateFormat The format of the date string (default: ISO_8601_FORMAT).\n     * @param timeZone The IANA time zone identifier.\n     * @throws {IllegalArgumentException} If the date string is invalid.\n     * @returns Parsed Date object.\n     */\n    static readDate(dateString: string, dateFormat = this.ISO_8601_FORMAT, timeZone: string): Date {\n        const date = parse(dateString, dateFormat, TZDate.tz(timeZone));\n        if (!isValid(date)) {\n            throw new IllegalArgumentException('Invalid date string or date format');\n        }\n        return date;\n    }\n\n    /**\n     * Formats a Date or timestamp into a string.\n     * @param date The date or timestamp to format.\n     * @param timeZone The IANA time zone identifier.\n     * @param dateFormat The desired output format (default: ISO_8601_FORMAT).\n     * @returns Formatted date string.\n     */\n    static printDate(date: Date, timeZone: string, dateFormat?: string): string;\n    static printDate(date: number, timeZone: string, dateFormat?: string): string;\n    static printDate(date: Date | number, timeZone: string, dateFormat: string = this.ISO_8601_FORMAT): string {\n        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;\n        return format(new TZDate(normalizedDate, timeZone), dateFormat);\n    }\n\n    /**\n     * Gets the start of the day for a given date or timestamp.\n     * @param date The date or timestamp to calculate from.\n     * @param timeZone The IANA time zone identifier.\n     * @returns The start of the day as a Date object.\n     */\n    static getStartOfDay(date: Date, timeZone: string): Date;\n    static getStartOfDay(date: number, timeZone: string): Date;\n    static getStartOfDay(date: Date | number, timeZone: string): Date {\n        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;\n        return startOfDay(new TZDate(normalizedDate, timeZone));\n    }\n\n    /**\n     * Gets the end of the day for a given date or timestamp.\n     * @param date The date or timestamp to calculate from.\n     * @param timeZone The IANA time zone identifier.\n     * @returns The end of the day as a Date object.\n     */\n    static getEndOfDay(date: Date, timeZone: string): Date;\n    static getEndOfDay(date: number, timeZone: string): Date;\n    static getEndOfDay(date: Date | number, timeZone: string): Date {\n        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;\n        return endOfDay(new TZDate(normalizedDate, timeZone));\n    }\n\n    /**\n     * Checks if a date string is valid according to the specified format.\n     * @param dateString The date string to validate.\n     * @param dateFormat Optional date format (default: ISO_8601_FORMAT).\n     * @returns True if the date is valid, false otherwise.\n     */\n    static isValidDate(dateString: string, dateFormat?: string): boolean {\n        try {\n            DateUtil.readDate(dateString, dateFormat, \"UTC\");\n            return true;\n        } catch (error) {\n            return false;\n        }\n    }\n\n    /**\n     * Calculates the absolute number of calendar days between two dates or timestamps.\n     * Since day boundaries depend on a calendar, callers can optionally provide a time zone\n     * so the same pair of instants is interpreted consistently across machines.\n     *\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @param timeZone Optional IANA time zone identifier used for calendar comparisons.\n     * @returns Number of days between the two dates.\n     */\n    static daysInBetween(firstDate: Date, secondDate: Date, timeZone?: string): number;\n    static daysInBetween(firstDate: number, secondDate: number, timeZone?: string): number;\n    static daysInBetween(firstDate: Date | number, secondDate: Date | number, timeZone?: string): number {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n        const effectiveTimeZone = timeZone || this.TIMEZONE;\n        return Math.abs(\n            differenceInCalendarDays(\n                new TZDate(first, effectiveTimeZone),\n                new TZDate(second, effectiveTimeZone),\n            )\n        );\n    }\n\n    /**\n     * Calculates the absolute number of calendar months between two dates or timestamps.\n     * Since month boundaries depend on a calendar, callers can optionally provide a time zone\n     * so the same pair of instants is interpreted consistently across machines.\n     *\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @param timeZone Optional IANA time zone identifier used for calendar comparisons.\n     * @returns The number of months between the two dates.\n     */\n    static monthsInBetween(firstDate: Date, secondDate: Date, timeZone?: string): number;\n    static monthsInBetween(firstDate: number, secondDate: number, timeZone?: string): number;\n    static monthsInBetween(firstDate: Date | number, secondDate: Date | number, timeZone?: string): number {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n        const effectiveTimeZone = timeZone || this.TIMEZONE;\n        return Math.abs(\n            differenceInCalendarMonths(\n                new TZDate(first, effectiveTimeZone),\n                new TZDate(second, effectiveTimeZone),\n            )\n        );\n    }\n\n    /**\n     * Calculates the absolute number of calendar years between two dates or timestamps.\n     * Since year boundaries depend on a calendar, callers can optionally provide a time zone\n     * so the same pair of instants is interpreted consistently across machines.\n     *\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @param timeZone Optional IANA time zone identifier used for calendar comparisons.\n     * @returns The number of years between the two dates.\n     */\n    static yearsInBetween(firstDate: Date, secondDate: Date, timeZone?: string): number;\n    static yearsInBetween(firstDate: number, secondDate: number, timeZone?: string): number;\n    static yearsInBetween(firstDate: Date | number, secondDate: Date | number, timeZone?: string): number {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n        const effectiveTimeZone = timeZone || this.TIMEZONE;\n        return Math.abs(\n            differenceInCalendarYears(\n                new TZDate(first, effectiveTimeZone),\n                new TZDate(second, effectiveTimeZone),\n            )\n        );\n    }\n\n    /**\n     * Calculates the absolute elapsed number of hours between two dates or timestamps.\n     * This is duration-based, not calendar-based, so it is independent of time zone.\n     *\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns The number of hours between the two dates.\n     */\n    static hoursInBetween(firstDate: Date, secondDate: Date): number;\n    static hoursInBetween(firstDate: number, secondDate: number): number;\n    static hoursInBetween(firstDate: Date | number, secondDate: Date | number): number {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n        return Math.abs(differenceInHours(first, second));\n    }\n\n    /**\n     * Calculates the absolute elapsed number of seconds between two dates or timestamps.\n     * This is duration-based, not calendar-based, so it is independent of time zone.\n     *\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns The number of seconds between the two dates.\n     */\n    static secondsInBetween(firstDate: Date, secondDate: Date): number;\n    static secondsInBetween(firstDate: number, secondDate: number): number;\n    static secondsInBetween(firstDate: Date | number, secondDate: Date | number): number {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n        return Math.abs(differenceInSeconds(first, second));\n    }\n\n    /**\n     * Compares two dates or timestamps.\n     * @param firstDate The first date or timestamp.\n     * @param secondDate The second date or timestamp.\n     * @returns `-1` if the first date is earlier, `1` if it is later, or `0` if the two dates are equal.\n     */\n    static compareDates(firstDate: Date, secondDate: Date): -1 | 0 | 1;\n    static compareDates(firstDate: number, secondDate: number): -1 | 0 | 1;\n    static compareDates(firstDate: Date | number, secondDate: Date | number): -1 | 0 | 1 {\n        const first = typeof firstDate === 'number' ? DateUtil.fromMillis(firstDate) : firstDate;\n        const second = typeof secondDate === 'number' ? DateUtil.fromMillis(secondDate) : secondDate;\n\n        return compareAsc(first, second) as -1 | 0 | 1;\n    }\n\n    /**\n     * Adds a duration (e.g., days, months, years) to a given date or timestamp.\n     * When a time zone is provided, the duration is applied using calendar arithmetic\n     * in that time zone so month-end or day-boundary business rules stay aligned locally.\n     *\n     * @param date The base date or timestamp to which the duration will be added.\n     * @param duration An object specifying the duration (e.g., `{ days: 1, months: 2 }`).\n     * @param timeZone Optional IANA time zone identifier used for calendar math.\n     * @returns A new Date object with the duration added.\n     */\n    static addDuration(date: Date, duration: Duration, timeZone?: string): Date;\n    static addDuration(date: number, duration: Duration, timeZone?: string): Date;\n    static addDuration(date: Date | number, duration: Duration, timeZone?: string): Date {\n        const normalizedDate = typeof date === 'number' ? DateUtil.fromMillis(date) : date;\n        const effectiveTimeZone = timeZone || this.TIMEZONE;\n        return add(new TZDate(normalizedDate, effectiveTimeZone), duration);\n    }\n\n    /**\n     * Determines whether a given year is a leap year.\n     * @param year The year to check.\n     * @returns `true` if the year is a leap year, otherwise `false`.\n     */\n    static isLeapYear(year: number): boolean {\n        return isLeapYear(DateUtil.readDate(year.toString(), 'yyyy', \"UTC\"));\n    }\n\n\n    /**\n     * Converts a timestamp (in milliseconds) to a Date object.\n     * @param milliseconds The timestamp in milliseconds since the Unix epoch.\n     * @returns A Date object representing the provided timestamp.\n     */\n    static fromMillis(milliseconds: number): Date {\n        return new Date(milliseconds);\n    }\n\n    /**\n     * Converts a Date object to a timestamp (in milliseconds).\n     * @param date The Date object to convert.\n     * @returns The timestamp in milliseconds since the Unix epoch.\n     */\n    static toMillis(date: Date): number {\n        return date.getTime();\n    }\n}\n"],"names":[],"mappings":"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"}

package/dist/types/src/utils/date/DateUtil.d.ts

@@ -6,6 +6,7 @@ import { Duration } from 'date-fns';
  */
 declare class DateUtil {
     static readonly ISO_8601_FORMAT = "yyyy-MM-dd'T'HH:mm:ss.SSSxxx";
+    static readonly TIMEZONE = "UTC";
     /**
      * Gets the current date and time in the specified time zone.
      * @param timeZone The IANA time zone identifier.
@@ -59,29 +60,61 @@ declare class DateUtil {
      */
     static isValidDate(dateString: string, dateFormat?: string): boolean;
     /**
-     * Calculates the absolute number of days between two dates or timestamps.
+     * Calculates the absolute number of calendar days between two dates or timestamps.
+     * Since day boundaries depend on a calendar, callers can optionally provide a time zone
+     * so the same pair of instants is interpreted consistently across machines.
+     *
      * @param firstDate The first date or timestamp.
      * @param secondDate The second date or timestamp.
+     * @param timeZone Optional IANA time zone identifier used for calendar comparisons.
      * @returns Number of days between the two dates.
      */
-    static daysInBetween(firstDate: Date, secondDate: Date): number;
-    static daysInBetween(firstDate: number, secondDate: number): number;
+    static daysInBetween(firstDate: Date, secondDate: Date, timeZone?: string): number;
+    static daysInBetween(firstDate: number, secondDate: number, timeZone?: string): number;
     /**
- * Calculates the absolute number of months between two dates or timestamps.
- * @param firstDate The first date or timestamp.
- * @param secondDate The second date or timestamp.
- * @returns The number of months between the two dates.
- */
-    static monthsInBetween(firstDate: Date, secondDate: Date): number;
-    static monthsInBetween(firstDate: number, secondDate: number): number;
+     * Calculates the absolute number of calendar months between two dates or timestamps.
+     * Since month boundaries depend on a calendar, callers can optionally provide a time zone
+     * so the same pair of instants is interpreted consistently across machines.
+     *
+     * @param firstDate The first date or timestamp.
+     * @param secondDate The second date or timestamp.
+     * @param timeZone Optional IANA time zone identifier used for calendar comparisons.
+     * @returns The number of months between the two dates.
+     */
+    static monthsInBetween(firstDate: Date, secondDate: Date, timeZone?: string): number;
+    static monthsInBetween(firstDate: number, secondDate: number, timeZone?: string): number;
     /**
-     * Calculates the absolute number of years between two dates or timestamps.
+     * Calculates the absolute number of calendar years between two dates or timestamps.
+     * Since year boundaries depend on a calendar, callers can optionally provide a time zone
+     * so the same pair of instants is interpreted consistently across machines.
+     *
      * @param firstDate The first date or timestamp.
      * @param secondDate The second date or timestamp.
+     * @param timeZone Optional IANA time zone identifier used for calendar comparisons.
      * @returns The number of years between the two dates.
      */
-    static yearsInBetween(firstDate: Date, secondDate: Date): number;
-    static yearsInBetween(firstDate: number, secondDate: number): number;
+    static yearsInBetween(firstDate: Date, secondDate: Date, timeZone?: string): number;
+    static yearsInBetween(firstDate: number, secondDate: number, timeZone?: string): number;
+    /**
+     * Calculates the absolute elapsed number of hours between two dates or timestamps.
+     * This is duration-based, not calendar-based, so it is independent of time zone.
+     *
+     * @param firstDate The first date or timestamp.
+     * @param secondDate The second date or timestamp.
+     * @returns The number of hours between the two dates.
+     */
+    static hoursInBetween(firstDate: Date, secondDate: Date): number;
+    static hoursInBetween(firstDate: number, secondDate: number): number;
+    /**
+     * Calculates the absolute elapsed number of seconds between two dates or timestamps.
+     * This is duration-based, not calendar-based, so it is independent of time zone.
+     *
+     * @param firstDate The first date or timestamp.
+     * @param secondDate The second date or timestamp.
+     * @returns The number of seconds between the two dates.
+     */
+    static secondsInBetween(firstDate: Date, secondDate: Date): number;
+    static secondsInBetween(firstDate: number, secondDate: number): number;
     /**
      * Compares two dates or timestamps.
      * @param firstDate The first date or timestamp.
@@ -92,12 +125,16 @@ declare class DateUtil {
     static compareDates(firstDate: number, secondDate: number): -1 | 0 | 1;
     /**
      * Adds a duration (e.g., days, months, years) to a given date or timestamp.
+     * When a time zone is provided, the duration is applied using calendar arithmetic
+     * in that time zone so month-end or day-boundary business rules stay aligned locally.
+     *
      * @param date The base date or timestamp to which the duration will be added.
      * @param duration An object specifying the duration (e.g., `{ days: 1, months: 2 }`).
+     * @param timeZone Optional IANA time zone identifier used for calendar math.
      * @returns A new Date object with the duration added.
      */
-    static addDuration(date: Date, duration: Duration): Date;
-    static addDuration(date: number, duration: Duration): Date;
+    static addDuration(date: Date, duration: Duration, timeZone?: string): Date;
+    static addDuration(date: number, duration: Duration, timeZone?: string): Date;
     /**
      * Determines whether a given year is a leap year.
      * @param year The year to check.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@org-quicko/core",
-	"version": "2.0.3",
+	"version": "2.0.5",
 	"description": "A library in typescript for common entities and utilities across Quicko",
 	"author": "Quicko",
 	"main": "dist/cjs/build/node/index.cjs",
@@ -9,11 +9,13 @@
 	"types": "dist/types/index.d.ts",
 	"type": "module",
 	"scripts": {
-		"clean": "rm -rf dist && npm cache clean --force",
+		"clean": "rm -rf ./dist",
+		"clean:all": "rm -rf ./node_modules ./package-lock.json ./dist && npm cache clean --force",
 		"lint": "eslint .",
 		"lint:fix": "eslint . --fix",
 		"prebuild": "npm run clean && npm run lint",
 		"build": "rollup -c",
+		"test": "set NODE_ENV=local && node --experimental-vm-modules node_modules/jest/bin/jest.js",
 		"test:date:util": "set NODE_ENV=local && node --experimental-vm-modules node_modules/jest/bin/jest.js run ./tests/DateUtil.test.ts"
 	},
 	"license": "ISC",
@@ -78,37 +80,9 @@
 		},
 		"./package.json": "./package.json"
 	},
-	"typesVersions": {
-		"*": {
-			"*": [
-				"dist/types/*"
-			],
-			"beans": [
-				"dist/types/src/beans/index.d.ts"
-			],
-			"types": [
-				"dist/types/src/types/index.d.ts"
-			],
-			"utils": [
-				"dist/types/src/utils/index.d.ts"
-			],
-			"utils/date": [
-				"dist/types/src/utils/date/index.d.ts"
-			],
-			"exceptions": [
-				"dist/types/src/exceptions/index.d.ts"
-			],
-			"logger": [
-				"dist/types/src/logger/index.d.ts"
-			]
-		}
-	},
 	"directories": {
 		"lib": "./dist"
 	},
-	"engines": {
-		"node": ">=14"
-	},
 	"dependencies": {
 		"@date-fns/tz": "^1.1.2",
 		"class-transformer": "^0.5.1",
@@ -121,6 +95,7 @@
 		"@rollup/plugin-commonjs": "^28.0.3",
 		"@rollup/plugin-node-resolve": "^16.0.1",
 		"@rollup/plugin-typescript": "^12.1.2",
+		"@types/jest": "^29.5.12",
 		"@types/node": "^22.7.0",
 		"@typescript-eslint/eslint-plugin": "^8.33.1",
 		"@typescript-eslint/parser": "^8.33.1",
@@ -129,12 +104,12 @@
 		"eslint-config-prettier": "^10.1.5",
 		"eslint-import-resolver-typescript": "^3.7.0",
 		"glob": "^11.0.2",
+		"jest": "^29.7.0",
 		"rollup": "^4.40.2",
 		"rollup-plugin-dts": "^6.2.1",
+		"rollup-plugin-node-externals": "^8.1.2",
+		"ts-jest": "^29.2.5",
 		"ts-node": "^10.9.2",
-		"typescript": "^5.6.2",
-		"@types/jest": "^29.5.12",
-		"jest": "^29.7.0",
-		"ts-jest": "^29.2.5"
+		"typescript": "^5.6.2"
 	}
-}
+}