timefyi

Pure TypeScript timezone engine for developers. Look up current time in any IANA timezone, calculate time differences between zones, convert times, generate 24-hour comparison tables, and find overlapping business hours -- all with zero dependencies.

Try the interactive tools at timefyi.com -- world clock, timezone converter, and business hours overlap finder.

Table of Contents

• Install
• Quick Start
• What You Can Do
  • How Timezone Conversion Works
  • Hourly Comparison Table
  • Business Hours Overlap
• API Reference
• TypeScript Types
• Features
• Learn More About Time Zones
• Also Available for Python
• FYIPedia Developer Tools
• License

Install

npm install timefyi

Works in Node.js, Deno, Bun, and browsers (ESM).

Quick Start

import { getCurrentTime, getTimeDifference, convertTime, formatUtcOffset } from "timefyi";

// Current time in any IANA timezone
const seoul = getCurrentTime("Asia/Seoul");
console.log(seoul.utcOffset);      // "+09:00"
console.log(seoul.abbreviation);   // "KST"
console.log(seoul.isDst);          // false
console.log(seoul.currentTime);    // "2026-03-04T14:30:00"

// Time difference between two cities
const diff = getTimeDifference("America/New_York", "Asia/Seoul");
console.log(diff.offsetDiff);      // 14
console.log(diff.description);     // "+14h"

// Convert a specific time between timezones
const converted = convertTime("09:00", "America/New_York", "Asia/Seoul");
console.log(converted);            // "23:00"

// Format UTC offset from minutes
console.log(formatUtcOffset(540));   // "+09:00"
console.log(formatUtcOffset(-300));  // "-05:00"
console.log(formatUtcOffset(330));   // "+05:30"

What You Can Do

How Timezone Conversion Works

This engine uses the Intl.DateTimeFormat API built into JavaScript runtimes (V8, SpiderMonkey, JSC). No timezone database is bundled -- it uses the ICU data already present in your runtime.

This approach has several advantages:

• Always up to date: Timezone rules change frequently (governments adjust DST, create new zones). Your runtime's ICU data is updated with the OS, so conversions stay correct without package updates.
• Zero bundle size: No timezone database shipped. The IANA timezone database is ~300KB compressed; this package adds 0 bytes of timezone data.
• DST-aware: Daylight saving time transitions are handled automatically by the runtime. The engine detects DST status by comparing January and July offsets.
• Half-hour offsets: Zones like Asia/Kolkata (+05:30) and Asia/Kathmandu (+05:45) are handled natively.

The world is divided into roughly 38 time zones (including half-hour and 45-minute offsets). Some notable examples:

| Timezone | UTC Offset | Abbreviation | Notable Feature | |----------|-----------|-------------|-----------------| | America/New_York | -05:00 / -04:00 | EST / EDT | US Eastern, DST observed | | Europe/London | +00:00 / +01:00 | GMT / BST | Prime Meridian, DST observed | | Asia/Seoul | +09:00 | KST | No DST since 1988 | | Asia/Kolkata | +05:30 | IST | Half-hour offset, 1.4B people | | Asia/Kathmandu | +05:45 | NPT | Only 45-minute offset zone | | Pacific/Chatham | +12:45 / +13:45 | CHAST / CHADT | Furthest ahead, 45-min offset |

Learn more: World Clock · IANA Time Zone Database · Time Zone Converter

Hourly Comparison Table

import { getHourlyComparison } from "timefyi";

// Generate a 24-hour comparison between New York and Seoul
const rows = getHourlyComparison("America/New_York", "Asia/Seoul");
console.log(rows[0]);   // { hour1: "00:00", hour2: "14:00" }
console.log(rows[9]);   // { hour1: "09:00", hour2: "23:00" }
console.log(rows.length); // 24

Learn more: Time Zone Comparison · REST API Docs

Business Hours Overlap

Finding meeting times across multiple time zones is one of the most common scheduling challenges for distributed teams. This function calculates the overlapping window where all specified time zones fall within business hours (default 09:00-17:00).

import { getBusinessHoursOverlap } from "timefyi";

// Find overlapping business hours (default 09:00-17:00)
const result = getBusinessHoursOverlap([
  "America/New_York",
  "Europe/London",
]);
console.log(result.hasOverlap);     // true
console.log(result.overlapHours);   // 3
console.log(result.overlapStart);   // "14:00"
console.log(result.overlapEnd);     // "17:00"

// Three-way overlap with custom hours
const threeWay = getBusinessHoursOverlap(
  ["America/New_York", "Europe/London", "Asia/Seoul"],
  9, 17,
);
console.log(threeWay.hasOverlap);   // false (no 3-way overlap)

Learn more: Business Hours Calculator · OpenAPI Spec

API Reference

Time Lookup

| Function | Description | |----------|-------------| | getCurrentTime(timezone) -> CityTimeInfo | Current time, UTC offset, abbreviation, DST status | | formatUtcOffset(offsetMinutes) -> string | Format minutes as "+HH:MM" / "-HH:MM" |

Timezone Comparison

| Function | Description | |----------|-------------| | getTimeDifference(tz1, tz2) -> TimeDifferenceInfo | Offset difference in hours and minutes | | convertTime(timeStr, fromTz, toTz) -> string | Convert "HH:MM" between timezones | | getHourlyComparison(tz1, tz2, hours?) -> HourlyRow[] | 24-hour side-by-side comparison table |

Business Hours

| Function | Description | |----------|-------------| | getBusinessHoursOverlap(timezones, startHour?, endHour?) -> OverlapResult | Find overlapping business hours across multiple zones |

TypeScript Types

import type {
  CityTimeInfo,
  TimeDifferenceInfo,
  HourlyRow,
  OverlapResult,
} from "timefyi";

Features

• Current time lookup: Any IANA timezone with UTC offset, abbreviation, and DST status
• Time difference: Calculate offset between any two timezones (including half-hour zones)
• Time conversion: Convert "HH:MM" strings between timezones
• Hourly comparison: Generate 24-hour side-by-side tables for scheduling
• Business hours overlap: Find meeting windows across multiple timezones
• DST-aware: Automatic daylight saving time detection
• Zero dependencies: Uses built-in Intl.DateTimeFormat, no timezone database bundled
• Type-safe: Full TypeScript with strict mode
• Tree-shakeable: ESM with named exports
• Fast: All computations under 1ms

Learn More About Time Zones

• Tools: World Clock · Time Zone Converter
• Browse: Time Zones · Countries
• API: REST API Docs · OpenAPI Spec
• Python: PyPI Package

Also Available for Python

pip install timefyi

See the Python package on PyPI.

FYIPedia Developer Tools

Part of the FYIPedia open-source developer tools ecosystem.

| Package | PyPI | npm | Description | |---------|------|-----|-------------| | colorfyi | PyPI | npm | Color conversion, WCAG contrast, harmonies -- colorfyi.com | | emojifyi | PyPI | npm | Emoji encoding & metadata for 3,953 emojis -- emojifyi.com | | symbolfyi | PyPI | npm | Symbol encoding in 11 formats -- symbolfyi.com | | unicodefyi | PyPI | npm | Unicode lookup with 17 encodings -- unicodefyi.com | | fontfyi | PyPI | npm | Google Fonts metadata & CSS -- fontfyi.com | | distancefyi | PyPI | npm | Haversine distance & travel times -- distancefyi.com | | timefyi | PyPI | npm | Timezone ops & business hours -- timefyi.com | | namefyi | PyPI | npm | Korean romanization & Five Elements -- namefyi.com | | unitfyi | PyPI | npm | Unit conversion, 220 units -- unitfyi.com | | holidayfyi | PyPI | npm | Holiday dates & Easter calculation -- holidayfyi.com | | cocktailfyi | PyPI | -- | Cocktail ABV, calories, flavor -- cocktailfyi.com | | fyipedia | PyPI | -- | Unified CLI: fyi color info FF6B35 -- fyipedia.com | | fyipedia-mcp | PyPI | -- | Unified MCP hub for AI assistants -- fyipedia.com |

License

MIT