tz-utils

Lightweight timezone utilities for Node.js and Bun. Convert local system time ↔ UTC safely with zero dependencies.

Built for Node 20+ and Bun, with simple, predictable behavior.

✨ Features

• ✅ Local system time → UTC
• ✅ UTC → local system time
• ✅ Automatic system timezone detection
• ✅ DST-safe (handled by system timezone rules)
• ✅ Zero dependencies
• ✅ Tiny footprint
• ✅ TypeScript support out of the box

📦 Installation

Using npm

npm install @vinit121/tz-utils

Using Bun

bun add @vinit121/tz-utils

🚀 Usage

Import

import {
  localToUTC,
  utcToLocal,
  getSystemTimezone,
  getSystemTimezoneOffset
} from "@vinit121/tz-utils"

Convert local time → UTC

const localDate = new Date()
const utcDate = localToUTC(localDate)

console.log(utcDate)

Convert UTC → local time

const utcDate = new Date("2026-01-01T10:00:00Z")
const localDate = utcToLocal(utcDate)

console.log(localDate)

Get system timezone

const timezone = getSystemTimezone()
// Example: "Asia/Kolkata"

console.log(timezone)

Get system timezone offset

const offset = getSystemTimezoneOffset()
// Example: -330 for IST

console.log(offset)

🧠 How it works

• Uses JavaScript’s native Date and Intl APIs
• Reads system timezone automatically
• Applies timezone offset safely
• No hardcoded offsets
• No manual timezone math

⚠️ Important Notes

• This library works with the system timezone only
• It does not convert between arbitrary timezones (e.g. IST → PST)
• For request-scoped or multi-timezone apps, use a context-based solution

🛠 API Reference

localToUTC(date)

Convert local system time to UTC.

localToUTC(input: Date | string | number): Date

utcToLocal(date)

Convert UTC time to local system time.

utcToLocal(input: Date | string | number): Date

getSystemTimezone()

Get system timezone name.

getSystemTimezone(): string

getSystemTimezoneOffset()

Get system timezone offset in minutes.

getSystemTimezoneOffset(): number

🧪 Supported Environments

• Node.js 20+
• Bun
• TypeScript
• Modern browsers (bundlers)

📄 License

MIT © Vinit Pratap

🌱 Roadmap (future ideas)

• ISO string helpers
• Temporal API support (Node 20+)
• Request-scoped timezone context
• Formatting utilities