ts-time-utils 1.1.0 → 2.0.0

package/dist/esm/parse.d.ts

@@ -28,4 +28,49 @@ export declare function parseCustomFormat(dateString: string, format: string): D
  * @param formats - array of format patterns to try
  */
 export declare function parseManyFormats(dateString: string, formats: string[]): Date | null;
+/**
+ * Parse an ISO 8601 duration string (e.g., "P1Y2M3DT4H5M6S")
+ * @param duration - ISO 8601 duration string
+ * @returns object with parsed components
+ */
+export declare function parseISO8601Duration(duration: string): {
+    years: number;
+    months: number;
+    weeks: number;
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+} | null;
+/**
+ * Convert ISO 8601 duration to milliseconds (approximate for months/years)
+ * @param duration - ISO 8601 duration string
+ */
+export declare function parseISO8601DurationToMs(duration: string): number | null;
+/**
+ * Parse a time string (e.g., "14:30", "2:30 PM", "14:30:45")
+ * @param timeString - time string to parse
+ * @returns object with hours, minutes, seconds, or null if invalid
+ */
+export declare function parseTime(timeString: string): {
+    hours: number;
+    minutes: number;
+    seconds: number;
+} | null;
+/**
+ * Guess the date format of a date string
+ * @param dateString - date string to analyze
+ * @returns detected format pattern or null
+ */
+export declare function guessDateFormat(dateString: string): string | null;
+/**
+ * Parse a date string using auto-detected format
+ * @param dateString - date string to parse
+ */
+export declare function parseAutoFormat(dateString: string): Date | null;
+/**
+ * Parse a date from a natural language date range endpoint
+ * @param input - string like "end of month", "start of year", "beginning of week"
+ */
+export declare function parseRangeEndpoint(input: string): Date | null;
 //# sourceMappingURL=parse.d.ts.map

package/dist/esm/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/parse.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAuDpE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CA6C5D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAiBvD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAmDjF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,IAAI,CAMnF"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/parse.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAuDpE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CA6C5D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAiBvD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAmDjF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,IAAI,CAMnF;AAqCD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,IAAI,CA4CP;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAqBxE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,IAAI,CAuCP;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoCjE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAmB/D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CA2C7D"}

package/dist/esm/parse.js

@@ -215,3 +215,210 @@ function addTimeUnits(date, amount, unit) {
 function subtractTimeUnits(date, amount, unit) {
     return addTimeUnits(date, -amount, unit);
 }
+/**
+ * Parse an ISO 8601 duration string (e.g., "P1Y2M3DT4H5M6S")
+ * @param duration - ISO 8601 duration string
+ * @returns object with parsed components
+ */
+export function parseISO8601Duration(duration) {
+    // ISO 8601 duration format: P[n]Y[n]M[n]DT[n]H[n]M[n]S or P[n]W
+    const result = {
+        years: 0,
+        months: 0,
+        weeks: 0,
+        days: 0,
+        hours: 0,
+        minutes: 0,
+        seconds: 0,
+    };
+    const normalized = duration.toUpperCase().trim();
+    if (!normalized.startsWith('P')) {
+        return null;
+    }
+    // Handle week format: P[n]W
+    const weekMatch = normalized.match(/^P(\d+)W$/);
+    if (weekMatch) {
+        result.weeks = parseInt(weekMatch[1]);
+        return result;
+    }
+    // Full format: P[n]Y[n]M[n]DT[n]H[n]M[n]S
+    const fullMatch = normalized.match(/^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/);
+    if (!fullMatch) {
+        return null;
+    }
+    const [, years, months, days, hours, minutes, seconds] = fullMatch;
+    if (years)
+        result.years = parseInt(years);
+    if (months)
+        result.months = parseInt(months);
+    if (days)
+        result.days = parseInt(days);
+    if (hours)
+        result.hours = parseInt(hours);
+    if (minutes)
+        result.minutes = parseInt(minutes);
+    if (seconds)
+        result.seconds = parseFloat(seconds);
+    return result;
+}
+/**
+ * Convert ISO 8601 duration to milliseconds (approximate for months/years)
+ * @param duration - ISO 8601 duration string
+ */
+export function parseISO8601DurationToMs(duration) {
+    const parsed = parseISO8601Duration(duration);
+    if (!parsed)
+        return null;
+    const MS_PER_SECOND = 1000;
+    const MS_PER_MINUTE = 60 * MS_PER_SECOND;
+    const MS_PER_HOUR = 60 * MS_PER_MINUTE;
+    const MS_PER_DAY = 24 * MS_PER_HOUR;
+    const MS_PER_WEEK = 7 * MS_PER_DAY;
+    const MS_PER_MONTH = 30 * MS_PER_DAY; // Approximate
+    const MS_PER_YEAR = 365 * MS_PER_DAY; // Approximate
+    return (parsed.years * MS_PER_YEAR +
+        parsed.months * MS_PER_MONTH +
+        parsed.weeks * MS_PER_WEEK +
+        parsed.days * MS_PER_DAY +
+        parsed.hours * MS_PER_HOUR +
+        parsed.minutes * MS_PER_MINUTE +
+        parsed.seconds * MS_PER_SECOND);
+}
+/**
+ * Parse a time string (e.g., "14:30", "2:30 PM", "14:30:45")
+ * @param timeString - time string to parse
+ * @returns object with hours, minutes, seconds, or null if invalid
+ */
+export function parseTime(timeString) {
+    const normalized = timeString.trim();
+    // 24-hour format: HH:MM or HH:MM:SS
+    const match24 = normalized.match(/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/);
+    if (match24) {
+        const hours = parseInt(match24[1]);
+        const minutes = parseInt(match24[2]);
+        const seconds = match24[3] ? parseInt(match24[3]) : 0;
+        if (hours >= 0 && hours <= 23 && minutes >= 0 && minutes <= 59 && seconds >= 0 && seconds <= 59) {
+            return { hours, minutes, seconds };
+        }
+        return null;
+    }
+    // 12-hour format: H:MM AM/PM or HH:MM AM/PM
+    const match12 = normalized.match(/^(\d{1,2}):(\d{2})(?::(\d{2}))?\s*(AM|PM|am|pm)$/i);
+    if (match12) {
+        let hours = parseInt(match12[1]);
+        const minutes = parseInt(match12[2]);
+        const seconds = match12[3] ? parseInt(match12[3]) : 0;
+        const isPM = match12[4].toLowerCase() === 'pm';
+        if (hours < 1 || hours > 12 || minutes < 0 || minutes > 59 || seconds < 0 || seconds > 59) {
+            return null;
+        }
+        // Convert to 24-hour format
+        if (isPM && hours !== 12) {
+            hours += 12;
+        }
+        else if (!isPM && hours === 12) {
+            hours = 0;
+        }
+        return { hours, minutes, seconds };
+    }
+    return null;
+}
+/**
+ * Guess the date format of a date string
+ * @param dateString - date string to analyze
+ * @returns detected format pattern or null
+ */
+export function guessDateFormat(dateString) {
+    const normalized = dateString.trim();
+    // YYYY-MM-DD
+    if (/^\d{4}-\d{2}-\d{2}$/.test(normalized)) {
+        return 'YYYY-MM-DD';
+    }
+    // DD/MM/YYYY or MM/DD/YYYY - need to analyze values
+    if (/^\d{2}\/\d{2}\/\d{4}$/.test(normalized)) {
+        const [first, second] = normalized.split('/').map(Number);
+        if (first > 12)
+            return 'DD/MM/YYYY'; // First must be day
+        if (second > 12)
+            return 'MM/DD/YYYY'; // Second must be day
+        // Ambiguous - default to US format
+        return 'MM/DD/YYYY';
+    }
+    // DD-MM-YYYY or MM-DD-YYYY
+    if (/^\d{2}-\d{2}-\d{4}$/.test(normalized)) {
+        const [first, second] = normalized.split('-').map(Number);
+        if (first > 12)
+            return 'DD-MM-YYYY';
+        if (second > 12)
+            return 'MM-DD-YYYY';
+        return 'MM-DD-YYYY';
+    }
+    // YYYYMMDD
+    if (/^\d{8}$/.test(normalized)) {
+        return 'YYYYMMDD';
+    }
+    // ISO 8601 with time
+    if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(normalized)) {
+        return 'ISO8601';
+    }
+    return null;
+}
+/**
+ * Parse a date string using auto-detected format
+ * @param dateString - date string to parse
+ */
+export function parseAutoFormat(dateString) {
+    const format = guessDateFormat(dateString);
+    if (!format) {
+        return parseDate(dateString);
+    }
+    if (format === 'ISO8601') {
+        return parseDate(dateString);
+    }
+    if (format === 'YYYYMMDD') {
+        const year = parseInt(dateString.slice(0, 4));
+        const month = parseInt(dateString.slice(4, 6)) - 1;
+        const day = parseInt(dateString.slice(6, 8));
+        return new Date(year, month, day);
+    }
+    return parseCustomFormat(dateString, format);
+}
+/**
+ * Parse a date from a natural language date range endpoint
+ * @param input - string like "end of month", "start of year", "beginning of week"
+ */
+export function parseRangeEndpoint(input) {
+    const now = new Date();
+    const lowercaseInput = input.toLowerCase().trim();
+    // Start/beginning of period
+    if (lowercaseInput.match(/^(start|beginning)\s+of\s+(this\s+)?(day|today)$/)) {
+        return new Date(now.getFullYear(), now.getMonth(), now.getDate(), 0, 0, 0, 0);
+    }
+    if (lowercaseInput.match(/^(start|beginning)\s+of\s+(this\s+)?week$/)) {
+        const day = now.getDay();
+        const diff = now.getDate() - day + (day === 0 ? -6 : 1); // Monday
+        return new Date(now.getFullYear(), now.getMonth(), diff, 0, 0, 0, 0);
+    }
+    if (lowercaseInput.match(/^(start|beginning)\s+of\s+(this\s+)?month$/)) {
+        return new Date(now.getFullYear(), now.getMonth(), 1, 0, 0, 0, 0);
+    }
+    if (lowercaseInput.match(/^(start|beginning)\s+of\s+(this\s+)?year$/)) {
+        return new Date(now.getFullYear(), 0, 1, 0, 0, 0, 0);
+    }
+    // End of period
+    if (lowercaseInput.match(/^end\s+of\s+(this\s+)?(day|today)$/)) {
+        return new Date(now.getFullYear(), now.getMonth(), now.getDate(), 23, 59, 59, 999);
+    }
+    if (lowercaseInput.match(/^end\s+of\s+(this\s+)?week$/)) {
+        const day = now.getDay();
+        const diff = now.getDate() - day + (day === 0 ? 0 : 7); // Sunday
+        return new Date(now.getFullYear(), now.getMonth(), diff, 23, 59, 59, 999);
+    }
+    if (lowercaseInput.match(/^end\s+of\s+(this\s+)?month$/)) {
+        return new Date(now.getFullYear(), now.getMonth() + 1, 0, 23, 59, 59, 999);
+    }
+    if (lowercaseInput.match(/^end\s+of\s+(this\s+)?year$/)) {
+        return new Date(now.getFullYear(), 11, 31, 23, 59, 59, 999);
+    }
+    return null;
+}

package/dist/esm/timezone.d.ts

@@ -31,4 +31,56 @@ export declare function compareZoneOffsets(zoneA: string, zoneB: string, date?:
  * For example useful for naive scheduling.
  */
 export declare function reinterpretAsZone(date: Date, targetZone: string): Date | null;
+/**
+ * Check if a date is in Daylight Saving Time for a given timezone
+ * @param date - date to check
+ * @param zone - IANA timezone string
+ */
+export declare function isDST(date: Date, zone: string): boolean | null;
+/**
+ * Get the next DST transition (if any) for a timezone
+ * @param date - starting date
+ * @param zone - IANA timezone string
+ * @returns next DST transition date or null if no DST in that zone
+ */
+export declare function getNextDSTTransition(date: Date, zone: string): Date | null;
+/**
+ * Find overlapping working hours between multiple timezones
+ * @param zones - array of IANA timezone strings
+ * @param workHoursStart - work hours start (0-24)
+ * @param workHoursEnd - work hours end (0-24)
+ * @param date - reference date (default: today)
+ * @returns array of overlapping hour ranges in UTC, or null if no overlap
+ */
+export declare function findCommonWorkingHours(zones: string[], workHoursStart?: number, workHoursEnd?: number, date?: Date): {
+    startUTC: number;
+    endUTC: number;
+} | null;
+/**
+ * Get all timezone abbreviations for a zone on a given date
+ * @param zone - IANA timezone string
+ * @param date - reference date
+ */
+export declare function getTimezoneAbbreviation(zone: string, date?: Date): string | null;
+/**
+ * Convert a wall clock time from one timezone to another
+ * @param date - date with time in source timezone
+ * @param fromZone - source timezone
+ * @param toZone - target timezone
+ */
+export declare function convertBetweenZones(date: Date, fromZone: string, toZone: string): Date | null;
+/**
+ * Get the time difference between two timezones in hours
+ * @param zoneA - first timezone
+ * @param zoneB - second timezone
+ * @param date - reference date
+ */
+export declare function getTimezoneDifferenceHours(zoneA: string, zoneB: string, date?: Date): number | null;
+/**
+ * Check if two timezones have the same offset at a given date
+ * @param zoneA - first timezone
+ * @param zoneB - second timezone
+ * @param date - reference date
+ */
+export declare function isSameTimezone(zoneA: string, zoneB: string, date?: Date): boolean | null;
 //# sourceMappingURL=timezone.d.ts.map

package/dist/esm/timezone.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timezone.d.ts","sourceRoot":"","sources":["../../src/timezone.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,sDAAsD;AACtD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAgBtF;AAED,iCAAiC;AACjC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,qBAA0B,GAAG,MAAM,CAG3G;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAIvE;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;CAAE,GAAG,IAAI,CAoB9J;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,UAK5B,CAAC;AAEF,0CAA0C;AAC1C,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,iDAAiD;AACjD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAKvG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAI7E"}
+{"version":3,"file":"timezone.d.ts","sourceRoot":"","sources":["../../src/timezone.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,sDAAsD;AACtD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAgBtF;AAED,iCAAiC;AACjC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,qBAA0B,GAAG,MAAM,CAG3G;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAIvE;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;CAAE,GAAG,IAAI,CAoB9J;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,UAK5B,CAAC;AAEF,0CAA0C;AAC1C,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,iDAAiD;AACjD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAKvG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAI7E;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CA0B9D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAiD1E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EAAE,EACf,cAAc,GAAE,MAAU,EAC1B,YAAY,GAAE,MAAW,EACzB,IAAI,GAAE,IAAiB,GACtB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA6B7C;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAY5F;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAa7F;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAI/G;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,OAAO,GAAG,IAAI,CAIpG"}

package/dist/esm/timezone.js

@@ -97,3 +97,174 @@ export function reinterpretAsZone(date, targetZone) {
         return null;
     return new Date(Date.UTC(target.year, target.month - 1, target.day, target.hour, target.minute, target.second));
 }
+/**
+ * Check if a date is in Daylight Saving Time for a given timezone
+ * @param date - date to check
+ * @param zone - IANA timezone string
+ */
+export function isDST(date, zone) {
+    if (!isValidTimeZone(zone))
+        return null;
+    // Compare offset in January vs July - the one with larger offset is DST
+    const january = new Date(date.getFullYear(), 0, 1);
+    const july = new Date(date.getFullYear(), 6, 1);
+    const janOffset = getTimezoneOffset(zone, january);
+    const julOffset = getTimezoneOffset(zone, july);
+    const currentOffset = getTimezoneOffset(zone, date);
+    if (janOffset === null || julOffset === null || currentOffset === null) {
+        return null;
+    }
+    // If offsets are the same, no DST in this zone
+    if (janOffset === julOffset) {
+        return false;
+    }
+    // In northern hemisphere, summer (July) has larger offset
+    // In southern hemisphere, summer (January) has larger offset
+    // DST is whichever is the "larger" offset
+    const maxOffset = Math.max(janOffset, julOffset);
+    return currentOffset === maxOffset;
+}
+/**
+ * Get the next DST transition (if any) for a timezone
+ * @param date - starting date
+ * @param zone - IANA timezone string
+ * @returns next DST transition date or null if no DST in that zone
+ */
+export function getNextDSTTransition(date, zone) {
+    if (!isValidTimeZone(zone))
+        return null;
+    const january = new Date(date.getFullYear(), 0, 1);
+    const july = new Date(date.getFullYear(), 6, 1);
+    const janOffset = getTimezoneOffset(zone, january);
+    const julOffset = getTimezoneOffset(zone, july);
+    if (janOffset === null || julOffset === null)
+        return null;
+    // No DST if offsets are the same
+    if (janOffset === julOffset)
+        return null;
+    // Binary search for the transition within the next year
+    const currentOffset = getTimezoneOffset(zone, date);
+    if (currentOffset === null)
+        return null;
+    // Check day by day for up to 366 days
+    const searchDate = new Date(date);
+    for (let i = 1; i <= 366; i++) {
+        searchDate.setDate(searchDate.getDate() + 1);
+        const newOffset = getTimezoneOffset(zone, searchDate);
+        if (newOffset !== null && newOffset !== currentOffset) {
+            // Found a transition, now narrow it down
+            const prevDay = new Date(searchDate);
+            prevDay.setDate(prevDay.getDate() - 1);
+            // Binary search within the day
+            let low = prevDay.getTime();
+            let high = searchDate.getTime();
+            while (high - low > 60000) { // 1 minute precision
+                const mid = Math.floor((low + high) / 2);
+                const midDate = new Date(mid);
+                const midOffset = getTimezoneOffset(zone, midDate);
+                if (midOffset === currentOffset) {
+                    low = mid;
+                }
+                else {
+                    high = mid;
+                }
+            }
+            return new Date(high);
+        }
+    }
+    return null;
+}
+/**
+ * Find overlapping working hours between multiple timezones
+ * @param zones - array of IANA timezone strings
+ * @param workHoursStart - work hours start (0-24)
+ * @param workHoursEnd - work hours end (0-24)
+ * @param date - reference date (default: today)
+ * @returns array of overlapping hour ranges in UTC, or null if no overlap
+ */
+export function findCommonWorkingHours(zones, workHoursStart = 9, workHoursEnd = 17, date = new Date()) {
+    if (zones.length === 0)
+        return null;
+    // Convert each zone's work hours to UTC
+    const utcRanges = zones.map(zone => {
+        const offset = getTimezoneOffset(zone, date);
+        if (offset === null)
+            return null;
+        // Offset is in minutes, positive means ahead of UTC
+        // So to convert local time to UTC, we subtract the offset
+        const startUTC = workHoursStart - (offset / 60);
+        const endUTC = workHoursEnd - (offset / 60);
+        return { startUTC, endUTC };
+    });
+    if (utcRanges.some(r => r === null))
+        return null;
+    const validRanges = utcRanges;
+    // Find intersection of all ranges
+    let overlapStart = Math.max(...validRanges.map(r => r.startUTC));
+    let overlapEnd = Math.min(...validRanges.map(r => r.endUTC));
+    if (overlapStart >= overlapEnd) {
+        return null; // No overlap
+    }
+    return { startUTC: overlapStart, endUTC: overlapEnd };
+}
+/**
+ * Get all timezone abbreviations for a zone on a given date
+ * @param zone - IANA timezone string
+ * @param date - reference date
+ */
+export function getTimezoneAbbreviation(zone, date = new Date()) {
+    try {
+        const fmt = new Intl.DateTimeFormat('en-US', {
+            timeZone: zone,
+            timeZoneName: 'short'
+        });
+        const parts = fmt.formatToParts(date);
+        const tzPart = parts.find(p => p.type === 'timeZoneName');
+        return tzPart?.value || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Convert a wall clock time from one timezone to another
+ * @param date - date with time in source timezone
+ * @param fromZone - source timezone
+ * @param toZone - target timezone
+ */
+export function convertBetweenZones(date, fromZone, toZone) {
+    // First, interpret the date as being in fromZone
+    const fromOffset = getTimezoneOffset(fromZone, date);
+    const toOffset = getTimezoneOffset(toZone, date);
+    if (fromOffset === null || toOffset === null)
+        return null;
+    // Calculate the difference in minutes
+    const diffMinutes = toOffset - fromOffset;
+    // Apply the difference
+    const result = new Date(date.getTime() + diffMinutes * 60 * 1000);
+    return result;
+}
+/**
+ * Get the time difference between two timezones in hours
+ * @param zoneA - first timezone
+ * @param zoneB - second timezone
+ * @param date - reference date
+ */
+export function getTimezoneDifferenceHours(zoneA, zoneB, date = new Date()) {
+    const diff = compareZoneOffsets(zoneA, zoneB, date);
+    if (diff === null)
+        return null;
+    return diff / 60;
+}
+/**
+ * Check if two timezones have the same offset at a given date
+ * @param zoneA - first timezone
+ * @param zoneB - second timezone
+ * @param date - reference date
+ */
+export function isSameTimezone(zoneA, zoneB, date = new Date()) {
+    const diff = compareZoneOffsets(zoneA, zoneB, date);
+    if (diff === null)
+        return null;
+    return diff === 0;
+}

package/dist/esm/validate.d.ts

@@ -59,4 +59,55 @@ export declare function isValidTimeString(time: string): boolean;
  * @param dateString - date string to validate
  */
 export declare function isValidISOString(dateString: string): boolean;
+/**
+ * Check if two dates are in the same week (ISO week, Monday-Sunday)
+ * @param date1 - first date
+ * @param date2 - second date
+ */
+export declare function isSameWeek(date1: Date, date2: Date): boolean;
+/**
+ * Check if two dates are in the same month
+ * @param date1 - first date
+ * @param date2 - second date
+ */
+export declare function isSameMonth(date1: Date, date2: Date): boolean;
+/**
+ * Check if two dates are in the same year
+ * @param date1 - first date
+ * @param date2 - second date
+ */
+export declare function isSameYear(date1: Date, date2: Date): boolean;
+/**
+ * Check if a date is in the current week
+ * @param date - date to check
+ */
+export declare function isThisWeek(date: Date): boolean;
+/**
+ * Check if a date is in the current month
+ * @param date - date to check
+ */
+export declare function isThisMonth(date: Date): boolean;
+/**
+ * Check if a date is in the current year
+ * @param date - date to check
+ */
+export declare function isThisYear(date: Date): boolean;
+/**
+ * Check if a date is a business day (weekday, optionally excluding holidays)
+ * @param date - date to check
+ * @param holidays - optional array of holiday dates to exclude
+ */
+export declare function isBusinessDay(date: Date, holidays?: Date[]): boolean;
+/**
+ * Check if a date is in the last N days (including today)
+ * @param date - date to check
+ * @param n - number of days
+ */
+export declare function isInLastNDays(date: Date, n: number): boolean;
+/**
+ * Check if a date is in the next N days (including today)
+ * @param date - date to check
+ * @param n - number of days
+ */
+export declare function isInNextNDays(date: Date, n: number): boolean;
 //# sourceMappingURL=validate.d.ts.map

package/dist/esm/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/validate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAWjE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE1C;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE5C;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAO3C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAQ/C;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAQ9C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAM3D;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAG7C;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE7C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAG5D"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/validate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAWjE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE1C;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE5C;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAO3C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAQ/C;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAQ9C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAM3D;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAG7C;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE7C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAW5D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAK7D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAE5D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE9C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE/C;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,GAAE,IAAI,EAAO,GAAG,OAAO,CAIxE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAU5D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAU5D"}

package/dist/esm/validate.js

@@ -106,3 +106,95 @@ export function isValidISOString(dateString) {
     const isoRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z?$/;
     return isoRegex.test(dateString) && isValidDate(dateString);
 }
+/**
+ * Check if two dates are in the same week (ISO week, Monday-Sunday)
+ * @param date1 - first date
+ * @param date2 - second date
+ */
+export function isSameWeek(date1, date2) {
+    const getWeekStart = (d) => {
+        const date = new Date(d);
+        const day = date.getDay();
+        const diff = date.getDate() - day + (day === 0 ? -6 : 1); // Adjust for Monday start
+        date.setDate(diff);
+        date.setHours(0, 0, 0, 0);
+        return date;
+    };
+    return getWeekStart(date1).getTime() === getWeekStart(date2).getTime();
+}
+/**
+ * Check if two dates are in the same month
+ * @param date1 - first date
+ * @param date2 - second date
+ */
+export function isSameMonth(date1, date2) {
+    return (date1.getMonth() === date2.getMonth() &&
+        date1.getFullYear() === date2.getFullYear());
+}
+/**
+ * Check if two dates are in the same year
+ * @param date1 - first date
+ * @param date2 - second date
+ */
+export function isSameYear(date1, date2) {
+    return date1.getFullYear() === date2.getFullYear();
+}
+/**
+ * Check if a date is in the current week
+ * @param date - date to check
+ */
+export function isThisWeek(date) {
+    return isSameWeek(date, new Date());
+}
+/**
+ * Check if a date is in the current month
+ * @param date - date to check
+ */
+export function isThisMonth(date) {
+    return isSameMonth(date, new Date());
+}
+/**
+ * Check if a date is in the current year
+ * @param date - date to check
+ */
+export function isThisYear(date) {
+    return isSameYear(date, new Date());
+}
+/**
+ * Check if a date is a business day (weekday, optionally excluding holidays)
+ * @param date - date to check
+ * @param holidays - optional array of holiday dates to exclude
+ */
+export function isBusinessDay(date, holidays = []) {
+    if (isWeekend(date))
+        return false;
+    return !holidays.some(holiday => isSameDay(date, holiday));
+}
+/**
+ * Check if a date is in the last N days (including today)
+ * @param date - date to check
+ * @param n - number of days
+ */
+export function isInLastNDays(date, n) {
+    const now = new Date();
+    const nDaysAgo = new Date(now);
+    nDaysAgo.setDate(nDaysAgo.getDate() - n);
+    nDaysAgo.setHours(0, 0, 0, 0);
+    const endOfToday = new Date(now);
+    endOfToday.setHours(23, 59, 59, 999);
+    return date >= nDaysAgo && date <= endOfToday;
+}
+/**
+ * Check if a date is in the next N days (including today)
+ * @param date - date to check
+ * @param n - number of days
+ */
+export function isInNextNDays(date, n) {
+    const now = new Date();
+    const startOfToday = new Date(now);
+    startOfToday.setHours(0, 0, 0, 0);
+    const nDaysFromNow = new Date(now);
+    nDaysFromNow.setDate(nDaysFromNow.getDate() + n);
+    nDaysFromNow.setHours(23, 59, 59, 999);
+    return date >= startOfToday && date <= nDaysFromNow;
+}