chronos-ts 1.1.0 → 2.0.1

package/dist/core/timezone.d.ts

@@ -0,0 +1,289 @@
+/**
+ * ChronosTimezone - Timezone handling and conversions
+ * @module ChronosTimezone
+ */
+import { TimezoneInfo, TimezoneOffset, DSTransition } from '../types';
+/**
+ * Common timezone identifiers
+ */
+export declare const TIMEZONES: {
+    readonly UTC: "UTC";
+    readonly GMT: "GMT";
+    readonly 'America/New_York': "America/New_York";
+    readonly 'America/Chicago': "America/Chicago";
+    readonly 'America/Denver': "America/Denver";
+    readonly 'America/Los_Angeles': "America/Los_Angeles";
+    readonly 'America/Phoenix': "America/Phoenix";
+    readonly 'America/Anchorage': "America/Anchorage";
+    readonly 'America/Toronto': "America/Toronto";
+    readonly 'America/Vancouver': "America/Vancouver";
+    readonly 'America/Mexico_City': "America/Mexico_City";
+    readonly 'America/Sao_Paulo': "America/Sao_Paulo";
+    readonly 'America/Buenos_Aires': "America/Buenos_Aires";
+    readonly 'America/Lima': "America/Lima";
+    readonly 'America/Bogota': "America/Bogota";
+    readonly 'Europe/London': "Europe/London";
+    readonly 'Europe/Paris': "Europe/Paris";
+    readonly 'Europe/Berlin': "Europe/Berlin";
+    readonly 'Europe/Madrid': "Europe/Madrid";
+    readonly 'Europe/Rome': "Europe/Rome";
+    readonly 'Europe/Amsterdam': "Europe/Amsterdam";
+    readonly 'Europe/Brussels': "Europe/Brussels";
+    readonly 'Europe/Vienna': "Europe/Vienna";
+    readonly 'Europe/Warsaw': "Europe/Warsaw";
+    readonly 'Europe/Prague': "Europe/Prague";
+    readonly 'Europe/Moscow': "Europe/Moscow";
+    readonly 'Europe/Istanbul': "Europe/Istanbul";
+    readonly 'Europe/Athens': "Europe/Athens";
+    readonly 'Europe/Helsinki': "Europe/Helsinki";
+    readonly 'Europe/Stockholm': "Europe/Stockholm";
+    readonly 'Europe/Oslo': "Europe/Oslo";
+    readonly 'Europe/Copenhagen': "Europe/Copenhagen";
+    readonly 'Europe/Dublin': "Europe/Dublin";
+    readonly 'Europe/Zurich': "Europe/Zurich";
+    readonly 'Asia/Tokyo': "Asia/Tokyo";
+    readonly 'Asia/Shanghai': "Asia/Shanghai";
+    readonly 'Asia/Hong_Kong': "Asia/Hong_Kong";
+    readonly 'Asia/Singapore': "Asia/Singapore";
+    readonly 'Asia/Seoul': "Asia/Seoul";
+    readonly 'Asia/Taipei': "Asia/Taipei";
+    readonly 'Asia/Bangkok': "Asia/Bangkok";
+    readonly 'Asia/Jakarta': "Asia/Jakarta";
+    readonly 'Asia/Manila': "Asia/Manila";
+    readonly 'Asia/Kuala_Lumpur': "Asia/Kuala_Lumpur";
+    readonly 'Asia/Ho_Chi_Minh': "Asia/Ho_Chi_Minh";
+    readonly 'Asia/Dubai': "Asia/Dubai";
+    readonly 'Asia/Kolkata': "Asia/Kolkata";
+    readonly 'Asia/Mumbai': "Asia/Mumbai";
+    readonly 'Asia/Karachi': "Asia/Karachi";
+    readonly 'Asia/Dhaka': "Asia/Dhaka";
+    readonly 'Asia/Tehran': "Asia/Tehran";
+    readonly 'Asia/Riyadh': "Asia/Riyadh";
+    readonly 'Asia/Jerusalem': "Asia/Jerusalem";
+    readonly 'Australia/Sydney': "Australia/Sydney";
+    readonly 'Australia/Melbourne': "Australia/Melbourne";
+    readonly 'Australia/Brisbane': "Australia/Brisbane";
+    readonly 'Australia/Perth': "Australia/Perth";
+    readonly 'Australia/Adelaide': "Australia/Adelaide";
+    readonly 'Pacific/Auckland': "Pacific/Auckland";
+    readonly 'Pacific/Fiji': "Pacific/Fiji";
+    readonly 'Pacific/Honolulu': "Pacific/Honolulu";
+    readonly 'Africa/Cairo': "Africa/Cairo";
+    readonly 'Africa/Johannesburg': "Africa/Johannesburg";
+    readonly 'Africa/Lagos': "Africa/Lagos";
+    readonly 'Africa/Nairobi': "Africa/Nairobi";
+    readonly 'Africa/Casablanca': "Africa/Casablanca";
+};
+export type TimezoneId = keyof typeof TIMEZONES | string;
+/**
+ * ChronosTimezone - Handles timezone operations and conversions
+ *
+ * This class provides comprehensive timezone handling including:
+ * - Timezone information retrieval
+ * - Offset calculations
+ * - DST detection
+ * - Timezone conversions
+ *
+ * @example
+ * ```typescript
+ * // Get timezone info
+ * const tz = ChronosTimezone.create('America/New_York');
+ * console.log(tz.offset); // -5 or -4 depending on DST
+ *
+ * // Check DST
+ * console.log(tz.isDST(new Date())); // true/false
+ *
+ * // Convert between timezones
+ * const utcDate = new Date();
+ * const localDate = ChronosTimezone.convert(utcDate, 'UTC', 'America/New_York');
+ * ```
+ */
+export declare class ChronosTimezone {
+    private _identifier;
+    private _originalOffset;
+    private _cachedOffset;
+    private _cachedDate;
+    /**
+     * Create a new ChronosTimezone
+     */
+    constructor(identifier?: TimezoneId);
+    /**
+     * Normalize timezone identifier
+     */
+    private _normalizeIdentifier;
+    /**
+     * Parse offset string to hours
+     */
+    private _parseOffsetString;
+    /**
+     * Create a timezone instance
+     */
+    static create(identifier?: TimezoneId): ChronosTimezone;
+    /**
+     * Create UTC timezone
+     */
+    static utc(): ChronosTimezone;
+    /**
+     * Create timezone from local system timezone
+     */
+    static local(): ChronosTimezone;
+    /**
+     * Create timezone from offset in hours
+     */
+    static fromOffset(offsetHours: number): ChronosTimezone;
+    /**
+     * Get the local system timezone identifier
+     */
+    static localIdentifier(): string;
+    /**
+     * Get timezone identifier
+     * Returns the original offset string if created from an offset, otherwise returns the IANA identifier
+     */
+    get identifier(): string;
+    /**
+     * Get the internal IANA timezone identifier (used for Intl operations)
+     */
+    get ianaIdentifier(): string;
+    /**
+     * Get timezone name (alias for identifier)
+     */
+    get name(): string;
+    /**
+     * Get timezone abbreviation for a given date
+     */
+    getAbbreviation(date?: Date): string;
+    /**
+     * Get full timezone name for a given date
+     */
+    getFullName(date?: Date): string;
+    /**
+     * Get UTC offset in minutes for a given date
+     */
+    getOffsetMinutes(date?: Date): number;
+    /**
+     * Parse Intl formatter parts to components
+     */
+    private _parseIntlParts;
+    /**
+     * Get UTC offset in hours for a given date
+     */
+    getOffsetHours(date?: Date): number;
+    /**
+     * Get UTC offset as string (e.g., "+05:30", "-08:00")
+     */
+    getOffsetString(date?: Date): string;
+    /**
+     * Get complete offset information
+     */
+    getOffset(date?: Date): TimezoneOffset;
+    /**
+     * Check if DST is in effect for a given date
+     */
+    isDST(date?: Date): boolean;
+    /**
+     * Check if timezone observes DST
+     */
+    observesDST(): boolean;
+    /**
+     * Get the next DST transition
+     */
+    getNextDSTTransition(from?: Date): DSTransition | null;
+    /**
+     * Binary search to find exact DST transition time
+     */
+    private _findExactTransition;
+    /**
+     * Convert a date to this timezone (returns formatted string)
+     */
+    format(date: Date, formatOptions?: Intl.DateTimeFormatOptions): string;
+    /**
+     * Get date components in this timezone
+     */
+    getComponents(date: Date): {
+        year: number;
+        month: number;
+        day: number;
+        hour: number;
+        minute: number;
+        second: number;
+        dayOfWeek: number;
+    };
+    /**
+     * Convert a date from one timezone to another
+     */
+    static convert(date: Date, from: TimezoneId, to: TimezoneId): Date;
+    /**
+     * Convert a UTC date to this timezone
+     */
+    fromUTC(date: Date): Date;
+    /**
+     * Convert a date in this timezone to UTC
+     */
+    toUTC(date: Date): Date;
+    /**
+     * Get comprehensive timezone information
+     */
+    getInfo(date?: Date): TimezoneInfo;
+    /**
+     * Check if two timezones are equivalent at a given moment
+     */
+    equals(other: ChronosTimezone | string, date?: Date): boolean;
+    /**
+     * Check if this is the same timezone identifier
+     */
+    isSame(other: ChronosTimezone | string): boolean;
+    /**
+     * Get all available timezone identifiers
+     * Note: This returns common timezones. Use Intl.supportedValuesOf('timeZone') for all.
+     */
+    static getAvailableTimezones(): string[];
+    /**
+     * Check if a timezone identifier is valid
+     */
+    static isValid(identifier: string): boolean;
+    /**
+     * Get timezones grouped by region
+     */
+    static getTimezonesByRegion(): Record<string, string[]>;
+    /**
+     * Find timezones that match a given offset
+     */
+    static findByOffset(offsetHours: number, date?: Date): ChronosTimezone[];
+    /**
+     * Get current time in a specific timezone
+     */
+    static now(identifier: TimezoneId): Date;
+    /**
+     * Convert to string
+     */
+    toString(): string;
+    /**
+     * Convert to JSON
+     */
+    toJSON(): object;
+    /**
+     * Get primitive value
+     */
+    valueOf(): string;
+}
+/**
+ * Pre-created timezone instances for common timezones
+ */
+export declare const Timezones: {
+    readonly UTC: ChronosTimezone;
+    readonly Local: ChronosTimezone;
+    readonly Eastern: ChronosTimezone;
+    readonly Central: ChronosTimezone;
+    readonly Mountain: ChronosTimezone;
+    readonly Pacific: ChronosTimezone;
+    readonly London: ChronosTimezone;
+    readonly Paris: ChronosTimezone;
+    readonly Berlin: ChronosTimezone;
+    readonly Tokyo: ChronosTimezone;
+    readonly Shanghai: ChronosTimezone;
+    readonly Singapore: ChronosTimezone;
+    readonly Dubai: ChronosTimezone;
+    readonly Mumbai: ChronosTimezone;
+    readonly Sydney: ChronosTimezone;
+    readonly Auckland: ChronosTimezone;
+};