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

$3

``bash
npm install @vinit121/tz-utils
`

$3

`bash
bun add @vinit121/tz-utils
`

---

🚀 Usage

$3

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

---

$3

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

console.log(utcDate)
`

---

$3

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

console.log(localDate)
`

---

$3

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

console.log(timezone)
`

---

$3

`ts
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

$3

Convert local system time to UTC.

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

---

$3

Convert UTC time to local system time.

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

---

$3

Get system timezone name.

`ts
getSystemTimezone(): string
`

---

$3

Get system timezone offset in minutes.

`ts
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

---