chronos-ts
Version:
A comprehensive TypeScript library for date and time manipulation, inspired by Carbon PHP. Features immutable API, intervals, periods, timezones, and i18n support.
291 lines (290 loc) • 9.32 kB
TypeScript
/**
* 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 _extraMinutes;
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;
};