ts-time/OffsetDateTime

import OffsetDateTime from "ts-time/OffsetDateTime";

Hierarchy#

• class OffsetDateTime

Description#

Comprises a specific instant bound to a specific time zone offset. In other words, this is a tuple of (Instant, ZoneOffset). Unambiguously identifies a LocalDateTime.

Construct#

OffsetDateTime has a very limited number of usage scenarios, so it has a limited number of ways to be constructed to avoid its misuse. Always consider using other data structures (ZonedDateTime, LocalDateTime, Instant) before OffsetDateTime.

Typically you don't construct OffsetDateTime directly, but create it from other data structures:

OffsetDateTime.ofInstant(instant, offset);   // From Instant in a given ZoneOffset
instant.atOffset(offset);                    // Equivalent
OffsetDateTime.ofDateTime(dateTime, offset); // From LocalDateTime in a given ZoneOffset
dateTime.atOffset(offset);                   // Equivalent
zonedDateTime.offsetDateTime;                // From ZonedDateTime

Please notice that:

• Conversion from Instant may be counter-intuitive, as string presentation of the date/time may change:

  const offset  = ZoneOffset.ofComponents(-2);
  const instant = Instant.parse("2022-06-14T00:00:00.000Z");
  console.log(instant.atOffset(offset));           // "2022-06-13T22:00:00.000-02:00"

  It happens, because OffsetDateTime preserves its instant component in this case, not dateTime:

  console.log(instant.atOffset(offset).instant);   // "2022-06-14T00:00:00.000Z"
  console.log(instant.atOffset(offset).dateTime);  // "2022-06-13T22:00:00.000"

• Conversion from LocalDateTime, on the contrary, preserves dateTime component:

  const dateTime = LocalDateTime.parse("2022-06-14T00:00:00.000");
  console.log(dateTime.atOffset(offset));          // "2022-06-14T00:00:00.000-02:00"
  console.log(dateTime.atOffset(offset).dateTime); // "2022-06-14T00:00:00.000"
  console.log(dateTime.atOffset(offset).instant);  // "2022-06-14T02:00:00.000Z"

• Conversion from ZonedDateTime may result in a partial data loss (if the time zone has dynamic offset).

Parse#

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

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

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

Inspect#

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

const offsetDateTime = OffsetDateTime.parse("2022-02-15T18:30:15.225-02:00");
const year           = offsetDateTime.year;            // 2022
const month          = offsetDateTime.month;           // FEBRUARY
const monthValue     = offsetDateTime.month.value;     // 2
const dayOfMonth     = offsetDateTime.dayOfMonth;      // 15
const dayOfWeek      = offsetDateTime.dayOfWeek;       // TUESDAY
const dayOfWeekValue = offsetDateTime.dayOfWeek.value; // 2
const hour           = offsetDateTime.hour;            // 18
const minute         = offsetDateTime.minute;          // 30
const second         = offsetDateTime.second;          // 15
const ms             = offsetDateTime.ms;              // 225
const offset         = offsetDateTime.offset;          // Instance of ZoneOffset
const offsetHours    = offsetDateTime.offset.hours;    // -2
const offsetMinutes  = offsetDateTime.offset.minutes;  // 0
const offsetSeconds  = offsetDateTime.offset.seconds;  // 0

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

Compare#

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

const d1 = OffsetDateTime.parse("2022-02-15T18:30:15.225-02:00");
const d2 = OffsetDateTime.parse("2022-02-15T18:30:15.226-02:00");
d1.equals(d2);    // false
d1.compareTo(d2); // -1

The objects are first compared by instant, and then by offset.

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

const d1: OffsetDateTime = null;
const d2 = OffsetDateTime.parse("2022-02-15T18:30:15.226-02:00");
OffsetDateTime.equal(d1, d2);   // false
OffsetDateTime.compare(d1, d2); // -1

As opposed to the majority of objects in ts-time, OffsetDateTime doesn't have isBefore and isAfter methods. You must explicitly specify which component you want to compare: instant or dateTime.

const d1 = OffsetDateTime.parse("2022-02-15T18:30:15.225-05:00");
const d2 = OffsetDateTime.parse("2022-02-15T20:30:15.226+01:00");
d1.instant.isBefore(d2.instant);   // false
d1.dateTime.isBefore(d2.dateTime); // true

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 offsetDateTime = OffsetDateTime.parse("2022-02-15T18:30:15.225-02:00");
const d1 = offsetDateTime.plusPeriod(DAY_PERIOD);                // 18:30:15.225 on 16th of February, 2022, UTC-2
const d2 = offsetDateTime.plusPeriod(Period.ofDays(2));          // 18:30:15.225 on 17th of February, 2022, UTC-2
const d3 = offsetDateTime.minusPeriod(MONTH_PERIOD);             // 18:30:15.225 on 15th of January, 2022, UTC-2

The algorithm respects dateTime to align periods, not instant. In the following example, offsetDateTime is the 1st of March in UTC+2, but still 28th of February in UTC. When adding a month, the library considers offsetDateTime to be the 1st of March, so it adds 31 days, not 28:

const offsetDateTime = OffsetDateTime.parse("2022-03-01T00:00:00.000+02:00");
const d1 = offsetDateTime.plusPeriod(MONTH_PERIOD);              // Midnight on 1st of April, 2022, UTC+2

If you expect a month to be added in UTC, convert the instant explicitly to UTC first:

const d2 = offsetDateTime.instant.atOffset(UTC).plusPeriod(MONTH_PERIOD); // 22:00 on 28th of March, 2022, UTC

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

const offsetDateTime = OffsetDateTime.parse("2022-02-15T18:30:15.225-02:00");
const d1 = offsetDateTime.plusDuration(MINUTE_DURATION);         // 18:31:15.225 on 15th of February, 2022, UTC-2
const d2 = offsetDateTime.plusDuration(Duration.ofHours(10));    // 04:30:15.225 on 16th of February, 2022, UTC-2
const d3 = offsetDateTime.minusDuration(Duration.ofSeconds(30)); // 18:29:45.225 on 15th of February, 2022, UTC-2

For difference between Period and Duration, see their documentation. For OffsetDateTime, 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 offsetDateTime = OffsetDateTime.parse("2022-02-15T18:30:15.225-02:00");
const d1 = offsetDateTime.withYear(2025);                        // 18:30:15.225 on 15th of February, 2025, UTC-2
const d2 = offsetDateTime.withMonth(APRIL);                      // 18:30:15.225 on 15th of April, 2022, UTC-2
const d3 = offsetDateTime.withDayOfMonth(10);                    // 18:30:15.225 on 10th of February, 2022, UTC-2
const d4 = offsetDateTime.withDayOfWeek(SUNDAY);                 // 18:30:15.225 on 20th of February, 2022, Sunday, UTC-2
const d5 = offsetDateTime.withHour(20);                          // 20:30:15.225 on 15th of February, 2022, UTC-2
const d6 = offsetDateTime.withMinute(20);                        // 18:20:15.225 on 15th of February, 2022, UTC-2
const d7 = offsetDateTime.withSecond(20);                        // 18:30:20.225 on 15th of February, 2022, UTC-2
const d8 = offsetDateTime.withMs(20);                            // 18:30:15.020 on 15th of February, 2022, UTC-2

For manipulating offset component, see Convert.

The library doesn't yet support OffsetDateTime truncating. Truncate its dateTime component instead.

Another sophisticated feature for OffsetDateTime manipulation: withDayOfYear.

Convert#

You can convert OffsetDateTime to other kinds of objects via its properties:

const offsetDateTime = OffsetDateTime.parse("2022-02-15T18:30:15.225-02:00");
offsetDateTime.instant;                   // To Instant: 2022-02-15T20:30:15.225Z
offsetDateTime.date;                      // To LocalDate: 2022-02-15
offsetDateTime.time;                      // To LocalTime: 18:30:15.225
offsetDateTime.dateTime;                  // To LocalDateTime: 2022-02-15T18:30:15.225
offsetDateTime.instant.atOffset(offset);  // To OffsetDateTime with another ZoneOffset, preserving instant component: 2022-02-16T00:30:15.225+04:00
offsetDateTime.dateTime.atOffset(offset); // To OffsetDateTime with another ZoneOffset, preserving dateTime component: 2022-02-15T18:30:15.225+04:00
offsetDateTime.instant.atZone(zone);      // To ZonedDateTime in a given ZoneId, preserving instant component: 2022-02-15T20:30:15.225Z
offsetDateTime.dateTime.atZone(zone);     // To ZonedDateTime in a given ZoneId, preserving dateTime component: 2022-02-15T18:30:15.225Z

Please notice that all conversions result in a partial data loss (date, time, original offset).

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

const offsetDateTime = OffsetDateTime.parse("2022-02-15T18:30:15.225-02:00");
offsetDateTime.native;                    // Date representing 20: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 offsetDateTime = OffsetDateTime.parse("2022-02-15T18:30:15.225-02:00");
offsetDateTime.toString(); // "2022-02-15T18:30:15.225-02:00"

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 OffsetDateTimeFormatter in order to format arbitrary OffsetDateTime instances:

const formatter = OffsetDateTimeFormatter.ofPattern("dd.MMM''yy, hh:mm a ('UTC'x)");
const offsetDateTime = OffsetDateTime.parse("2022-02-15T18:30:15.225-02:00");
formatter.format(offsetDateTime); // "15.Feb'22, 06:30 PM (UTC-02)"

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

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

Fields#

dateTime#

instant#

offset#

date#

time#

native#

epochMs#

era#

year#

yearOfEra#

weekBasedYear#

month#

weekOfWeekBasedYear#

dayOfYear#

dayOfWeekBasedYear#

dayOfMonth#

dayOfWeek#

epochDay#

quarterOfYear#

isLeapYear#

lengthOfYear#

hour#

minute#

second#

ms#

Methods#

compareTo#

equals#

plusDuration#

plusPeriod#

minusDuration#

minusPeriod#

withYear#

withMonth#

withDayOfMonth#

withDayOfWeek#

withDayOfYear#

withHour#

withMinute#

withSecond#

withMs#

toString#

Static methods#

ofInstant#

ofDateTime#

parse#

compare#

equal#