Работа с API

API библиотеки строится вокруг нескольких ключевых сущностей: DateTime, Duration, Interval и глобальных настроек через Settings. Каждая из них представляет строго ограниченную область ответственности, что формирует предсказуемую модель работы с датой и временем.

Основной принцип — неизменяемость объектов. Любая операция возвращает новый экземпляр, не модифицируя исходный. Это исключает скрытые побочные эффекты и упрощает построение цепочек преобразований.

DateTime как центральная сущность API

DateTime — основной объект, через который выполняется большинство операций.

Создание экземпляров происходит через статические методы:

  • DateTime.now() — текущее локальное время
  • DateTime.local() — локальная дата с явными компонентами
  • DateTime.utc() — создание в UTC
  • DateTime.fromISO() — разбор ISO-строки
  • DateTime.fromJSDate() — конвертация из Date

Каждый метод возвращает полноценный объект DateTime, содержащий:

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

Работа с таймзонами через API

Таймзона является частью состояния DateTime и может быть изменена через метод:

  • setZone(zone: string, { keepLocalTime?: boolean })

При этом создаётся новый объект с пересчитанным временем.

Пример логики API:

  • смена зоны без сохранения локального времени приводит к пересчёту абсолютного момента
  • с keepLocalTime: true сохраняются компоненты времени, изменяется только интерпретация зоны

Также используется:

  • toUTC() — перевод в UTC
  • toLocal() — перевод в локальную зону выполнения

API опирается на IANA time zone database, что позволяет работать с зонами вида Europe/Moscow, Asia/Almaty.

Парсинг данных: входные точки API

Библиотека поддерживает несколько форматов входных данных.

ISO-формат

Наиболее строгий и предпочтительный:

DateTime.fromISO("2026-05-23T10:30:00")

Поддерживается полный спектр расширений ISO 8601: смещения, миллисекунды, зоны.

Unix timestamp

DateTime.fromMillis(1716450000000)
DateTime.fromSeconds(1716450000)

API различает миллисекунды и секунды, что важно при интеграции с внешними сервисами.

JavaScript Date

DateTime.fromJSDate(new Date())

Конвертация происходит без потери точности, но с привязкой к системной зоне.

Строки с пользовательским форматом

DateTime.fromFormat("23-05-2026", "dd-MM-yyyy")

Парсинг зависит от токенизированного формата, где каждый элемент строки сопоставляется с шаблоном.

Форматирование данных через API

Форматирование реализуется через метод:

  • toFormat(formatString)

Пример работы API:

  • yyyy — год
  • MM — месяц
  • dd — день
  • HH:mm — время
dt.toFormat("dd.MM.yyyy HH:mm")

Также поддерживаются специализированные форматы:

  • toISO() — ISO 8601 строка
  • toRFC2822() — формат email/HTTP
  • toHTTP() — HTTP-date формат

Преобразование в стандартные типы JavaScript

toJSDate

dt.toJSDate()

Возвращает стандартный Date, сохраняя момент времени.

toMillis

dt.toMillis()

Возвращает Unix-время в миллисекундах.

toSeconds

dt.toSeconds()

Используется в API, связанных с серверными таймстемпами и протоколами.

Мутации через API и принцип иммутабельности

Любые методы изменения возвращают новый объект:

  • set({ year, month, day })
  • plus({ days, hours })
  • minus({ weeks })

Пример:

const upd ated = dt.plus({ days: 5 })

Исходный объект остаётся неизменным.

Такой подход позволяет безопасно использовать цепочки:

dt.plus({ days: 1 }).se t({ hour: 10 }).toISO()

Duration: работа с временными интервалами

Duration представляет абстрактную длительность.

Создание:

Duration.fromObject({ hours: 2, minutes: 30 })

API поддерживает:

  • нормализацию единиц
  • преобразование в разные шкалы
  • арифметику с DateTime

Пример:

dt.plus(Duration.fromObject({ days: 1 }))

Форматы вывода:

  • toISO() — ISO 8601 duration
  • toHuman() — человекочитаемое представление
  • toObject() — объектное представление

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

Interval представляет промежуток между двумя DateTime.

Создание:

Interval.fromDateTimes(start, end)

Основные методы API:

  • contains(dateTime) — проверка принадлежности
  • overlaps(otherInterval) — пересечение интервалов
  • length() — длительность

Интервал всегда строго нормализуется по времени начала и конца.

Глобальные настройки API через Settings

Settings управляет поведением библиотеки:

  • defaultZone — зона по умолчанию
  • defaultLocale — локаль
  • now() — переопределение текущего времени (тестирование)

Пример:

Settings.defaultLocale = "ru"
Settings.defaultZone = "Asia/Almaty"

Эти параметры влияют на все создаваемые экземпляры, если явно не указано иное.

Локализация через API

Локаль влияет на:

  • формат вывода дат
  • названия месяцев
  • порядок компонентов даты
dt.setLocale("ru").toLocaleString()

Метод toLocaleString использует внутренние пресеты:

  • DATE_SHORT
  • DATE_MED
  • DATETIME_FULL

Сериализация и восстановление объектов

Для передачи данных через API используется:

  • toJSON() — ISO строка
  • toObject() — структурированный формат

Пример:

JSON.stringify(dt)

При десериализации необходимо использовать fromISO или аналогичный метод.

Взаимодействие с внешними API и HTTP

Работа с веб-протоколами требует строгих форматов:

  • HTTP-date через toHTTP()
  • заголовки Last-Modified, Date

Пример использования:

const headerDate = DateTime.now().toHTTP()

ISO формат применяется в REST API:

dt.toISO()

Числовая модель времени внутри API

Внутренне время представлено как:

  • Unix epoch (мс)
  • смещение таймзоны
  • календарные компоненты

API обеспечивает синхронизацию этих представлений при каждой операции.

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

Композиция API-операций

Типичный сценарий работы строится через цепочки:

DateTime.now()
  .setZone("Europe/Moscow")
  .plus({ days: 3 })
  .set({ hour: 12 })
  .toISO()

Каждый шаг создаёт новый объект, формируя предсказуемый конвейер преобразований данных.

Работа с ошибками API

Ошибочные состояния не выбрасывают исключения напрямую в большинстве случаев.

Вместо этого объект DateTime содержит флаг:

  • isValid

и причину:

  • invalidReason

Это позволяет безопасно обрабатывать результат без try/catch в простых сценариях.

Интероперабельность с JavaScript стандартами

API проектировался с учётом встроенных механизмов:

  • Intl.DateTimeFormat
  • Date
  • Number (timestamps)

Это позволяет интегрировать библиотеку в существующие приложения без адаптеров, используя минимальные преобразования типов.

Оглавление