ts-time-utils 1.1.0 → 3.0.0

package/dist/plugins.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Plugin system for extending ChainedDate with custom methods
+ *
+ * @example
+ * ```ts
+ * import { extend } from 'ts-time-utils/plugins';
+ * import { ChainedDate } from 'ts-time-utils/chain';
+ *
+ * // Define plugin methods
+ * extend('myPlugin', {
+ *   nextMonday(this: ChainedDate): ChainedDate {
+ *     const day = this.weekday();
+ *     const daysUntilMonday = day === 0 ? 1 : 8 - day;
+ *     return this.add(daysUntilMonday, 'days');
+ *   }
+ * });
+ *
+ * // Use plugin methods
+ * chain(new Date()).nextMonday().format('YYYY-MM-DD');
+ * ```
+ */
+/**
+ * Initialize the plugin system with ChainedDate class
+ * This is called automatically when chain.js is imported
+ * @internal
+ */
+export declare function __initPluginSystem(ChainedDateClass: any): void;
+/**
+ * Plugin function type - methods receive ChainedDate instance as `this`
+ */
+export type PluginFunction = (this: any, ...args: any[]) => any;
+/**
+ * Plugin definition - map of method names to functions
+ */
+export interface Plugin {
+    [methodName: string]: PluginFunction;
+}
+/**
+ * Extend ChainedDate with custom methods
+ *
+ * @param pluginName - Unique name for the plugin
+ * @param methods - Object mapping method names to functions
+ *
+ * @example
+ * ```ts
+ * extend('businessDays', {
+ *   addBusinessDays(this: ChainedDate, days: number): ChainedDate {
+ *     let current = this.clone();
+ *     let remaining = days;
+ *
+ *     while (remaining > 0) {
+ *       current = current.add(1, 'days');
+ *       if (current.isWeekday()) remaining--;
+ *     }
+ *
+ *     return current;
+ *   }
+ * });
+ *
+ * chain(new Date()).addBusinessDays(5);
+ * ```
+ */
+export declare function extend(pluginName: string, methods: Plugin): void;
+/**
+ * Remove a plugin and its methods from ChainedDate
+ *
+ * @param pluginName - Name of the plugin to uninstall
+ *
+ * @example
+ * ```ts
+ * uninstall('businessDays');
+ * ```
+ */
+export declare function uninstall(pluginName: string): void;
+/**
+ * Get list of all registered plugin names
+ *
+ * @returns Array of plugin names
+ *
+ * @example
+ * ```ts
+ * getRegisteredPlugins(); // ['businessDays', 'myPlugin']
+ * ```
+ */
+export declare function getRegisteredPlugins(): string[];
+/**
+ * Get list of methods provided by a plugin
+ *
+ * @param pluginName - Name of the plugin
+ * @returns Array of method names, or empty array if plugin not found
+ *
+ * @example
+ * ```ts
+ * getPluginMethods('businessDays'); // ['addBusinessDays', 'subtractBusinessDays']
+ * ```
+ */
+export declare function getPluginMethods(pluginName: string): string[];
+/**
+ * Check if a plugin is registered
+ *
+ * @param pluginName - Name of the plugin
+ * @returns True if plugin is registered
+ *
+ * @example
+ * ```ts
+ * isPluginRegistered('businessDays'); // true
+ * ```
+ */
+export declare function isPluginRegistered(pluginName: string): boolean;
+/**
+ * Declare plugin methods for TypeScript support
+ *
+ * Use module augmentation to add type definitions for your plugin methods:
+ *
+ * @example
+ * ```ts
+ * import { ChainedDate } from 'ts-time-utils/chain';
+ *
+ * declare module 'ts-time-utils/chain' {
+ *   interface ChainedDate {
+ *     addBusinessDays(days: number): ChainedDate;
+ *     subtractBusinessDays(days: number): ChainedDate;
+ *   }
+ * }
+ * ```
+ */
+export interface PluginDeclaration {
+}
+//# sourceMappingURL=plugins.d.ts.map

package/dist/plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../src/plugins.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA0BH;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,gBAAgB,EAAE,GAAG,QAEvD;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,CAAC;CACtC;AAcD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAwBhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAqBlD;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,EAAE,CAE/C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAG7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,iBAAiB;CAAG"}

package/dist/plugins.js

@@ -0,0 +1,173 @@
+/**
+ * Plugin system for extending ChainedDate with custom methods
+ *
+ * @example
+ * ```ts
+ * import { extend } from 'ts-time-utils/plugins';
+ * import { ChainedDate } from 'ts-time-utils/chain';
+ *
+ * // Define plugin methods
+ * extend('myPlugin', {
+ *   nextMonday(this: ChainedDate): ChainedDate {
+ *     const day = this.weekday();
+ *     const daysUntilMonday = day === 0 ? 1 : 8 - day;
+ *     return this.add(daysUntilMonday, 'days');
+ *   }
+ * });
+ *
+ * // Use plugin methods
+ * chain(new Date()).nextMonday().format('YYYY-MM-DD');
+ * ```
+ */
+// Import ChainedDate class directly - safe because chain.js doesn't import plugins.js
+// We need the actual class (not just the type) to modify its prototype
+let ChainedDateConstructor = null;
+/**
+ * Get ChainedDate class lazily to ensure it's fully initialized
+ */
+function getChainedDate() {
+    if (!ChainedDateConstructor) {
+        // Use dynamic import that works in both CJS and ESM
+        try {
+            // Try ESM import path first
+            ChainedDateConstructor = globalThis.__chainedDateClass;
+            if (!ChainedDateConstructor) {
+                // Fallback: The class will be set by chain.js when it loads
+                throw new Error('ChainedDate not yet loaded. Import chain.js before using plugins.');
+            }
+        }
+        catch (e) {
+            throw new Error('ChainedDate class not available. Ensure chain.js is imported before registering plugins.');
+        }
+    }
+    return ChainedDateConstructor;
+}
+/**
+ * Initialize the plugin system with ChainedDate class
+ * This is called automatically when chain.js is imported
+ * @internal
+ */
+export function __initPluginSystem(ChainedDateClass) {
+    ChainedDateConstructor = ChainedDateClass;
+}
+const registry = {};
+/**
+ * Extend ChainedDate with custom methods
+ *
+ * @param pluginName - Unique name for the plugin
+ * @param methods - Object mapping method names to functions
+ *
+ * @example
+ * ```ts
+ * extend('businessDays', {
+ *   addBusinessDays(this: ChainedDate, days: number): ChainedDate {
+ *     let current = this.clone();
+ *     let remaining = days;
+ *
+ *     while (remaining > 0) {
+ *       current = current.add(1, 'days');
+ *       if (current.isWeekday()) remaining--;
+ *     }
+ *
+ *     return current;
+ *   }
+ * });
+ *
+ * chain(new Date()).addBusinessDays(5);
+ * ```
+ */
+export function extend(pluginName, methods) {
+    if (registry[pluginName]) {
+        throw new Error(`Plugin "${pluginName}" is already registered. Use a different name or uninstall first.`);
+    }
+    // Get ChainedDate class and save original methods before overwriting
+    const ChainedDateClass = getChainedDate();
+    const originalMethods = new Map();
+    Object.entries(methods).forEach(([methodName, fn]) => {
+        // Save original method if it exists
+        if (methodName in ChainedDateClass.prototype) {
+            const original = ChainedDateClass.prototype[methodName];
+            if (typeof original === 'function') {
+                originalMethods.set(methodName, original);
+            }
+            console.warn(`Method "${methodName}" already exists on ChainedDate and will be overwritten`);
+        }
+        // Add the plugin method
+        ChainedDateClass.prototype[methodName] = fn;
+    });
+    // Register the plugin with its original methods
+    registry[pluginName] = { plugin: methods, originalMethods };
+}
+/**
+ * Remove a plugin and its methods from ChainedDate
+ *
+ * @param pluginName - Name of the plugin to uninstall
+ *
+ * @example
+ * ```ts
+ * uninstall('businessDays');
+ * ```
+ */
+export function uninstall(pluginName) {
+    const entry = registry[pluginName];
+    if (!entry) {
+        throw new Error(`Plugin "${pluginName}" is not registered`);
+    }
+    // Get ChainedDate class and restore/remove methods
+    const ChainedDateClass = getChainedDate();
+    Object.keys(entry.plugin).forEach((methodName) => {
+        // If there was an original method, restore it
+        const original = entry.originalMethods.get(methodName);
+        if (original) {
+            ChainedDateClass.prototype[methodName] = original;
+        }
+        else {
+            // Otherwise, delete the method entirely
+            delete ChainedDateClass.prototype[methodName];
+        }
+    });
+    // Remove from registry
+    delete registry[pluginName];
+}
+/**
+ * Get list of all registered plugin names
+ *
+ * @returns Array of plugin names
+ *
+ * @example
+ * ```ts
+ * getRegisteredPlugins(); // ['businessDays', 'myPlugin']
+ * ```
+ */
+export function getRegisteredPlugins() {
+    return Object.keys(registry);
+}
+/**
+ * Get list of methods provided by a plugin
+ *
+ * @param pluginName - Name of the plugin
+ * @returns Array of method names, or empty array if plugin not found
+ *
+ * @example
+ * ```ts
+ * getPluginMethods('businessDays'); // ['addBusinessDays', 'subtractBusinessDays']
+ * ```
+ */
+export function getPluginMethods(pluginName) {
+    const entry = registry[pluginName];
+    return entry ? Object.keys(entry.plugin) : [];
+}
+/**
+ * Check if a plugin is registered
+ *
+ * @param pluginName - Name of the plugin
+ * @returns True if plugin is registered
+ *
+ * @example
+ * ```ts
+ * isPluginRegistered('businessDays'); // true
+ * ```
+ */
+export function isPluginRegistered(pluginName) {
+    return pluginName in registry;
+}

package/dist/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/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/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/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/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"}