ts-time-utils 4.0.1 → 4.4.0

package/dist/scheduling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduling.d.ts","sourceRoot":"","sources":["../src/scheduling.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAK3F,8CAA8C;AAC9C,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,kDAAkD;IAClD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAC;CACnB;AAED,2CAA2C;AAC3C,MAAM,WAAW,IAAI;IACnB,KAAK,EAAE,IAAI,CAAC;IACZ,GAAG,EAAE,IAAI,CAAC;IACV,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,uCAAuC;AACvC,MAAM,WAAW,OAAQ,SAAQ,SAAS;IACxC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,uCAAuC;AACvC,eAAO,MAAM,yBAAyB,EAAE,gBAKvC,CAAC;AAkBF;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,GAAE,gBAAqB,GAAG,IAAI,EAAE,CAqCpF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,GAAE,gBAAqB,GAAG,IAAI,EAAE,CAe7F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,OAAO,EAAE,EACnB,MAAM,GAAE,gBAAqB,GAC5B,IAAI,EAAE,CAmBR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,OAAO,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,gBAAqB,GAC5B,IAAI,GAAG,IAAI,CAmBb;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAE7E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,SAAS,GAAG,OAAO,EAAE,CAEjF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,SAAS,GAAG,OAAO,CAE7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,GAAG,SAAS,CAM3E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,GAAG,SAAS,CAM9E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,SAAS,EAChB,MAAM,GAAE,gBAAqB,GAC5B,IAAI,EAAE,CAUR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAS5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,IAAI,CAmBxE"}

package/dist/{serialize.js → serialize.cjs}

@@ -1,10 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeDate = serializeDate;
+exports.deserializeDate = deserializeDate;
+exports.createDateReviver = createDateReviver;
+exports.createDateReplacer = createDateReplacer;
+exports.parseISOString = parseISOString;
+exports.toEpochTimestamp = toEpochTimestamp;
+exports.fromEpochTimestamp = fromEpochTimestamp;
+exports.createEpochTimestamp = createEpochTimestamp;
+exports.toDateObject = toDateObject;
+exports.fromDateObject = fromDateObject;
+exports.isValidISODateString = isValidISODateString;
+exports.isValidEpochTimestamp = isValidEpochTimestamp;
+exports.cloneDate = cloneDate;
+exports.datesEqual = datesEqual;
+exports.now = now;
+exports.parseJSONWithDates = parseJSONWithDates;
+exports.stringifyWithDates = stringifyWithDates;
 /**
  * Safe JSON date serialization and deserialization utilities
  */
 /**
  * Safely serialize a date to JSON with various format options
  */
-export function serializeDate(date, options = {}) {
+function serializeDate(date, options = {}) {
     const { format = 'iso', includeTimezone = false, useUTC = false, precision = 'milliseconds', customFormat } = options;
     const dateObj = normalizeDate(date);
     if (!dateObj) {
@@ -30,7 +49,7 @@ export function serializeDate(date, options = {}) {
 /**
  * Safely deserialize a date from various formats
  */
-export function deserializeDate(serializedDate, options = {}) {
+function deserializeDate(serializedDate, options = {}) {
     const { useUTC = false } = options;
     try {
         if (typeof serializedDate === 'string') {
@@ -59,7 +78,7 @@ export function deserializeDate(serializedDate, options = {}) {
 /**
  * Create a safe JSON reviver function for automatic date parsing
  */
-export function createDateReviver(dateKeys = ['createdAt', 'updatedAt', 'date', 'timestamp'], options = {}) {
+function createDateReviver(dateKeys = ['createdAt', 'updatedAt', 'date', 'timestamp'], options = {}) {
     return (key, value) => {
         if (dateKeys.includes(key) && (typeof value === 'string' || typeof value === 'number')) {
             const parsed = deserializeDate(value, options);
@@ -71,7 +90,7 @@ export function createDateReviver(dateKeys = ['createdAt', 'updatedAt', 'date',
 /**
  * Create a safe JSON replacer function for automatic date serialization
  */
-export function createDateReplacer(dateKeys = ['createdAt', 'updatedAt', 'date', 'timestamp'], options = {}) {
+function createDateReplacer(dateKeys = ['createdAt', 'updatedAt', 'date', 'timestamp'], options = {}) {
     return (key, value) => {
         if (dateKeys.includes(key)) {
             if (value instanceof Date) {
@@ -91,7 +110,7 @@ export function createDateReplacer(dateKeys = ['createdAt', 'updatedAt', 'date',
 /**
  * Parse ISO string with better error handling
  */
-export function parseISOString(isoString, useUTC = false) {
+function parseISOString(isoString, useUTC = false) {
     if (!isoString || typeof isoString !== 'string') {
         return null;
     }
@@ -120,7 +139,7 @@ export function parseISOString(isoString, useUTC = false) {
 /**
  * Convert date to epoch timestamp with specified precision
  */
-export function toEpochTimestamp(date, precision = 'milliseconds') {
+function toEpochTimestamp(date, precision = 'milliseconds') {
     const dateObj = normalizeDate(date);
     if (!dateObj) {
         throw new Error('Invalid date provided for epoch conversion');
@@ -139,7 +158,7 @@ export function toEpochTimestamp(date, precision = 'milliseconds') {
 /**
  * Create date from epoch timestamp with specified precision
  */
-export function fromEpochTimestamp(timestamp, precision = 'milliseconds') {
+function fromEpochTimestamp(timestamp, precision = 'milliseconds') {
     let ms;
     switch (precision) {
         case 'seconds':
@@ -158,7 +177,7 @@ export function fromEpochTimestamp(timestamp, precision = 'milliseconds') {
 /**
  * Create epoch timestamp with metadata
  */
-export function createEpochTimestamp(date, precision = 'milliseconds', timezone) {
+function createEpochTimestamp(date, precision = 'milliseconds', timezone) {
     return {
         timestamp: toEpochTimestamp(date, precision),
         precision,
@@ -168,7 +187,7 @@ export function createEpochTimestamp(date, precision = 'milliseconds', timezone)
 /**
  * Convert date to safe object representation
  */
-export function toDateObject(date, includeTimezone = false) {
+function toDateObject(date, includeTimezone = false) {
     const dateObj = normalizeDate(date);
     if (!dateObj) {
         throw new Error('Invalid date provided for object conversion');
@@ -195,7 +214,7 @@ export function toDateObject(date, includeTimezone = false) {
 /**
  * Create date from object representation
  */
-export function fromDateObject(dateObj) {
+function fromDateObject(dateObj) {
     // Validate required fields
     if (!dateObj || typeof dateObj !== 'object') {
         throw new Error('Invalid date object provided');
@@ -228,7 +247,7 @@ export function fromDateObject(dateObj) {
 /**
  * Check if a string is a valid ISO date string for serialization
  */
-export function isValidISODateString(dateString) {
+function isValidISODateString(dateString) {
     if (!dateString || typeof dateString !== 'string') {
         return false;
     }
@@ -238,7 +257,7 @@ export function isValidISODateString(dateString) {
 /**
  * Check if a number is a valid epoch timestamp
  */
-export function isValidEpochTimestamp(timestamp, precision = 'milliseconds') {
+function isValidEpochTimestamp(timestamp, precision = 'milliseconds') {
     if (typeof timestamp !== 'number' || isNaN(timestamp)) {
         return false;
     }
@@ -265,14 +284,14 @@ export function isValidEpochTimestamp(timestamp, precision = 'milliseconds') {
 /**
  * Clone a date safely (avoids reference issues)
  */
-export function cloneDate(date) {
+function cloneDate(date) {
     const dateObj = normalizeDate(date);
     return dateObj ? new Date(dateObj.getTime()) : null;
 }
 /**
  * Compare two dates for equality (ignoring milliseconds if specified)
  */
-export function datesEqual(date1, date2, precision = 'milliseconds') {
+function datesEqual(date1, date2, precision = 'milliseconds') {
     const d1 = normalizeDate(date1);
     const d2 = normalizeDate(date2);
     if (!d1 || !d2) {
@@ -295,7 +314,7 @@ export function datesEqual(date1, date2, precision = 'milliseconds') {
 /**
  * Get current timestamp in various formats
  */
-export function now(format = 'date') {
+function now(format = 'date') {
     const current = new Date();
     switch (format) {
         case 'iso':
@@ -312,7 +331,7 @@ export function now(format = 'date') {
 /**
  * Safely handle JSON parsing with date conversion
  */
-export function parseJSONWithDates(jsonString, dateKeys, options) {
+function parseJSONWithDates(jsonString, dateKeys, options) {
     try {
         return JSON.parse(jsonString, createDateReviver(dateKeys, options));
     }
@@ -323,7 +342,7 @@ export function parseJSONWithDates(jsonString, dateKeys, options) {
 /**
  * Safely handle JSON stringification with date conversion
  */
-export function stringifyWithDates(obj, dateKeys, options, space) {
+function stringifyWithDates(obj, dateKeys, options, space) {
     try {
         return JSON.stringify(obj, createDateReplacer(dateKeys, options), space);
     }

package/dist/{temporal.js → temporal.cjs}

@@ -1,8 +1,23 @@
+"use strict";
 /**
  * @fileoverview Temporal API compatibility layer
  * Provides Temporal-like objects that work with native Date
  * When Temporal ships natively, these become thin wrappers
  */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPlainDate = toPlainDate;
+exports.toPlainTime = toPlainTime;
+exports.toPlainDateTime = toPlainDateTime;
+exports.toZonedDateTime = toZonedDateTime;
+exports.toInstant = toInstant;
+exports.createDuration = createDuration;
+exports.parseDuration = parseDuration;
+exports.nowInstant = nowInstant;
+exports.nowPlainDateTime = nowPlainDateTime;
+exports.nowPlainDate = nowPlainDate;
+exports.nowPlainTime = nowPlainTime;
+exports.nowZonedDateTime = nowZonedDateTime;
+exports.fromTemporal = fromTemporal;
 // Helper functions
 function getWeekNumber(date) {
     const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
@@ -552,7 +567,7 @@ class InstantImpl {
         return new Date(this.epochMilliseconds);
     }
 }
-export function toPlainDate(dateOrYear, month, day) {
+function toPlainDate(dateOrYear, month, day) {
     if (dateOrYear instanceof Date) {
         return new PlainDateImpl(dateOrYear.getFullYear(), dateOrYear.getMonth() + 1, dateOrYear.getDate());
     }
@@ -561,7 +576,7 @@ export function toPlainDate(dateOrYear, month, day) {
     }
     return new PlainDateImpl(dateOrYear, month, day);
 }
-export function toPlainTime(dateOrHour, minute, second, millisecond) {
+function toPlainTime(dateOrHour, minute, second, millisecond) {
     if (dateOrHour instanceof Date) {
         return new PlainTimeImpl(dateOrHour.getHours(), dateOrHour.getMinutes(), dateOrHour.getSeconds(), dateOrHour.getMilliseconds());
     }
@@ -570,7 +585,7 @@ export function toPlainTime(dateOrHour, minute, second, millisecond) {
     }
     return new PlainTimeImpl(dateOrHour, minute, second, millisecond);
 }
-export function toPlainDateTime(dateOrYear, month, day, hour, minute, second, millisecond) {
+function toPlainDateTime(dateOrYear, month, day, hour, minute, second, millisecond) {
     if (dateOrYear instanceof Date) {
         return new PlainDateTimeImpl(dateOrYear.getFullYear(), dateOrYear.getMonth() + 1, dateOrYear.getDate(), dateOrYear.getHours(), dateOrYear.getMinutes(), dateOrYear.getSeconds(), dateOrYear.getMilliseconds());
     }
@@ -582,10 +597,10 @@ export function toPlainDateTime(dateOrYear, month, day, hour, minute, second, mi
 /**
  * Create a ZonedDateTime from a Date object and timezone
  */
-export function toZonedDateTime(date, timeZone) {
+function toZonedDateTime(date, timeZone) {
     return new ZonedDateTimeImpl(date.getTime(), timeZone);
 }
-export function toInstant(dateOrEpoch) {
+function toInstant(dateOrEpoch) {
     if (dateOrEpoch instanceof Date) {
         return new InstantImpl(dateOrEpoch.getTime());
     }
@@ -597,13 +612,13 @@ export function toInstant(dateOrEpoch) {
 /**
  * Create a Duration from components
  */
-export function createDuration(fields = {}) {
+function createDuration(fields = {}) {
     return new DurationImpl(fields);
 }
 /**
  * Parse an ISO 8601 duration string
  */
-export function parseDuration(str) {
+function parseDuration(str) {
     const match = str.match(/^(-)?P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/);
     if (!match)
         throw new Error(`Invalid duration: ${str}`);
@@ -625,36 +640,36 @@ export function parseDuration(str) {
 /**
  * Get current instant
  */
-export function nowInstant() {
+function nowInstant() {
     return new InstantImpl(Date.now());
 }
 /**
  * Get current PlainDateTime in local timezone
  */
-export function nowPlainDateTime() {
+function nowPlainDateTime() {
     return toPlainDateTime(new Date());
 }
 /**
  * Get current PlainDate in local timezone
  */
-export function nowPlainDate() {
+function nowPlainDate() {
     return toPlainDate(new Date());
 }
 /**
  * Get current PlainTime in local timezone
  */
-export function nowPlainTime() {
+function nowPlainTime() {
     return toPlainTime(new Date());
 }
 /**
  * Get current ZonedDateTime in specified timezone
  */
-export function nowZonedDateTime(timeZone) {
+function nowZonedDateTime(timeZone) {
     return toZonedDateTime(new Date(), timeZone);
 }
 /**
  * Convert Temporal-like object back to Date
  */
-export function fromTemporal(temporal) {
+function fromTemporal(temporal) {
     return temporal.toDate();
 }

package/dist/{timezone.js → timezone.cjs}

@@ -1,8 +1,40 @@
+"use strict";
 /**
  * Timezone utilities using Intl API with fallbacks
  */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMON_TIMEZONES = void 0;
+exports.getTimezoneOffset = getTimezoneOffset;
+exports.formatInTimeZone = formatInTimeZone;
+exports.getZonedTime = getZonedTime;
+exports.convertDateToZone = convertDateToZone;
+exports.isValidTimeZone = isValidTimeZone;
+exports.getLocalOffset = getLocalOffset;
+exports.compareZoneOffsets = compareZoneOffsets;
+exports.reinterpretAsZone = reinterpretAsZone;
+exports.isDST = isDST;
+exports.getNextDSTTransition = getNextDSTTransition;
+exports.findCommonWorkingHours = findCommonWorkingHours;
+exports.getTimezoneAbbreviation = getTimezoneAbbreviation;
+exports.convertBetweenZones = convertBetweenZones;
+exports.getTimezoneDifferenceHours = getTimezoneDifferenceHours;
+exports.isSameTimezone = isSameTimezone;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DAY_HOURS = 24;
+const YEAR_MONTHS = Array.from({ length: 12 }, (_, month) => month);
+function normalizeHourValue(hour) {
+    return ((hour % DAY_HOURS) + DAY_HOURS) % DAY_HOURS;
+}
+function pushSweepInterval(events, start, end) {
+    const clampedStart = Math.max(0, start);
+    const clampedEnd = Math.min(DAY_HOURS * 2, end);
+    if (clampedStart >= clampedEnd)
+        return;
+    events.push({ time: clampedStart, delta: 1 });
+    events.push({ time: clampedEnd, delta: -1 });
+}
 /** Get offset (minutes) for a zone at a given date */
-export function getTimezoneOffset(zone, date = new Date()) {
+function getTimezoneOffset(zone, date = new Date()) {
     try {
         const dtf = new Intl.DateTimeFormat('en-US', { timeZone: zone, timeZoneName: 'shortOffset', hour: '2-digit' });
         const parts = dtf.formatToParts(date);
@@ -23,19 +55,19 @@ export function getTimezoneOffset(zone, date = new Date()) {
     }
 }
 /** Format date/time in a zone */
-export function formatInTimeZone(date, zone, options = {}) {
+function formatInTimeZone(date, zone, options = {}) {
     const fmt = new Intl.DateTimeFormat('en-US', { timeZone: zone, ...options });
     return fmt.format(date);
 }
 /** Get a lightweight ZonedTime object */
-export function getZonedTime(date, zone) {
+function getZonedTime(date, zone) {
     const offset = getTimezoneOffset(zone, date);
     if (offset == null)
         return null;
     return { date: new Date(date), zone, offsetMinutes: offset };
 }
 /** Convert a date (treated as absolute moment) to another zone's clock components */
-export function convertDateToZone(date, zone) {
+function convertDateToZone(date, zone) {
     try {
         const fmt = new Intl.DateTimeFormat('en-US', {
             timeZone: zone,
@@ -58,7 +90,7 @@ export function convertDateToZone(date, zone) {
     }
 }
 /** Check if provided zone string is a valid IANA zone */
-export function isValidTimeZone(zone) {
+function isValidTimeZone(zone) {
     try {
         new Intl.DateTimeFormat('en-US', { timeZone: zone });
         return true;
@@ -68,18 +100,18 @@ export function isValidTimeZone(zone) {
     }
 }
 /** List a subset of common timezones (cannot enumerate all via API) */
-export const COMMON_TIMEZONES = [
+exports.COMMON_TIMEZONES = [
     'UTC', 'Etc/UTC', 'Europe/London', 'Europe/Paris', 'Europe/Berlin', 'Europe/Madrid', 'Europe/Rome',
     'America/New_York', 'America/Chicago', 'America/Denver', 'America/Los_Angeles', 'America/Toronto', 'America/Sao_Paulo',
     'Asia/Tehran', 'Asia/Dubai', 'Asia/Tokyo', 'Asia/Shanghai', 'Asia/Singapore', 'Asia/Kolkata', 'Asia/Hong_Kong',
     'Australia/Sydney', 'Pacific/Auckland'
 ];
 /** Get current local offset in minutes */
-export function getLocalOffset() {
+function getLocalOffset() {
     return -new Date().getTimezoneOffset();
 }
 /** Compare two timezones offset at given date */
-export function compareZoneOffsets(zoneA, zoneB, date = new Date()) {
+function compareZoneOffsets(zoneA, zoneB, date = new Date()) {
     const a = getTimezoneOffset(zoneA, date);
     const b = getTimezoneOffset(zoneB, date);
     if (a == null || b == null)
@@ -91,7 +123,7 @@ export function compareZoneOffsets(zoneA, zoneB, date = new Date()) {
  * the same wall clock time in the target zone interpreted as local.
  * For example useful for naive scheduling.
  */
-export function reinterpretAsZone(date, targetZone) {
+function reinterpretAsZone(date, targetZone) {
     const target = convertDateToZone(date, targetZone);
     if (!target)
         return null;
@@ -99,30 +131,35 @@ export function reinterpretAsZone(date, targetZone) {
 }
 /**
  * Check if a date is in Daylight Saving Time for a given timezone
+ * Uses a yearly-offset heuristic: sample the zone's local year and treat the
+ * maximum observed UTC offset as the DST offset for that year.
  * @param date - date to check
  * @param zone - IANA timezone string
  */
-export function isDST(date, zone) {
+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 zonedDate = convertDateToZone(date, zone);
+    if (!zonedDate) {
+        return null;
+    }
     const currentOffset = getTimezoneOffset(zone, date);
-    if (janOffset === null || julOffset === null || currentOffset === null) {
+    if (currentOffset === null) {
         return null;
     }
-    // If offsets are the same, no DST in this zone
-    if (janOffset === julOffset) {
+    const yearlyOffsets = new Set();
+    for (const month of YEAR_MONTHS) {
+        const sample = new Date(Date.UTC(zonedDate.year, month, 1, 12, 0, 0));
+        const offset = getTimezoneOffset(zone, sample);
+        if (offset === null) {
+            return null;
+        }
+        yearlyOffsets.add(offset);
+    }
+    if (yearlyOffsets.size <= 1) {
         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;
+    return currentOffset === Math.max(...yearlyOffsets);
 }
 /**
  * Get the next DST transition (if any) for a timezone
@@ -130,49 +167,38 @@ export function isDST(date, zone) {
  * @param zone - IANA timezone string
  * @returns next DST transition date or null if no DST in that zone
  */
-export function getNextDSTTransition(date, zone) {
+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);
+    const startTime = date.getTime() + 1;
+    const searchLimit = startTime + 366 * DAY_MS;
+    let low = startTime;
+    let high = null;
+    for (let probeTime = startTime + DAY_MS; probeTime <= searchLimit; probeTime += DAY_MS) {
+        const probeOffset = getTimezoneOffset(zone, new Date(probeTime));
+        if (probeOffset !== null && probeOffset !== currentOffset) {
+            low = probeTime - DAY_MS;
+            high = probeTime;
+            break;
         }
     }
-    return null;
+    if (high === null) {
+        return null;
+    }
+    while (high - low > 1) {
+        const mid = Math.floor((low + high) / 2);
+        const midOffset = getTimezoneOffset(zone, new Date(mid));
+        if (midOffset === currentOffset) {
+            low = mid;
+        }
+        else {
+            high = mid;
+        }
+    }
+    return new Date(high);
 }
 /**
  * Find overlapping working hours between multiple timezones
@@ -180,39 +206,71 @@ export function getNextDSTTransition(date, zone) {
  * @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
+ * @returns one contiguous UTC overlap window, specifically the longest
+ * contiguous overlap slice. A full-day overlap is returned as
+ * `{ startUTC: 0, endUTC: 24 }`, and wrapped overlaps are returned with
+ * `endUTC` normalized back into the 0-24 range and may be less than `startUTC`
  */
-export function findCommonWorkingHours(zones, workHoursStart = 9, workHoursEnd = 17, date = new Date()) {
+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 endHour = workHoursEnd < workHoursStart ? workHoursEnd + DAY_HOURS : workHoursEnd;
+    const duration = endHour - workHoursStart;
+    if (duration <= 0) {
+        return null;
+    }
+    const sweepEvents = [];
+    for (const zone of zones) {
         const offset = getTimezoneOffset(zone, date);
-        if (offset === null)
+        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))
+        }
+        if (duration >= DAY_HOURS) {
+            pushSweepInterval(sweepEvents, 0, DAY_HOURS * 2);
+            continue;
+        }
+        const startUTC = normalizeHourValue(workHoursStart - (offset / 60));
+        pushSweepInterval(sweepEvents, startUTC, startUTC + duration);
+        pushSweepInterval(sweepEvents, startUTC + DAY_HOURS, startUTC + DAY_HOURS + duration);
+    }
+    sweepEvents.sort((a, b) => a.time - b.time || b.delta - a.delta);
+    let activeWindows = 0;
+    let previousTime = 0;
+    let bestOverlap = null;
+    for (let i = 0; i < sweepEvents.length;) {
+        const currentTime = sweepEvents[i].time;
+        if (currentTime > previousTime && activeWindows === zones.length) {
+            const candidate = { start: previousTime, end: currentTime };
+            if (bestOverlap === null ||
+                candidate.end - candidate.start > bestOverlap.end - bestOverlap.start ||
+                (candidate.end - candidate.start === bestOverlap.end - bestOverlap.start &&
+                    candidate.start < bestOverlap.start)) {
+                bestOverlap = candidate;
+            }
+        }
+        while (i < sweepEvents.length && sweepEvents[i].time === currentTime) {
+            activeWindows += sweepEvents[i].delta;
+            i++;
+        }
+        previousTime = currentTime;
+    }
+    if (bestOverlap === 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 };
+    const overlapDuration = bestOverlap.end - bestOverlap.start;
+    if (overlapDuration >= DAY_HOURS) {
+        return { startUTC: 0, endUTC: DAY_HOURS };
+    }
+    const startUTC = normalizeHourValue(bestOverlap.start);
+    const endUTC = normalizeHourValue(bestOverlap.start + overlapDuration);
+    return { startUTC, endUTC };
 }
 /**
  * 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()) {
+function getTimezoneAbbreviation(zone, date = new Date()) {
     try {
         const fmt = new Intl.DateTimeFormat('en-US', {
             timeZone: zone,
@@ -232,7 +290,7 @@ export function getTimezoneAbbreviation(zone, date = new Date()) {
  * @param fromZone - source timezone
  * @param toZone - target timezone
  */
-export function convertBetweenZones(date, fromZone, toZone) {
+function convertBetweenZones(date, fromZone, toZone) {
     // First, interpret the date as being in fromZone
     const fromOffset = getTimezoneOffset(fromZone, date);
     const toOffset = getTimezoneOffset(toZone, date);
@@ -250,7 +308,7 @@ export function convertBetweenZones(date, fromZone, toZone) {
  * @param zoneB - second timezone
  * @param date - reference date
  */
-export function getTimezoneDifferenceHours(zoneA, zoneB, date = new Date()) {
+function getTimezoneDifferenceHours(zoneA, zoneB, date = new Date()) {
     const diff = compareZoneOffsets(zoneA, zoneB, date);
     if (diff === null)
         return null;
@@ -262,7 +320,7 @@ export function getTimezoneDifferenceHours(zoneA, zoneB, date = new Date()) {
  * @param zoneB - second timezone
  * @param date - reference date
  */
-export function isSameTimezone(zoneA, zoneB, date = new Date()) {
+function isSameTimezone(zoneA, zoneB, date = new Date()) {
     const diff = compareZoneOffsets(zoneA, zoneB, date);
     if (diff === null)
         return null;

package/dist/timezone.d.ts

@@ -33,6 +33,8 @@ export declare function compareZoneOffsets(zoneA: string, zoneB: string, date?:
 export declare function reinterpretAsZone(date: Date, targetZone: string): Date | null;
 /**
  * Check if a date is in Daylight Saving Time for a given timezone
+ * Uses a yearly-offset heuristic: sample the zone's local year and treat the
+ * maximum observed UTC offset as the DST offset for that year.
  * @param date - date to check
  * @param zone - IANA timezone string
  */
@@ -50,7 +52,10 @@ export declare function getNextDSTTransition(date: Date, zone: string): Date | n
  * @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
+ * @returns one contiguous UTC overlap window, specifically the longest
+ * contiguous overlap slice. A full-day overlap is returned as
+ * `{ startUTC: 0, endUTC: 24 }`, and wrapped overlaps are returned with
+ * `endUTC` normalized back into the 0-24 range and may be less than `startUTC`
  */
 export declare function findCommonWorkingHours(zones: string[], workHoursStart?: number, workHoursEnd?: number, date?: Date): {
     startUTC: number;