@calipsa/tz-utils

JavaScript timezone utils

Usage no npm install needed!

<script type="module">
  import calipsaTzUtils from 'https://cdn.skypack.dev/@calipsa/tz-utils';
</script>

README

@calipsa/tz-utils

NPM version Downloads Dependency status Dev Dependency status

tz-utils is a lightweight library to convert/format dates from one timezone to a different timezone.

Installation

# using npm:
npm install --save @calipsa/tz-utils

# or if you like yarn:
yarn add @calipsa/tz-utils

Available Methods

formatDateTz

You can use this function to convert the date to a different timezone.

Param Type Required Description
date Date || Number || String yes Date you want to format. It can be a date object, date string or a number in milliseconds
format String yes The format you want to convert date to.
timezone String yes The timezone you want to convert to, can be full timezone names like America/New_York or abbreviations like EST5EDT

Usage

import {
  formatDateTz,
} from '@calipsa/tz-utils'

const date = new Date('2021-10-10T03:00:00.005Z')

const dateInNYTz = formatDateTz(date, 'yyyy-MM-dd hh:mm:ss', 'America/New_York')

names

It is a list of all timezones accepted by date-fns library.

Usage

import {
  names,
} from '@calipsa/tz-utils'

// names is an array containing all timezones as string values

deprecatedNames

It is a list of all deprecated timezones.

Usage

import {
  deprecatedNames,
} from '@calipsa/tz-utils'

// deprecatedNames is an array containing all deprecated timezones as string values

notWorkingInDateFns

It is a list of all timezones that are not compatible with date-fns library.

Usage

import {
  notWorkingInDateFns,
} from '@calipsa/tz-utils'

// notWorkingInDateFns is an array containing all non-compatible timezones as string values

offset

You can use this function to get the time difference of the passed timezone from UTC. The return value will be a number, representing difference in minutes.

Param Type Required Description
timezone String yes The timezone you want to get offset for. It can be full timezone names like America/New_York or abbreviations like EST5EDT

Usage

import {
  offset,
} from '@calipsa/tz-utils'

const offsetNYC = offset('America/New_York') // will return -240 (GMT-4)

const offsetKolkata = offset('Asia/Kolkata') // will return 330 (GMT+5:30)

offsetFormattedShort

You can use this function to get the time difference of the passed timezone from UTC. The return value will be a string like GMT-4 or GMT+5:30.

Param Type Required Description
timezone String yes The timezone you want to get offset for. It can be full timezone names like America/New_York or abbreviations like EST5EDT

Usage

import {
  offsetFormattedShort,
} from '@calipsa/tz-utils'

const offsetNYC = offset('America/New_York') // will return GMT-4

const offsetKolkata = offset('Asia/Kolkata') // will return GMT+5:30

offsetFormattedLong

You can use this function to get the time difference of the passed timezone from UTC. The return value will be a string like GMT-04:00.

Param Type Required Description
timezone String yes The timezone you want to get offset for. It can be full timezone names like America/New_York or abbreviations like EST5EDT

Usage

import {
  offsetFormattedLong,
} from '@calipsa/tz-utils'

const offsetNYC = offset('America/New_York') // will return GMT-04:00

const offsetKolkata = offset('Asia/Kolkata') // will return GMT+05:30

suggested

You can use this function to get your system's timezone. It will return string representing your timezone like America/New_York.

Usage

import {
  suggested,
} from '@calipsa/tz-utils'

const timezone = suggested()

Usage

import {
  formatDateTz,
  names,
  offset,
  offsetFormattedLong,
  offsetFormattedShort,
  suggested,
} from '@calipsa/tz-utils'

// ...