ts-time/LocalDateTime

import LocalDateTime from "ts-time/LocalDateTime";

Hierarchy#

• class LocalDateTime

Description#

Comprises a specific date/time, without time zone relation. In other words, this is a tuple of (LocalDate, LocalTime).

Construct#

A common way to construct an object in ts-time is to call its of* static method. For example, the following LocalDateTime instances represent 18 hours, 30 minutes, 15 seconds, 225 milliseconds on 15th of February, 2022:

LocalDateTime.ofComponents(2022, FEBRUARY, 15, 18, 30, 15, 225);
LocalDateTime.ofComponents(2022, 2, 15, 18, 30, 15, 225);

As opposed to Java API, there's no common way to get the current instance of LocalDateTime in ts-time, because ts-time doesn't have a concept of default time zone. Instead, you must get the current Instant and convert it to an object that you need, taking time zone into consideration.

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

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

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

LocalDateTime.fromNativeUtc(date);              // LocalDateTime from a given Date in UTC
LocalDateTime.fromNativeLocal(date);            // LocalDateTime from a given Date in the local time zone
Instant.fromNative(date).atZone(zone).dateTime; // LocalDateTime from a given Date in a given ZoneId/ZoneOffset

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

LocalDateTime.of(date, time);                   // From a pair of LocalDate and LocalTime
date.atTime(time);                              // Equivalent
instant.atZone(zone).dateTime;                  // From Instant in a given ZoneId/ZoneOffset
offsetDateTime.dateTime;                        // From OffsetDateTime in the same ZoneOffset
zonedDateTime.dateTime;                         // From ZonedDateTime in the same ZoneId

Please notice that conversions from OffsetDateTime and ZonedDateTime result in a partial data loss (offset and time zone respectively).

Another sophisticated constructor: ofEpochMsUtc. Also check sophisticated constructors of LocalDate and LocalTime, as LocalDateTime is essentially a pair of them.

Parse#

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

LocalDateTime.parse("2022-02-15T18:30:15.225");

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

Inspect#

In the following example, we inspect various properties of a LocalDateTime object. Please notice the difference in return value types:

const dateTime       = LocalDateTime.ofComponents(2022, FEBRUARY, 15, 18, 30, 15, 225);
const year           = dateTime.year;            // 2022
const month          = dateTime.month;           // FEBRUARY
const monthValue     = dateTime.month.value;     // 2
const dayOfMonth     = dateTime.dayOfMonth;      // 15
const dayOfWeek      = dateTime.dayOfWeek;       // TUESDAY
const dayOfWeekValue = dateTime.dayOfWeek.value; // 2
const hour           = dateTime.hour;            // 18
const minute         = dateTime.minute;          // 30
const second         = dateTime.second;          // 15
const ms             = dateTime.ms;              // 225

Other sophisticated features for LocalDateTime inspection: epochMsUtc, era, yearOfEra, weekBasedYear, weekOfWeekBasedYear, dayOfYear, dayOfWeekBasedYear, epochDay, quarterOfYear, isLeapYear, lengthOfYear.

Compare#

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

const d1 = LocalDateTime.ofComponents(2022, FEBRUARY, 15, 18, 30, 15, 225);
const d2 = LocalDateTime.ofComponents(2022, FEBRUARY, 15, 18, 30, 15, 226);
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: LocalDateTime = null;
const d2 = LocalDateTime.ofComponents(2022, FEBRUARY, 15, 18, 30, 15, 226);
LocalDateTime.equal(d1, d2);     // false
LocalDateTime.isBefore(d1, d2);  // true
LocalDateTime.isAfter(d1, d2);   // false
LocalDateTime.compare(d1, d2);   // -1

Manipulate#

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

To add/subtract a Period, call plusPeriod/minusPeriod method:

const dateTime = LocalDateTime.ofComponents(2022, FEBRUARY, 15, 18, 30, 15, 225);
const d1 = dateTime.plusPeriod(DAY_PERIOD);                // 18:30:15.225 on 16th of February, 2022
const d2 = dateTime.plusPeriod(Period.ofDays(2));          // 18:30:15.225 on 17th of February, 2022
const d3 = dateTime.minusPeriod(MONTH_PERIOD);             // 18:30:15.225 on 15th of January, 2022

To add/subtract a duration, call plusDuration/minusDuration method:

const dateTime = LocalDateTime.ofComponents(2022, FEBRUARY, 15, 18, 30, 15, 225);
const d1 = dateTime.plusDuration(MINUTE_DURATION);         // 18:31:15.225 on 15th of February, 2022
const d2 = dateTime.plusDuration(Duration.ofHours(10));    // 04:30:15.225 on 16th of February, 2022
const d3 = dateTime.minusDuration(Duration.ofSeconds(30)); // 18:29:45.225 on 15th of February, 2022

For difference between Period and Duration, see their documentation. For LocalDateTime, they are interchangeable - apart for the list of supported date/time components.

To change one of the components, preserving all the rest, call with* methods:

const dateTime = LocalDateTime.ofComponents(2022, FEBRUARY, 15, 18, 30, 15, 225);
const d1 = dateTime.withYear(2025);                        // 18:30:15.225 on 15th of February, 2025
const d2 = dateTime.withMonth(APRIL);                      // 18:30:15.225 on 15th of April, 2022
const d3 = dateTime.withDayOfMonth(10);                    // 18:30:15.225 on 10th of February, 2022
const d4 = dateTime.withDayOfWeek(SUNDAY);                 // 18:30:15.225 on 20th of February, 2022, Sunday
const d5 = dateTime.withHour(20);                          // 20:30:15.225 on 15th of February, 2022
const d6 = dateTime.withMinute(20);                        // 18:20:15.225 on 15th of February, 2022
const d7 = dateTime.withSecond(20);                        // 18:30:20.225 on 15th of February, 2022
const d8 = dateTime.withMs(20);                            // 18:30:15.020 on 15th of February, 2022

To truncate all the least-significant components, call truncate* methods:

const dateTime = LocalDateTime.ofComponents(2022, FEBRUARY, 15, 18, 30, 15, 225);
const d1 = dateTime.truncateToYear;                        // Midnight on 1st of January, 2022
const d2 = dateTime.truncateToMonth;                       // Midnight on 1st of February, 2022
const d3 = dateTime.truncateToWeek;                        // Midnight on 14th of February, 2022, Monday
const d4 = dateTime.truncateToDay;                         // Midnight on 15th of February, 2022
const d5 = dateTime.truncateToHour;                        // 18:00:00.000 on 15th of February, 2022
const d6 = dateTime.truncateToMinute;                      // 18:30:00.000 on 15th of February, 2022
const d7 = dateTime.truncateToSecond;                      // 18:30:15.000 on 15th of February, 2022

The library doesn't yet support Sunday as the 1st day of the week. But there's a workaround:

const d8 = dateTime.truncateToDay.minusPeriod(Period.ofDays(dateTime.dayOfWeek.value % 7)); // Midnight on 13th of February, 2022, Sunday

Or a flexible solution, where firstDayOfWeek is 1 for Monday, and 7 for Sunday:

const d8 = dateTime.truncateToDay.minusPeriod(Period.ofDays((dateTime.dayOfWeek.value + 7 - firstDayOfWeek) % 7));

Other sophisticated features for LocalDateTime manipulation: withDayOfYear, truncateToWeekBasedYear.

Convert#

You can convert LocalDateTime to other kinds of objects via its properties and methods:

const dateTime = LocalDateTime.ofComponents(2022, FEBRUARY, 15, 18, 30, 15, 225);
dateTime.date;                 // To LocalDate: 2022-02-15
dateTime.time;                 // To LocalTime: 18:30:15.225
dateTime.atOffset(offset);     // To OffsetDateTime in a given ZoneOffset: 2022-02-15T18:30:15.225+01:00
dateTime.atZone(zone);         // To ZonedDateTime in a given ZoneId: 2022-02-15T18:30:15.225+01:00[Europe/Berlin]
dateTime.atZone(zone).instant; // To Instant in a given ZoneId/ZoneOffset: 2022-02-15T17:30:15.225Z

Please notice that - when converting to Instant - string presentation may change depending on the selected time zone.

In order to convert LocalDateTime from one ZoneId/ZoneOffset to another, you must first convert it to an Instant:

dateTime.atZone(sourceZone).instant.atZone(targetZone).dateTime;

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

const dateTime = LocalDateTime.ofComponents(2022, FEBRUARY, 15, 18, 30, 15, 225);
dateTime.nativeUtc;            // Date representing 18:30:15.225 on 15th of February, 2022 in UTC
dateTime.nativeLocal;          // Date representing 18:30:15.225 on 15th of February, 2022 in the local time zone
dateTime.atZone(zone).native;  // Date representing 18:30:15.225 on 15th of February, 2022 in a given ZoneId/ZoneOffset

For backward conversion, see Construct.

Format#

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

const dateTime = LocalDateTime.ofComponents(2022, FEBRUARY, 15, 18, 30, 15, 225);
dateTime.toString(); // "2022-02-15T18:30:15.225"

For more sophisticated string formatting, add ts-time-format library to your list of dependencies:

npm install --save ts-time-format

Now you can construct an instance of DateTimeFormatter in order to format arbitrary LocalDateTime instances:

const formatter = DateTimeFormatter.ofPattern("dd.MMM''yy, hh:mm a");
const dateTime = LocalDateTime.ofComponents(2022, FEBRUARY, 15, 18, 30, 15, 225);
formatter.format(dateTime); // "15.Feb'22, 06:30 PM"

You can define a custom context object to internationalize the formatted strings:

const context = {monthShortNames: ["Янв", "Фев", "Мар"]};
formatter.format(dateTime, context); // "15.Фев'22, 06:30 PM"

Fields#

date#

time#

nativeLocal#

nativeUtc#

epochMsUtc#

era#

year#

yearOfEra#

weekBasedYear#

month#

weekOfWeekBasedYear#

dayOfYear#

dayOfWeekBasedYear#

dayOfMonth#

dayOfWeek#

epochDay#

quarterOfYear#

isLeapYear#

lengthOfYear#

hour#

minute#

second#

ms#

truncateToYear#

truncateToWeekBasedYear#

truncateToMonth#

truncateToWeek#

truncateToDay#

truncateToHour#

truncateToMinute#

truncateToSecond#

Methods#

compareTo#

equals#

isBefore#

isAfter#

atZone#

atOffset#

plusDuration#

plusPeriod#

minusDuration#

minusPeriod#

withYear#

withMonth#

withDayOfMonth#

withDayOfWeek#

withDayOfYear#

withHour#

withMinute#

withSecond#

withMs#

toString#

Static methods#

of#

ofComponents#

ofEpochMsUtc#

fromNativeLocal#

fromNativeUtc#

parse#

compare#

equal#

isBefore#

isAfter#