ts-time/Instant

import Instant, {EPOCH} from "ts-time/Instant";

Hierarchy#

• class Instant

Description#

Represents an instant of time. Lacking time zone and offset information, it doesn't indicate any particular date/time. In order to obtain a particular date/time, you must call atZone or atOffset method. Instant object is determined by epochMs - number of milliseconds since ECMAScript epoch (1st of JANUARY 1970 UTC).

Construct#

Primary Instant constructor accepts number of milliseconds since epoch as an argument. For example, the following Instant instance represents 18 hours, 30 minutes, 15 seconds, 225 milliseconds on 15th of February, 2022 (UTC):

const msSinceEpoch: number = Date.UTC(2022, 1, 15, 18, 30, 15, 225);
Instant.ofEpochMs(msSinceEpoch);

Instant is the only class in ts-time library that allows you to obtain current moment of time:

Instant.now();

Other classes don't have such a method. For example, in order to get the current instance of ZonedDateTime, you must get the current Instant and then convert it to ZonedDateTime:

Instant.now().atZone(UTC);              // Current ZonedDateTime in UTC
Instant.now().atZone(LOCAL_ZONE_ID);    // Current ZonedDateTime in the local time zone
Instant.now().atZone(zone);             // Current ZonedDateTime in a given ZoneId/ZoneOffset

It makes ts-time API more robust. It leaves less room for a mistake.

You can convert instances of other ts-time classes to Instant via their properties and methods:

zonedDateTime.instant;                  // From ZonedDateTime
offsetDateTime.instant;                 // From OffsetDateTime
localDateTime.atZone(zone).instant;     // From LocalDateTime in a given ZoneId
localDateTime.atOffset(offset).instant; // From LocalDateTime in a given ZoneOffset

Please notice that conversion from ZonedDateTime and OffsetDateTime results in a partial data loss (original time zone/offset).

A common way to convert a native JavaScript Date object to a ts-time object is to call fromNative* static method:

Instant.fromNative(date);               // Instant from a given Date

Parse#

A common way to parse an ISO 8601 compliant string in ts-time is to call parse static method. For example, the following Instant instance represents 18 hours, 30 minutes, 15 seconds, 225 milliseconds on 15th of February, 2022 in New York:

Instant.parse("2022-02-15T18:30:15.225-05:00[America/New_York]");

The library doesn't yet support parsing non-compliant strings.

Inspect#

Since Instant doesn't represent a particular date and time, the only thing you can inspect is epochMs. For inspection of other date/time properties, you must convert it to ZonedDateTime or OffsetDateTime first:

const instant       = Instant.parse("2022-02-15T18:30:15.225Z");
const zonedDateTime = instant.atZone(UTC);
const hour          = zonedDateTime.hour;            // 18
const minute        = zonedDateTime.minute;          // 30

Compare#

A common way to compare objects in ts-time is to call equals, isBefore, isAfter, compareTo methods:

const d1 = Instant.parse("2022-02-15T18:30:15.225Z");
const d2 = Instant.parse("2022-02-15T18:30:15.226Z");
d1.equals(d2);    // false
d1.isBefore(d2);  // true
d1.isAfter(d2);   // false
d1.compareTo(d2); // -1

For nullable objects, use static methods instead. Null and undefined are considered less than anything, except each other:

const d1: Instant = null;
const d2 = Instant.parse("2022-02-15T18:30:15.226Z");
Instant.equal(d1, d2);     // false
Instant.isBefore(d1, d2);  // true
Instant.isAfter(d1, d2);   // false
Instant.compare(d1, d2);   // -1

Manipulate#

Every object in ts-time is immutable. Therefore every manipulation returns a new object.

To add/subtract a Duration, call plus/minus method:

const instant = Instant.parse("2022-02-15T18:30:15.225Z");
const d1 = instant.plus(MINUTE_DURATION);         // 2022-02-15T18:31:15.225Z
const d2 = instant.plus(Duration.ofHours(10));    // 2022-02-16T04:30:15.225Z
const d3 = instant.minus(Duration.ofSeconds(30)); // 2022-02-15T18:29:45.225Z

You can't add/subtract a Period, because sometimes the respective date/time differs in different time zones so much that it is impossible to determine the exact time duration to add/subtract. If you know the exact time zone/offset to work with, call atZone/atOffset method and then you'll be able to add/subtract a Period to/from the returned ZonedDateTime/OffsetDateTime. For difference between Period and Duration, see their documentation.

Convert#

You can convert Instant to other kinds of objects via its methods:

const instant = Instant.parse("2022-02-15T18:30:15.225Z");
const zone    = ZoneId.of("Europe/Berlin");
const offset  = ZoneOffset.ofComponents(2);
instant.atZone(zone);              // To ZonedDateTime  in a given time zone: 2022-02-15T19:30:15.225+01:00[Europe/Berlin]
instant.atOffset(offset);          // To OffsetDateTime in a given offset:    2022-02-15T20:30:15.225+02:00
instant.atZone(zone).dateTime;     // To LocalDateTime  in a given time zone: 2022-02-15T19:30:15.225
instant.atOffset(offset).dateTime; // To LocalDateTime  in a given offset:    2022-02-15T20:30:15.225

Please notice that conversion to LocalDateTime results in a partial data loss (instant becomes ambiguous due to lack of time zone/offset attachment).

You can as well convert Instant to a native JavaScript Date:

const instant = Instant.parse("2022-02-15T18:30:15.225Z");
instant.native;                    // Date representing 18:30:15.225 on 15th of February, 2022 (UTC)

Please notice that native Date is always stored in UTC or local time zone, so you can see a different date/time when printing it as a string. It will be the same instant, just a different time zone.

For backward conversion, see Construct.

Format#

Every class in ts-time has ISO 8601 compliant toString method:

const instant = Instant.parse("2022-02-15T18:30:15.225-05:00[America/New_York]");
instant.toString(); // "2022-02-15T23:30:15.225Z"

Please notice that the instant is always formatted in UTC, because Instant doesn't have a time zone.

For more sophisticated string formatting, you must first convert the Instant to ZonedDateTime or OffsetDateTime and then use their formatting functionality.

Fields#

epochMs#

native#

Methods#

atOffset#

atZone#

compareTo#

equals#

isBefore#

isAfter#

plus#

minus#

until#

toString#

Static methods#

now#

ofEpochMs#

fromNative#

parse#

compare#

equal#

isBefore#

isAfter#

EPOCH: Instant

Instant with epochMs = 0, i.e. representing ECMAScript epoch (1st of JANUARY 1970 UTC).