eztz

I just want to get current date and time in a timezone using ONLY it's offset in hours. I'm so done looking for proper and 100% valid names.

About

This tool can do two things:

1. get - time in any timezone as Date knowing only it's UTC time offset:
   • UTC time: eztz.get(0)
   • Almaty time (GMT+6): eztz.get(+6)
   • San Francisco time, knowing it's 13h behind Almaty: eztz.get(-13, timeInAlmaty)
2. diff - calcualte time difference (measured in hours) as number between two Date objects:
   • Time difference between Almaty and UTC: eztz.diff(timeInAlmaty, timeUtc), which returns +6
   • Time difference between Moscow and Almaty: eztz.diff(timeInMoscow, timeInAlmaty), which returns -3

NOTE: value returned by this library is just a local date shifted to match the required timezone:

// Prints 6 for me, as my local UTC offset is +6.
console.log(timeInMoscow.getTimezoneOffset() / -60);

However, In practice it does the job

console.log(timeInSanFrancisco.toLocaleString());   // 2017-10-27 17:09:06
console.log(timeInAlmaty.toLocaleString());         // 2017-10-28 06:09:06
console.log(timeInMoscow.toLocaleString());         // 2017-10-28 03:09:06
console.log(timeInMoscow.toLocaleString('en-US', {  // Oct 28, 3:09 AM
  month: 'short',
  day: 'numeric',
  hour: 'numeric',
  minute:'numeric',
  hour12: true }));

More detailed review of common usecases can be found below, in Usage section
Some info on Working Environment

Installation

This package is distributed via npm:

npm install eztz

And available at npmcdn(https://unpkg.com/):

• eztz.js
• eztz.min.js

Browser-ready:

<script src="https://unpkg.com/eztz@1.1.2/dist/umd/eztz.min.js"></script>

Usage

Read step-by-step guide below, or copy-paste compiled sample in wiki

1. Import

   var eztz = require('eztz');

2. Get current time in various timezones, specifying it's UTC time offset as first argument
   2.1. UTC

   var timeUtc = eztz.get(0);

   2.2. Pro- way to get UTC date-time

   var timeUtc = eztz.get();

   2.3. Almaty (GMT+6)

   var timeInAlmaty = eztz.get(+6);

   2.4. Moscow (GMT+3), note that + is not necessary, since +3 is just 3

   var timeInMoscow = eztz.get(3);

   2.5. San Francisco (GMT-7)

   var timeInSanFrancisco = eztz.get(-7);

   2.6. India (GMT+5:30). Offset of 5h 30m is basically 5.5h

   var timeInIndia = eztz.get(5.5);

   2.7. Fictive Time Zone, say GMT+25.852, still works

   var timeFictive = eztz.get(+25.852);

3. Time difference in hours between specified Date objects
   3.1. Calculated basically by substracting right from left

   var diffFromAlmatyToMoscow = eztz.diff(timeInAlmaty, timeInMoscow);  // +3

   3.2. Provides negated values if switch places

   var diffFromMoscowToAlmaty = eztz.diff(timeInMoscow, timeInAlmaty);  // -3

   3.3. Limits number of decimal places to 1 by default

   var diffDefault = eztz.diff(timeFictive, timeUtc);       // 25.9

   3.4. But you can specify it explicitly as third argument

   var diffDefault = eztz.diff(timeFictive, timeUtc, 1);    // 25.9

   3.5. And drop decimal part by feeding 0

   var diffRound = eztz.diff(timeFictive, timeUtc, 0);      // 26

   3.5. Or get exact value with 3

   var diffExact = eztz.diff(timeFictive, timeUtc, 3);      // 25.852

   3.6. Implemented with Math.round()

   var diffUtcIndia = eztz.diff(timeUtc, timeInIndia, 0);   // -5, not -6

4. Get date shifted against another Date
   4.1. GMT is 6h behind Almaty

   var timeGmt = eztz.get(-6, timeInAlmaty);

   4.2. San Francisco is 13h behind Almaty

   var timeSanFrancisco = eztz.get(-13, timeInAlmaty);

   4.3. Moscow is 3h ahead GMT

   var timeInMoscow = eztz.get(3, timeGmt);    // The same as eztz.get(3)

5. NOTE
   5.1. Value returned by this library is just a local date shifted to match the required timezone

   // Prints 6 for me, as my local UTC offset is +6.
   console.log(timeInMoscow.getTimezoneOffset() / -60);

   5.2. Further manipulation may produce unexpected results, for example .getTime() should actually return the same value

   console.log(timeInMoscow.getTime());                // 1509138546929
   console.log(timeInAlmaty.getTime());                // 1509149346929

6. However
   6.1. In practice it does the job

   console.log(timeInSanFrancisco.toLocaleString());   // 2017-10-27 17:09:06
   console.log(timeInAlmaty.toLocaleString());         // 2017-10-28 06:09:06
   console.log(timeInMoscow.toLocaleString());         // 2017-10-28 03:09:06
   console.log(timeInMoscow.toLocaleString('en-US', {  // Oct 28, 3:09 AM
       month: 'short',
       day: 'numeric',
       hour: 'numeric',
       minute:'numeric',
       hour12: true }));

Click to see full compiled usage example in wiki page

Working Environment

Prerequisites:

• NodeJS >= 4 to build. Current latest version is 8.8.1, LTS is 6.11.5
• NodeJS >= 8 to use auto-publishing with semantic-release
• npm, which usually comes packaged with Node
• git command line tool
• github, travis, coveralls accounts
• npm account

References

This library was developed by me to power up my github page
Thanks to Kent C. Dodds and his series on starwars-names