possible-tz

A lightweight, zero-dependency library to determine possible IANA timezones by comparing local time and UTC time.

Overview

This library helps you identify which timezones a user might be in when you know their local time and the corresponding UTC time. This is particularly useful for systems that need to automatically detect a user's timezone without relying on geolocation, using only system clock information.

Key Features

• High Accuracy: Determines timezones by comparing specific moments in time.
• DST Support: Naturally handles Daylight Saving Time transitions.
• Comprehensive: Supports non-standard offsets (e.g., India UTC+5:30 or Nepal UTC+5:45).
• High Performance: Caches formatters for efficient repeated lookups.
• Lightweight: Zero external dependencies, leveraging the built-in Intl.DateTimeFormat API.

Installation

npm install possible-tz

Quick Start

import { getPossibleTimezones, CheckingDateTime, UtcDateTime } from 'possible-tz';

// Example for Tokyo (UTC+9)
// January 1, 2024, 18:00:00 local time
const local = new CheckingDateTime(2024, 0, 1, 18, 0, 0);

// At the same moment, it was 09:00:00 UTC
const utc = new UtcDateTime(2024, 0, 1, 9, 0, 0);

// Get the list of matching timezones
const timezones = getPossibleTimezones(local, utc);

console.log(timezones);
// Output: ['Asia/Chita', 'Asia/Tokyo', 'Pacific/Palau', ...]

API Reference

getPossibleTimezones(local, utc)

The main function that takes two time objects and returns an array of IANA timezone strings.

• Parameters:
  • local: CheckingDateTime - The local time to check.
  • utc: UtcDateTime - The reference UTC time.
• Returns: string[] - Array of matching IANA timezone identifiers.

CheckingDateTime

A class representing the local time components. Constructor: (year, month, date, hours, minutes, seconds?)

• month is 0-indexed (0 = January).
• seconds defaults to 0.

UtcDateTime

A class representing the UTC reference time components. Constructor: (year, month, date, hours, minutes, seconds?)

• month is 0-indexed (0 = January).
• seconds defaults to 0.

License

MIT