Методы Instant

Instant представляет собой момент времени в UTC с точностью до наносекунд, независимый от часовых поясов и календарных систем. Модель ориентирована на абсолютную временную шкалу и используется как базовый строительный блок для операций сравнения, хранения и арифметики времени.

Создание Instant

Instant.now()

Возвращает текущий момент времени в UTC.

import { Instant } from 'js-joda';

const now = Instant.now();

Особенности:

  • значение вычисляется на основе системных часов
  • результат фиксируется в момент вызова
  • используется для меток времени, логирования, измерений длительности

Instant.ofEpochSecond(second, nanoAdjustment?)

Создание Instant на основе секунд Unix epoch.

const i1 = Instant.ofEpochSecond(0);
const i2 = Instant.ofEpochSecond(1609459200, 500000000);

Параметры:

  • second — количество секунд с 1970-01-01T00:00:00Z
  • nanoAdjustment — дополнительная корректировка в наносекундах

Особенности:

  • отрицательные значения допустимы (даты до эпохи Unix)
  • наносекунды нормализуются в диапазон 0–999,999,999

Instant.ofEpochMilli(epochMilli)

Создание момента времени из миллисекунд Unix epoch.

const instant = Instant.ofEpochMilli(1609459200000);

Особенности:

  • точность до миллисекунд
  • наносекунды автоматически устанавливаются в 0
  • применяется при работе с Date.now()

Instant.parse(text)

Парсинг строки в формате ISO-8601.

const instant = Instant.parse('2020-01-01T00:00:00Z');

Поддерживаемые форматы:

  • YYYY-MM-DDTHH:mm:ssZ
  • YYYY-MM-DDTHH:mm:ss.SSSZ
  • расширенные наносекундные представления

Особенности:

  • обязательное наличие временной зоны (Z)
  • отсутствие зоны приводит к ошибке парсинга

Методы получения значений времени

toEpochMilli()

Возвращает количество миллисекунд с Unix epoch.

const millis = Instant.now().toEpochMilli();

Применение:

  • интеграция с Date
  • хранение в базах данных
  • сериализация

getEpochSecond()

Возвращает количество секунд с Unix epoch.

const seconds = Instant.now().getEpochSecond();

Особенности:

  • не включает наносекундную часть
  • используется в низкоуровневых протоколах времени

getNano()

Возвращает наносекундную часть секунды.

const nano = Instant.now().getNano();

Диапазон:

  • от 0 до 999_999_999

Арифметика времени

Instant является неизменяемым объектом. Любая операция возвращает новый экземпляр.

Добавление времени

plusSeconds(seconds)

const future = Instant.now().plusSeconds(60);

plusMillis(millis)

const future = Instant.now().plusMillis(500);

plusNanos(nanos)

const future = Instant.now().plusNanos(1_000_000);

Вычитание времени

minusSeconds(seconds)

const past = Instant.now().minusSeconds(60);

minusMillis(millis)

const past = Instant.now().minusMillis(500);

minusNanos(nanos)

const past = Instant.now().minusNanos(1_000_000);

Нормализация переполнений

При арифметике выполняется автоматическая нормализация:

  • наносекунды переносятся в секунды
  • отрицательные значения корректируются

Сравнение Instant

isBefore(other)

const a = Instant.now();
const b = a.plusSeconds(10);

a.isBefore(b); // true

isAfter(other)

b.isAfter(a); // true

compareTo(other)

Возвращает:

  • -1 если меньше
  • 0 если равны
  • 1 если больше
a.compareTo(b); // -1

equals(other)

Проверка полного равенства, включая наносекунды.

a.equals(b); // false

Особенность:

  • различие даже в 1 наносекунду делает объекты неравными

Преобразования и взаимодействие

Использование с Date

const instant = Instant.now();
const date = new Date(instant.toEpochMilli());
const instant2 = Instant.ofEpochMilli(Date.now());

Ограничение:

  • Date не поддерживает наносекунды
  • происходит потеря точности

Работа с временными диапазонами

Instant часто используется как граница интервалов.

const start = Instant.parse('2024-01-01T00:00:00Z');
const end = Instant.parse('2024-01-02T00:00:00Z');

const now = Instant.now();

const isInRange = now.isAfter(start) && now.isBefore(end);

Сериализация и форматирование

Instant не хранит формат отображения, но может быть преобразован в ISO-строку через внешние классы (например, DateTimeFormatter и ZonedDateTime в js-joda).

Типичный путь:

import { ZonedDateTime, ZoneOffset } from 'js-joda';

const instant = Instant.now();
const zdt = instant.atZone(ZoneOffset.UTC);
const text = zdt.toString();

Особенности точности

Модель Instant включает:

  • секунды (64-bit диапазон)
  • наносекунды (0–999,999,999)

Следствия:

  • высокая точность временных вычислений
  • отсутствие зависимости от локальной системы времени
  • стабильность при сериализации

Граничные значения

Поддерживаются экстремальные диапазоны:

  • минимальное значение: около года -1000000000
  • максимальное значение: около года +1000000000

Поведение:

  • при выходе за пределы выбрасывается исключение
  • арифметика проверяется на переполнение

Иммутабельность

Все методы Instant возвращают новый объект.

const t1 = Instant.now();
const t2 = t1.plusSeconds(10);

t1 === t2; // false

Следствия:

  • безопасное использование в многопоточных сценариях
  • отсутствие побочных эффектов
  • предсказуемость операций

Типовые паттерны использования

Таймстемпы событий

const eventTime = Instant.now();

Замеры длительности

const start = Instant.now();

// операция

const end = Instant.now();
const durationMillis = end.toEpochMilli() - start.toEpochMilli();

Сравнение событий

if (eventA.isBefore(eventB)) {
  // событие A произошло раньше
}

Хранение в базе данных

const payload = {
  createdAt: Instant.now().toString()
};

Внутренние принципы представления

Instant опирается на:

  • линейную шкалу времени
  • Unix epoch как нулевую точку
  • разбиение на секунды и наносекунды

Такое представление обеспечивает:

  • независимость от календарей
  • отсутствие DST-аномалий
  • устойчивость к локальным настройкам системы
Оглавление