timezone-convert

Convert between timezone formats

timezone-convert

• timezone-convert
  • Overview
    • Important notes
      • Imperfect accuracy
      • Partial 'etcetera' and 'backward' zones for IANA
  • Features
  • Usage
    • CLI
    • Programatic
      • Install package
      • Import & use:
  • Releasing
  • License

Overview

timezone-convert is a small and efficient utility library and CLI for (smart parsing and) converting between timezone formats.

Important notes

Imperfect accuracy

The primary goal of the project is to focus on converting from one timezone format into a roughly accurate representation in other formats for possible of use with other libraries (e.g Windows display name from calendar => TZID / IANA for datetime manipulation), and AS SIMPLE AS POSSIBLE, things like extensive array mapping (Windows id => Multiple IANA ids) won't be available.

Partial 'etcetera' and 'backward' zones for IANA

The project will only supports the ETC IANA ids that is also used by Windows, and only supports the commonly-used backward IANA ids (like America/Indianapolis), uncommon ids like WET, W-SU is not supported, but in a fast-check, this library should support a few more commonly-used ids than windows-iana.

Features

• Parsing and converting between:
  • Windows display name
  • Windows time zone id
  • IANA (Olsen) tzdb ids
• Auto parse from any formats, just parseTzAuto(str)

Usage

CLI

npx timezone-convert "Europe/Athens"
# Outputs a JSON string of the parsed timezone
# { iana, windowsId, windowsDisplay }

# Example use with `jq`
npx -y timezone-convert Asia/Saigon | jq '.windowsDisplay'

Programatic

Install package

# npm
npm install timezone-convert

# bun
bun add timezone-convert

# pnpm (recommended)
pnpm install timezone-convert

Import & use:

// ESM
import { parseTzAuto } from 'timezone-convert'

const bucharestTz = parseTzAuto('Europe/Bucharest')

Releasing

Releases are version-first and manual: go to Actions → Release → Run workflow, enter the version to ship (e.g. 1.5.0, without a leading v) and run it.

The workflow validates that version against package.json, runs the full check gate (lint + types + tests with coverage), builds, then lets changelogen derive the changelog from conventional commits, bump package.json, write CHANGELOG.md, commit and tag v<version>. It pushes that commit and tag, creates the GitHub release with the generated notes, and finally publishes to npm using trusted publishing (OIDC — no NPM_TOKEN secret). Enable the dry-run input to stop right before the push, release and publish.

There is no tag-triggered publish: pushing a tag on its own publishes nothing, so a tag can never publish the same version twice.

One-time setup before the first run:

• publish the package once by hand — npm only lets you configure a trusted publisher for a package that already exists
• on npmjs.com → the package → Settings → Trusted Publisher, add this repository with the workflow filename release.yml

To preview a release locally:

pnpm run release:check 1.5.0 # validate a version against package.json
pnpm run release:preview     # print the changelog the next release would get

License