Парсинг строковых значений времени

Парсинг строк в js-joda опирается на строго определённые форматы и использование объектов DateTimeFormatter. Библиотека следует модели Java Time API, поэтому большинство правил разбора строк совпадает с ISO-8601 и механизмами java.time.

Основная идея заключается в том, что строковое представление времени преобразуется в объект даты/времени через статические методы parse. Почти каждый класс даты во js-joda поддерживает свой вариант парсинга:

  • LocalDate.parse
  • LocalTime.parse
  • LocalDateTime.parse
  • Instant.parse
  • ZonedDateTime.parse
  • OffsetDateTime.parse

Каждый из методов использует ISO-формат по умолчанию, если не указан иной форматтер.

Парсинг ISO-8601 строк

Наиболее частый сценарий — работа с ISO-8601 строками, которые распознаются без дополнительных настроек.

LocalDate

import { LocalDate } from 'js-joda';

const date = LocalDate.parse('2026-05-24');

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

  • YYYY-MM-DD

LocalTime

import { LocalTime } from 'js-joda';

const time = LocalTime.parse('14:30:15');

Формат:

  • HH:mm:ss
  • допускаются миллисекунды: HH:mm:ss.SSS

LocalDateTime

import { LocalDateTime } from 'js-joda';

const dateTime = LocalDateTime.parse('2026-05-24T14:30:15');

Разделитель T является обязательным для ISO-формата.

Instant и момент времени

Instant предназначен для работы с абсолютным временем в UTC.

import { Instant } from 'js-joda';

const instant = Instant.parse('2026-05-24T10:30:00Z');

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

  • обязательный суффикс Z или смещение
  • отсутствие локальной зоны

ZonedDateTime и OffsetDateTime

OffsetDateTime

import { OffsetDateTime } from 'js-joda';

const odt = OffsetDateTime.parse('2026-05-24T14:30:15+03:00');

Содержит:

  • дату
  • время
  • смещение от UTC

ZonedDateTime

import { ZonedDateTime } from 'js-joda';

const zdt = ZonedDateTime.parse('2026-05-24T14:30:15+03:00[Europe/Moscow]');

Дополнительно включает:

  • идентификатор временной зоны
  • правила перехода на летнее/зимнее время

Использование DateTimeFormatter для кастомных форматов

Когда строка не соответствует ISO-формату, применяется DateTimeFormatter.

import { LocalDate, DateTimeFormatter } from 'js-joda';

const formatter = DateTimeFormatter.ofPattern('dd.MM.yyyy');

const date = LocalDate.parse('24.05.2026', formatter);

Основные символы формата

  • y — год
  • M — месяц
  • d — день
  • H — часы (24h)
  • m — минуты
  • s — секунды

Парсинг локализованных форматов

js-joda поддерживает локализацию через Locale.

import { LocalDate, DateTimeFormatter, Locale } from 'js-joda';

const formatter = DateTimeFormatter
  .ofPattern('d MMMM yyyy')
  .withLocale(Locale.US);

const date = LocalDate.parse('24 May 2026', formatter);

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

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

Строгость и режимы разбора (ResolverStyle)

Парсинг может выполняться в разных режимах строгости:

  • STRICT — строгая проверка корректности даты
  • SMART — допускает некоторые логические исправления
  • LENIENT — максимально гибкий разбор
import { DateTimeFormatter, ResolverStyle } from 'js-joda';

const formatter = DateTimeFormatter
  .ofPattern('dd-MM-yyyy')
  .withResolverStyle(ResolverStyle.STRICT);

Пример влияния режима

  • STRICT: 31.02.2026 → ошибка
  • SMART: может интерпретировать как 28.02 или 01.03 в зависимости от правил
  • LENIENT: переносит лишние дни на следующий месяц

Обработка ошибок парсинга

Ошибки возникают при несоответствии формата или некорректных данных:

import { LocalDate } from 'js-joda';

try {
  LocalDate.parse('2026-02-31');
} catch (e) {
  // DateTimeParseException
}

Типичные причины ошибок:

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

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

При работе с ZonedDateTime важно учитывать корректность идентификаторов зон:

import { ZonedDateTime } from 'js-joda';

const zdt = ZonedDateTime.parse('2026-05-24T12:00:00+03:00[Asia/Almaty]');

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

  • зона должна соответствовать базе IANA
  • смещение и зона могут проверяться на согласованность

Комбинированные форматы и кастомные шаблоны

Сложные форматы требуют составного DateTimeFormatter:

import { LocalDateTime, DateTimeFormatter } from 'js-joda';

const formatter = DateTimeFormatter.ofPattern('yyyy/MM/dd HH-mm-ss');

const dt = LocalDateTime.parse('2026/05/24 14-30-15', formatter);

Нормализация входных данных

Перед парсингом часто выполняется предварительная обработка строк:

  • удаление пробелов
  • унификация разделителей
  • приведение к UTF-8
  • замена локальных символов (например, запятых)

Пример:

const normalized = input.replace(',', '.').trim();

Производительность парсинга

В js-joda парсинг оптимизирован под повторное использование DateTimeFormatter.

Ключевые особенности:

  • форматтеры рекомендуется создавать один раз
  • повторный парсинг с тем же форматтером быстрее
  • ISO-парсинг быстрее кастомного

Сравнение ISO и кастомного парсинга

  • ISO (parse без formatter):

    • быстрее
    • меньше ошибок
    • стандартный формат

  • кастомный formatter:

    • гибкость
    • локализация
    • более высокая стоимость обработки

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

  • импорт данных из CSV с датами в локальном формате
  • обработка пользовательского ввода
  • интеграция с API, возвращающими нестандартные даты
  • парсинг логов с временными метками
  • миграция данных между системами с разными форматами времени
Оглавление