@org-quicko/core 2.0.4 → 2.0.5

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,31 +60,45 @@ 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 number of hours between two dates or timestamps.
+     * 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.
@@ -91,7 +106,9 @@ declare class DateUtil {
     static hoursInBetween(firstDate: Date, secondDate: Date): number;
     static hoursInBetween(firstDate: number, secondDate: number): number;
     /**
-     * Calculates the absolute number of seconds between two dates or timestamps.
+     * 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.
@@ -108,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,140 +1,115 @@
-{
-	"name": "@org-quicko/core",
-	"version": "2.0.4",
-	"description": "A library in typescript for common entities and utilities across Quicko",
-	"author": "Quicko",
-	"main": "dist/cjs/build/node/index.cjs",
-	"module": "dist/esm/build/node/index.js",
-	"browser": "dist/browser/build/browser/index.js",
-	"types": "dist/types/index.d.ts",
-	"type": "module",
-	"scripts": {
-		"clean": "rm -rf dist && npm cache clean --force",
-		"lint": "eslint .",
-		"lint:fix": "eslint . --fix",
-		"prebuild": "npm run clean && npm run lint",
-		"build": "rollup -c",
-		"test:date:util": "set NODE_ENV=local && node --experimental-vm-modules node_modules/jest/bin/jest.js run ./tests/DateUtil.test.ts"
-	},
-	"license": "ISC",
-	"files": [
-		"dist/**/*"
-	],
-	"exports": {
-		".": {
-			"types": "./dist/types/index.d.ts",
-			"node": {
-				"import": "./dist/esm/build/node/index.js",
-				"require": "./dist/cjs/build/node/index.cjs"
-			},
-			"default": "./dist/browser/build/browser/index.js"
-		},
-		"./beans": {
-			"types": "./dist/types/src/beans/index.d.ts",
-			"node": {
-				"import": "./dist/esm/beans/index.js",
-				"require": "./dist/cjs/beans/index.cjs"
-			},
-			"default": "./dist/browser/beans/index.js"
-		},
-		"./types": {
-			"types": "./dist/types/src/types/index.d.ts",
-			"node": {
-				"import": "./dist/esm/types/index.js",
-				"require": "./dist/cjs/types/index.cjs"
-			},
-			"default": "./dist/browser/types/index.js"
-		},
-		"./utils": {
-			"types": "./dist/types/src/utils/index.d.ts",
-			"node": {
-				"import": "./dist/esm/utils/index.js",
-				"require": "./dist/cjs/utils/index.cjs"
-			},
-			"default": "./dist/browser/utils/index.js"
-		},
-		"./utils/date": {
-			"types": "./dist/types/src/utils/date/index.d.ts",
-			"node": {
-				"import": "./dist/esm/utils/date/index.js",
-				"require": "./dist/cjs/utils/date/index.cjs"
-			},
-			"default": "./dist/browser/utils/date/index.js"
-		},
-		"./logger": {
-			"types": "./dist/types/src/logger/index.d.ts",
-			"node": {
-				"import": "./dist/esm/logger/index.js",
-				"require": "./dist/cjs/logger/index.cjs"
-			}
-		},
-		"./exceptions": {
-			"types": "./dist/types/src/exceptions/index.d.ts",
-			"node": {
-				"import": "./dist/esm/exceptions/index.js",
-				"require": "./dist/cjs/exceptions/index.cjs"
-			},
-			"default": "./dist/browser/exceptions/index.js"
-		},
-		"./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",
-		"class-validator": "^0.14.1",
-		"date-fns": "^4.1.0",
-		"tslib": "^2.8.1",
-		"winston": "^3.17.0"
-	},
-	"devDependencies": {
-		"@rollup/plugin-commonjs": "^28.0.3",
-		"@rollup/plugin-node-resolve": "^16.0.1",
-		"@rollup/plugin-typescript": "^12.1.2",
-		"@types/node": "^22.7.0",
-		"@typescript-eslint/eslint-plugin": "^8.33.1",
-		"@typescript-eslint/parser": "^8.33.1",
-		"esbuild-plugin-eslint": "^0.3.7",
-		"eslint": "^9.28.0",
-		"eslint-config-prettier": "^10.1.5",
-		"eslint-import-resolver-typescript": "^3.7.0",
-		"glob": "^11.0.2",
-		"rollup": "^4.40.2",
-		"rollup-plugin-dts": "^6.2.1",
-		"ts-node": "^10.9.2",
-		"typescript": "^5.6.2",
-		"@types/jest": "^29.5.12",
-		"jest": "^29.7.0",
-		"ts-jest": "^29.2.5"
-	}
-}
+{
+	"name": "@org-quicko/core",
+	"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",
+	"module": "dist/esm/build/node/index.js",
+	"browser": "dist/browser/build/browser/index.js",
+	"types": "dist/types/index.d.ts",
+	"type": "module",
+	"scripts": {
+		"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",
+	"files": [
+		"dist/**/*"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"node": {
+				"import": "./dist/esm/build/node/index.js",
+				"require": "./dist/cjs/build/node/index.cjs"
+			},
+			"default": "./dist/browser/build/browser/index.js"
+		},
+		"./beans": {
+			"types": "./dist/types/src/beans/index.d.ts",
+			"node": {
+				"import": "./dist/esm/beans/index.js",
+				"require": "./dist/cjs/beans/index.cjs"
+			},
+			"default": "./dist/browser/beans/index.js"
+		},
+		"./types": {
+			"types": "./dist/types/src/types/index.d.ts",
+			"node": {
+				"import": "./dist/esm/types/index.js",
+				"require": "./dist/cjs/types/index.cjs"
+			},
+			"default": "./dist/browser/types/index.js"
+		},
+		"./utils": {
+			"types": "./dist/types/src/utils/index.d.ts",
+			"node": {
+				"import": "./dist/esm/utils/index.js",
+				"require": "./dist/cjs/utils/index.cjs"
+			},
+			"default": "./dist/browser/utils/index.js"
+		},
+		"./utils/date": {
+			"types": "./dist/types/src/utils/date/index.d.ts",
+			"node": {
+				"import": "./dist/esm/utils/date/index.js",
+				"require": "./dist/cjs/utils/date/index.cjs"
+			},
+			"default": "./dist/browser/utils/date/index.js"
+		},
+		"./logger": {
+			"types": "./dist/types/src/logger/index.d.ts",
+			"node": {
+				"import": "./dist/esm/logger/index.js",
+				"require": "./dist/cjs/logger/index.cjs"
+			}
+		},
+		"./exceptions": {
+			"types": "./dist/types/src/exceptions/index.d.ts",
+			"node": {
+				"import": "./dist/esm/exceptions/index.js",
+				"require": "./dist/cjs/exceptions/index.cjs"
+			},
+			"default": "./dist/browser/exceptions/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"directories": {
+		"lib": "./dist"
+	},
+	"dependencies": {
+		"@date-fns/tz": "^1.1.2",
+		"class-transformer": "^0.5.1",
+		"class-validator": "^0.14.1",
+		"date-fns": "^4.1.0",
+		"tslib": "^2.8.1",
+		"winston": "^3.17.0"
+	},
+	"devDependencies": {
+		"@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",
+		"esbuild-plugin-eslint": "^0.3.7",
+		"eslint": "^9.28.0",
+		"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"
+	}
+}