tai-date v3.0.0

tai-date

A TaiDate object represents an instant in International Atomic Time (TAI), in the same way that a conventional JavaScript Date object represents an instant in Unix time.

To convert TaiDates to and from Dates, use the t-a-i, which provides methods for converting TAI milliseconds to Unix milliseconds.

Installation

npm install tai-date

Usage

const tai = require('t-a-i')
const TaiDate = require('tai-date')

const taiConverter = tai.TaiConverter(tai.MODELS.STALL)

const date = new Date(2016, 9, 30, 14, 45, 49)
// Sun Oct 30 2016 14:45:49 GMT+0000 (GMT Standard Time)

const taiDate = new TaiDate(taiConverter.unixToAtomic(date.getTime()))
// Sun Oct 30 2016 14:46:25 TAI

console.log(taiDate.getTime() - date.getTime())
// 36000; TAI was 36 seconds ahead of Unix at this time

Why can't I just use a Date for this purpose?

A Date object specifically represents an instant in Unix time. Its method names and method behaviours reflect this. For example

• the names of the methods Date.UTC, Date.prototype.getUTCFullYear, Date.prototype.getUTCMonth and so on
• the behaviour of e.g. Date.now() and Date.prototype.getTime(), which are documented as returning Unix milliseconds, not TAI milliseconds
• locale conversion behaviour of Date.prototype.getHours, Date.prototype.getMinutes and so on
• stringification methods such as Date.prototype.toISOString which return e.g. "2011-10-05T14:48:00.000Z" - note the trailing "Z" indicating Zulu time i.e. UTC

API

new TaiDate()

Throws an exception. TaiDate has to be told what instant in TAI it represents, it isn't able to convert Unix time to TAI by itself.

new TaiDate(atomic)

atomic is a number of TAI milliseconds. Constructs a TaiDate object representing this instant in time.

new TaiDate(1000000000000)
// Sun, 09 Sep 2001 01:46:40 TAI

new TaiDate(string)

Throws an exception. TaiDate has no string-parsing capability.

new TaiDate(year, month[, day[, hours[, minutes[, seconds, milliseconds]]]])

Construct a TaiDate object representing the instant described by year, month and so on in the TAI calendar. day defaults to 1 if omitted, everything else defaults to 0.

new TaiDate(2016, 9, 30, 14, 46, 25)
// Sun Oct 30 2016 14:46:25 TAI

TaiDate.TAI(year, month[, day[, hours[, minutes[, seconds, milliseconds]]]])

Take the year, month etc. as representing a TAI calendar date and time, and convert it to TAI milliseconds. day defaults to 1 if omitted, everything else defaults to 0. Note that this method has exactly identical behaviour to Date.UTC.

TaiDate.TAI(2012, 11, 12, 23, 59, 59, 999)
// 1355356799999

TaiDate.prototype.getTime()

Convert a TaiDate object to TAI milliseconds.

new TaiDate(2012, 11, 12, 23, 59, 59, 999).getTime()
// 1355356799999

TaiDate.prototype.getTAIDate()

TaiDate.prototype.getTAIDay()

TaiDate.prototype.getTAIFullYear()

TaiDate.prototype.getTAIHours()

TaiDate.prototype.getTAIMilliseconds()

TaiDate.prototype.getTAIMonth()

TaiDate.prototype.getTAISeconds()

The above are all getter methods, analogous to the equivalent getters on Date but always returning TAI figures.

TaiDate.prototype.toString()

Return a string representing this instant in TAI.

new TaiDate(2006, 6, 3, 21, 44, 38).toString()
// "Mon 03 Jul 2006 21:44:38 TAI"