Метод toISO

Метод toISO() в Luxon предназначен для преобразования объекта DateTime в строку формата ISO 8601 — стандартизированное представление даты и времени, широко используемое в API, базах данных и межсистемной передаче данных. Основная задача метода заключается в том, чтобы обеспечить точное, однозначное и переносимое представление момента времени с учётом временной зоны и дополнительных параметров точности.

ISO-строка, формируемая этим методом, может включать дату, время, смещение часового пояса и дробные секунды. Luxon предоставляет гибкие настройки, позволяющие контролировать уровень детализации результата.

Общая сигнатура

Метод вызывается на экземпляре DateTime:

DateTime.toISO(options?: Object): string | null

Возвращаемое значение:

  • string — строка в формате ISO 8601
  • null — в случае некорректного или невалидного объекта DateTime

Базовый формат ISO 8601

Результирующая строка обычно имеет следующий вид:

YYYY-MM-DDTHH:mm:ss.sss±HH:mm

Пример:

2026-05-23T14:45:30.123+06:00

Структура включает:

  • дату: YYYY-MM-DD
  • разделитель времени: T
  • время: HH:mm:ss
  • миллисекунды (опционально)
  • смещение часового пояса относительно UTC

Основные особенности метода

1. Полная временная однозначность

toISO() всегда возвращает момент времени с привязкой к конкретному часовому поясу, если он задан в объекте DateTime. Это исключает неоднозначность, характерную для локальных строковых форматов.

2. Поддержка временных зон

Luxon сохраняет информацию о зоне:

const dt = DateTime.now().setZone('Asia/Almaty');
dt.toISO();

Результат будет содержать корректное смещение:

2026-05-23T18:12:45.000+06:00

3. Управление точностью времени

Метод позволяет контролировать, будут ли включены:

  • миллисекунды
  • секунды
  • только дата

Это достигается через параметры.

Параметры метода

Метод принимает объект опций:

toISO({
  includeOffset,
  suppressMilliseconds,
  suppressSeconds,
  includeZone
})

includeOffset

Определяет, будет ли добавлено смещение часового пояса.

  • true (по умолчанию) — смещение присутствует
  • false — смещение удаляется

Пример:

dt.toISO({ includeOffset: false });

Результат:

2026-05-23T14:45:30.123

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

suppressMilliseconds

Удаляет миллисекунды из строки:

dt.toISO({ suppressMilliseconds: true });

Результат:

2026-05-23T14:45:30+06:00

Используется при необходимости уменьшить точность или соответствовать внешним API, не поддерживающим дробные секунды.

suppressSeconds

Полностью убирает секунды и миллисекунды:

dt.toISO({ suppressSeconds: true });

Результат:

2026-05-23T14:45+06:00

Применяется в интерфейсах, где точность до минуты достаточна (например, расписания).

includeZone

Добавляет идентификатор временной зоны:

dt.toISO({ includeZone: true });

Результат:

2026-05-23T14:45:30.123+06:00[Asia/Almaty]

Это расширенный формат ISO, полезный для систем, где важно не только смещение, но и исходная зона.

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

Базовое преобразование

const dt = DateTime.local(2026, 5, 23, 14, 45);
dt.toISO();

Результат:

2026-05-23T14:45:00.000+06:00

Удаление миллисекунд

dt.toISO({ suppressMilliseconds: true });

Результат:

2026-05-23T14:45:00+06:00

Формат без смещения

dt.toISO({ includeOffset: false });

Результат:

2026-05-23T14:45:00.000

Только дата (через комбинацию методов)

Хотя toISO() ориентирован на дату и время, при необходимости можно получить только дату через предварительную трансформацию:

dt.startOf('day').toISO({ suppressSeconds: true, includeOffset: true });

Результат:

2026-05-23T00:00+06:00

Поведение при невалидных значениях

Если объект DateTime находится в состоянии ошибки:

const dt = DateTime.fromISO('invalid-date');
dt.toISO();

Результат:

null

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

Особенности работы с UTC

При переводе в UTC форматирование сохраняет стандарт ISO с суффиксом Z:

const dt = DateTime.utc(2026, 5, 23, 14, 45);
dt.toISO();

Результат:

2026-05-23T14:45:00.000Z

Символ Z эквивалентен нулевому смещению.

Сравнение с другими методами форматирования

toISO vs toString

  • toISO() — строгий стандарт ISO 8601
  • toString() — человеко-читаемый формат Luxon

Пример:

dt.toString();
dt.toISO();

toString() может возвращать локализованные строки, тогда как toISO() всегда фиксирован.

toISO vs toFormat

  • toISO() — фиксированный стандарт
  • toFormat() — произвольное форматирование

Пример:

dt.toFormat('yyyy LLL dd HH:mm');

toISO() предпочтителен при обмене данными между системами, тогда как toFormat() — для UI.

Влияние настроек DateTime

Результат toISO() зависит от состояния объекта:

  • локальная зона (DateTime.local())
  • UTC (DateTime.utc())
  • заданная зона (setZone())

Пример:

DateTime.local().toISO();
DateTime.utc().toISO();
DateTime.local().setZone('Asia/Tokyo').toISO();

Каждый вызов отражает разное смещение и представление времени.

Использование в API и сериализации

ISO-строки часто применяются при:

  • передаче данных в REST API
  • сохранении временных меток в JSON
  • логировании событий
  • синхронизации распределённых систем

Пример сериализации:

JSON.stringify({
  createdAt: DateTime.now().toISO()
});

Потеря точности и контроль формата

При передаче данных важно учитывать, что:

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

Поэтому параметры suppressMilliseconds и includeOffset часто используются для адаптации строки под внешний контракт.

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

Если исходный объект содержит только дату:

const dt = DateTime.fromObject({ year: 2026, month: 5, day: 23 });
dt.toISO();

Результат:

2026-05-23T00:00:00.000+06:00

Luxon автоматически добавляет нулевое время.

Поведение при частичной информации

Если объект создан не полностью (например, отсутствуют часы или минуты), Luxon нормализует значения до стандартного времени 00:00:00, что гарантирует корректность ISO-строки.

Практическая значимость метода

Метод toISO() является базовым инструментом сериализации времени в Luxon и используется как основной способ получения машинно-читаемого представления даты и времени, совместимого с большинством современных систем обработки данных.

Он обеспечивает строгую стандартизацию формата, предсказуемость вывода и гибкость настройки уровня детализации без изменения внутреннего представления DateTime объекта.

Оглавление