Class PreciseDate (4.0.0)

Date object with nanosecond precision. Supports all standard Date arguments in addition to several custom types as noted below.

external:Date

Inheritance

Date > PreciseDate

Package

@google-cloud/precise-date

Examples

With a RFC 3339 formatted string. const date = new PreciseDate('2019-02-08T10:34:29.481145231Z');

With a nanosecond timestamp string. const date = new PreciseDate('1549622069481320032');

With a BigInt (requires Node >= v10.7) const date = new PreciseDate(1549622069481320032n);

With a tuple containing seconds and nanoseconds. const date = new PreciseDate([1549622069, 481320032]);

With an object containing seconds and nanos const date = new PreciseDate({seconds: 1549622069, nanos: 481320032});

Specifiying date fields const date = new PreciseDate(2018, 5, 14, 41, 11, 34, 123, 874, 321);

Constructors

(constructor)(time)

constructor(time?: number | Date);

Constructs a new instance of the PreciseDate class

Parameter
NameDescription
time number | Date

(constructor)(preciseTime)

constructor(preciseTime: string | bigint | DateTuple | ProtobufDate);

Constructs a new instance of the PreciseDate class

Parameter
NameDescription
preciseTime string | bigint | DateTuple | ProtobufDate

(constructor)(year, month, date, hours, minutes, seconds, milliseconds, microseconds, nanoseconds)

constructor(year: number, month?: number, date?: number, hours?: number, minutes?: number, seconds?: number, milliseconds?: number, microseconds?: number, nanoseconds?: number);

Constructs a new instance of the PreciseDate class

Parameters
NameDescription
year number
month number
date number
hours number
minutes number
seconds number
milliseconds number
microseconds number
nanoseconds number

Methods

fullUTC(args)

static fullUTC(...args: number[]): bigint;

Accepts the same number parameters as the PreciseDate constructor, but treats them as UTC. It returns a string that represents the number of nanoseconds since January 1, 1970, 00:00:00 UTC.

**NOTE:** Because this method returns a BigInt it requires Node >= v10.7.

Parameter
NameDescription
args number[]
Returns
TypeDescription
bigint

{bigint}

Example

const time = PreciseDate.fullUTC(2019, 1, 8, 10, 34, 29, 481, 145, 231); console.log(time); // expected output: 1549622069481145231n

fullUTCString(args)

static fullUTCString(...args: number[]): string;

Accepts the same number parameters as the PreciseDate constructor, but treats them as UTC. It returns a string that represents the number of nanoseconds since January 1, 1970, 00:00:00 UTC.

Parameter
NameDescription
args number[]
Returns
TypeDescription
string

{string}

Example

const time = PreciseDate.fullUTCString(2019, 1, 8, 10, 34, 29, 481, 145, 231); console.log(time); // expected output: '1549622069481145231'

getFullTime()

getFullTime(): bigint;

Returns the specified date represented in nanoseconds according to universal time.

**NOTE:** Because this method returns a BigInt it requires Node >= v10.7. Use to get the time as a string.

Returns
TypeDescription
bigint

{bigint}

Example

const date = new PreciseDate('2019-02-08T10:34:29.481145231Z');

console.log(date.getFullTime()); // expected output: 1549622069481145231n

getFullTimeString()

getFullTimeString(): string;

Returns a string of the specified date represented in nanoseconds according to universal time.

Returns
TypeDescription
string

{string}

Example

const date = new PreciseDate('2019-02-08T10:34:29.481145231Z');

console.log(date.getFullTimeString()); // expected output: "1549622069481145231"

getMicroseconds()

getMicroseconds(): number;

Returns the microseconds in the specified date according to universal time.

Returns
TypeDescription
number

{number}

Example

const date = new PreciseDate('2019-02-08T10:34:29.481145Z');

console.log(date.getMicroseconds()); // expected output: 145

getNanoseconds()

getNanoseconds(): number;

Returns the nanoseconds in the specified date according to universal time.

Returns
TypeDescription
number

{number}

Example

const date = new PreciseDate('2019-02-08T10:34:29.481145231Z');

console.log(date.getNanoseconds()); // expected output: 231

parseFull(time)

static parseFull(time: string | bigint | DateTuple | ProtobufDate): string;

Parses a precise time.

Parameter
NameDescription
time string | bigint | DateTuple | ProtobufDate

The precise time value.

Returns
TypeDescription
string

{string} Returns a string representing the nanoseconds in the specified date according to universal time.

Examples

From a RFC 3339 formatted string. const time = PreciseDate.parseFull('2019-02-08T10:34:29.481145231Z'); console.log(time); // expected output: "1549622069481145231"

From a nanosecond timestamp string. const time = PreciseDate.parseFull('1549622069481145231'); console.log(time); // expected output: "1549622069481145231"

From a BigInt (requires Node >= v10.7) const time = PreciseDate.parseFull(1549622069481145231n); console.log(time); // expected output: "1549622069481145231"

From a tuple. const time = PreciseDate.parseFull([1549622069, 481145231]); console.log(time); // expected output: "1549622069481145231"

From an object. const struct = {seconds: 1549622069, nanos: 481145231}; const time = PreciseDate.parseFull(struct); console.log(time); // expected output: "1549622069481145231"

setFullTime(time)

setFullTime(time: string | number | bigint): string;

Sets the PreciseDate object to the time represented by a number of nanoseconds since January 1, 1970, 00:00:00 UTC.

Parameter
NameDescription
time string | number | bigint

Value representing the number of nanoseconds since January 1, 1970, 00:00:00 UTC.

Returns
TypeDescription
string

{string} Returns a string representing the nanoseconds in the specified date according to universal time (effectively, the value of the argument).

Examples

With a nanosecond string. const date = new PreciseDate(); date.setFullTime('1549622069481145231');

With a BigInt date.setFullTime(1549622069481145231n);

setMicroseconds(micros)

setMicroseconds(micros: number): string;

Sets the microseconds for a specified date according to universal time.

Parameter
NameDescription
micros number
Returns
TypeDescription
string

{string} Returns a string representing the nanoseconds in the specified date according to universal time.

Example

const date = new PreciseDate();

date.setMicroseconds(149);

console.log(date.getMicroseconds()); // expected output: 149

setNanoseconds(nanos)

setNanoseconds(nanos: number): string;

Sets the nanoseconds for a specified date according to universal time.

Parameter
NameDescription
nanos number
Returns
TypeDescription
string

{string} Returns a string representing the nanoseconds in the specified date according to universal time.

Example

const date = new PreciseDate();

date.setNanoseconds(231);

console.log(date.getNanoseconds()); // expected output: 231

setTime(time)

setTime(time: number): number;

Sets the PreciseDate object to the time represented by a number of milliseconds since January 1, 1970, 00:00:00 UTC. Calling this method will reset both the microseconds and nanoseconds to 0.

Parameter
NameDescription
time number

Value representing the number of milliseconds since January 1, 1970, 00:00:00 UTC.

Returns
TypeDescription
number

{string} The number of milliseconds between January 1, 1970, 00:00:00 UTC and the updated date (effectively, the value of the argument).

toISOString()

toISOString(): string;

Returns a string in RFC 3339 format. Unlike the native Date#toISOString, this will return 9 digits to represent sub-second precision.

Returns
TypeDescription
string

{string}

Example

const date = new PreciseDate(1549622069481145231n);

console.log(date.toISOString()); // expected output: "2019-02-08T10:34:29.481145231Z"

toStruct()

toStruct(): DateStruct;

Returns an object representing the specified date according to universal time.

Returns
TypeDescription
DateStruct

{DateStruct}

Example

const date = new PreciseDate('2019-02-08T10:34:29.481145231Z');

console.log(date.toStruct()); // expected output: {seconds: 1549622069, nanos: 481145231}

toTuple()

toTuple(): DateTuple;

Returns a tuple representing the specified date according to universal time.

Returns
TypeDescription
DateTuple

{DateTuple}

Example

const date = new PreciseDate('2019-02-08T10:34:29.481145231Z');

console.log(date.toTuple()); // expected output: [1549622069, 481145231]