Форматирование в ISO

Формат ISO 8601 — стандарт представления даты и времени, который широко используется в JavaScript-экосистеме и является базовым для сериализации времени в Day.js. Он задаёт однозначную структуру строки, устраняя проблемы локальных форматов и неоднозначностей вроде «03/04/2026».

В Day.js работа с ISO строится вокруг двух ключевых операций:

  • преобразование даты в ISO-строку
  • создание объекта даты из ISO-строки

Day.js по умолчанию использует immutable-модель: каждая операция возвращает новый экземпляр объекта, не изменяя исходный.

Формирование ISO-строки через toISOString

Метод toISOString() возвращает дату в строгом формате UTC:

import dayjs from 'dayjs';

const now = dayjs();
const iso = now.toISOString();

console.log(iso);

Результат всегда соответствует шаблону:

YYYY-MM-DDTHH:mm:ss.sssZ

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

  • всегда используется UTC
  • присутствуют миллисекунды
  • суффикс Z указывает на нулевое смещение часового пояса
  • результат совместим с Date.prototype.toISOString()

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

Разбор ISO-строк при создании даты

Day.js автоматически распознаёт ISO 8601 при передаче строки в конструктор:

import dayjs from 'dayjs';

const date = dayjs('2026-05-23T14:30:00Z');
console.log(date.format());

Поддерживаются основные варианты ISO:

  • полная дата и время: 2026-05-23T14:30:00Z
  • с миллисекундами: 2026-05-23T14:30:00.123Z
  • с часовым смещением: 2026-05-23T14:30:00+03:00
  • только дата: 2026-05-23

При разборе Day.js:

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

Локальное время и ISO: ключевое различие

Day.js хранит время в виде Unix timestamp (миллисекунды с эпохи Unix). ISO-строка является лишь представлением этого значения.

Пример:

const local = dayjs();
const iso = local.toISOString();

console.log(local.format('YYYY-MM-DD HH:mm:ss'));
console.log(iso);

Разница принципиальная:

  • format() показывает локальное время
  • toISOString() всегда возвращает UTC

Это приводит к важному следствию: одинаковый timestamp может выглядеть по-разному в разных форматах.

Контроль временной зоны при ISO-форматировании

Для управления временными зонами в контексте ISO часто используется плагин UTC:

import dayjs from 'dayjs';
import utc from 'dayjs/plugin/utc';

dayjs.extend(utc);

const utcDate = dayjs.utc().toISOString();
console.log(utcDate);

После подключения utc появляется возможность явно работать с UTC-режимом:

  • dayjs.utc() — создание даты в UTC
  • toISOString() — возвращение уже нормализованного значения
  • исключение локальных смещений

ISO-форматирование через format()

Хотя toISOString() является каноническим методом, ISO-строки часто формируются вручную через format() для контроля структуры:

const d = dayjs();

const isoLike = d.format('YYYY-MM-DDTHH:mm:ssZ');
console.log(isoLike);

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

  • T задаётся как литерал
  • Z в format() — это не UTC-знак, а смещение часового пояса
  • результат зависит от локального времени

Если требуется строгий UTC ISO, необходимо комбинировать с utc():

import utc from 'dayjs/plugin/utc';
dayjs.extend(utc);

const isoUtc = dayjs.utc().format('YYYY-MM-DDTHH:mm:ss[Z]');

Квадратные скобки фиксируют литерал Z.

Нормализация входных ISO-значений

При работе с API часто приходят строки ISO, которые могут быть в разных вариантах. Day.js выполняет нормализацию:

const a = dayjs('2026-05-23T00:00:00Z');
const b = dayjs('2026-05-23T03:00:00+03:00');

console.log(a.valueOf() === b.valueOf());

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

Ключевой принцип:

  • ISO-строка может быть разной
  • внутреннее значение времени — единое

Строгая проверка ISO-валидности

Day.js не выбрасывает исключения при невалидной дате, а помечает объект как invalid:

const d = dayjs('invalid-date');

console.log(d.isValid());

При работе с ISO это важно, поскольку:

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

Работа с миллисекундами в ISO

ISO-формат поддерживает точность до миллисекунд:

const precise = dayjs().millisecond(123).toISOString();
console.log(precise);

Формат:

YYYY-MM-DDTHH:mm:ss.123Z

Если миллисекунды равны нулю, они всё равно могут отображаться в стандартной сериализации.

Сравнение ISO и Unix timestamp

ISO и Unix timestamp являются взаимозаменяемыми представлениями одной сущности:

const d = dayjs();

console.log(d.valueOf());
console.log(d.toISOString());

Различия:

  • timestamp: числовое значение, компактное и быстро сравнимое
  • ISO: человекочитаемая строка, пригодная для API и логов

Внутри Day.js оба формата преобразуются в одну и ту же временную точку.

Частые ошибки при работе с ISO

При использовании ISO-формата в Day.js часто возникают типовые ошибки:

  1. Игнорирование UTC в toISOString()

    • ожидание локального времени вместо UTC

  2. Неправильное использование Z в format()

    • подстановка буквального символа вместо часового смещения

  3. Смешивание локальных и UTC-дат

    • приводит к смещению времени на несколько часов

  4. Отсутствие проверки isValid()

    • некорректные строки не вызывают исключений

ISO как универсальный контракт обмена данными

В прикладных системах ISO 8601 используется как универсальный формат передачи времени между:

  • клиентом и сервером
  • микросервисами
  • базами данных и API
  • логирующими системами

Day.js выступает как слой нормализации, обеспечивая:

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

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

Оглавление