Returns a JavaScript date object using the UTC timezone with optional offsets to adjust the hour, minute, second or millisecond.

Table of contents

• Pre-requisites
• Setup
  • Install
  • Usage
    • Node.js
    • Native ES modules or TypeScript
• API Reference
  • UTCTimeOpts
  • utcTime([UTCTimeOps])
  • utcTimeSync([UTCTimeOpts])
• License

Pre-requisites

• Node.js >= 8.9.0
• NPM >= 5.5.1 (NPM comes with Node.js so there is no need to install separately.)

Setup

Install

# Install via NPM
$ npm install --save @motss/utc-time

Usage

Node.js

const {
  utcTime,
  // utcTimeSync,
} = require('@motss/utc-time');

void async function main() {
  /** NOTE: Assuming today's date is '2020-02-02', */
  const defaultUTCDatetime = await utcTime(); // utcTimeSync();
  const defaultUTCDatetimeWithOffsets = await utcTime({
    offset: {
      hour: 3,
      minute: 2,
      second: 1,
      millisecond: 0,
    },
  });
  const specifiedUTCDatetime = await utcTime({
    startDatetime: '2033-03-03T03:33:33.333Z',
  });
  
  assert(defaultUTCDatetime, new Date('2020-02-02T00:00:00.000Z')); // OK
  assert(defaultUTCDatetimeWithOffsets, new Date('2020-02-02T03:02:01.000Z')); // OK
  assert(specifiedUTCDatetime, new Date('2033-03-03T03:33:33.333Z')); // OK
}();

Native ES modules or TypeScript

// @ts-check

import {
  utcTime,
  // utcTimeSync,
} from '@motss/utc-time';

void async function main() {
  /** NOTE: Assuming today's date is '2020-02-02', */
  const defaultUTCDatetime = await utcTime(); // utcTimeSync();
  const defaultUTCDatetimeWithOffsets = await utcTime({
    offset: {
      hour: 3,
      minute: 2,
      second: 1,
      millisecond: 0,
    },
  });
  const specifiedUTCDatetime = await utcTime({
    startDatetime: '2033-03-03T03:33:33.333Z',
  });
  
  assert(defaultUTCDatetime, new Date('2020-02-02T00:00:00.000Z')); // OK
  assert(defaultUTCDatetimeWithOffsets, new Date('2020-02-02T03:02:01.000Z')); // OK
  assert(specifiedUTCDatetime, new Date('2033-03-03T03:33:33.333Z')); // OK
}();

API Reference

UTCTimeOpts

• offsets <Object> Optional offset values when returning a JavaScript Date object using UTC timezone.
  • hour <number> Optional offset to adjust the hour.
  • minute <number> Optional offset to adjust the minute.
  • second <number> Optional offset to adjust the second.
  • millisecond <number> Optional offset to adjust the millisecond.
• startDatetime <string|number|Date> Optional starting datetime. Defaults to today's datetime if it is not provided.

utcTime([UTCTimeOps])

• UTCTimeOpts <UTCTimeOpts> Optional configuration when returning a JavaScript Date object using UTC timezone.
• returns: <Promise<string>> Promise which resolves with a JavaScript Date object using UTC timezone.

utcTimeSync([UTCTimeOpts])

This methods works the same as utcTime([UTCTimeOpts]) except that this is the synchronous version.

License

MIT License © Rong Sen Ng