Особенности токенов

Токены форматирования в Day.js представляют собой компактный язык описания того, как дата и время должны быть преобразованы в строку или разобраны из строки. Их структура заимствована из Moment.js и построена на принципе последовательностей символов, каждая из которых соответствует конкретной части даты: году, месяцу, дню, времени, таймзоне или дополнительным вычисляемым представлениям.

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

Система токенов Day.js опирается на идею декларативного описания даты. Строка форматирования рассматривается как шаблон, где каждый фрагмент либо интерпретируется как токен, либо как литерал.

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

каждый токен — это строго определённая единица времени или представления даты

Например:

YYYY — полный год
MM — месяц с ведущим нулём
DD — день месяца
HH — часы в 24-часовом формате
mm — минуты
ss — секунды

Комбинация этих токенов формирует итоговое представление даты:

YYYY-MM-DD HH:mm:ss

Важно, что разделители (-, :, пробелы) не интерпретируются как токены и выводятся напрямую.

Чувствительность к регистру и длине

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

Примеры различий:

MM — месяц (01–12)
mm — минуты (00–59)

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

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

M — месяц без ведущего нуля (1–12)
MM — месяц с ведущим нулём (01–12)
MMM — сокращённое название месяца (Jan, Feb)
MMMM — полное название месяца (January, February)

Таким образом, количество повторений символа формирует семантику представления, а не просто декоративное расширение.

Токены времени и их поведение

Временные токены охватывают основные компоненты времени суток:

H / HH — 24-часовой формат
h / hh — 12-часовой формат
m / mm — минуты
s / ss — секунды
A — AM/PM в верхнем регистре
a — am/pm в нижнем регистре

Особенность заключается в зависимости некоторых токенов друг от друга. Например, использование 12-часового формата без токена A или a приводит к потере информации о половине суток.

Также важно учитывать отсутствие автоматической коррекции диапазонов при форматировании. Day.js всегда отображает значение так, как оно хранится внутри объекта даты.

Экранирование и литеральные значения

Токены могут конфликтовать с обычным текстом, поэтому используется механизм экранирования.

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

[YYYY] MM-DD

В этом случае YYYY не интерпретируется как год, а выводится как текст.

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

Дата создания: DD.MM.YYYY

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

Локализация токенов

Day.js поддерживает локализацию, которая влияет на текстовые представления дат:

названия месяцев
сокращённые формы месяцев
дни недели

Токены, связанные с текстовыми значениями, автоматически адаптируются под текущую локаль:

MMM — локализованное сокращение месяца
MMMM — локализованное полное название месяца
ddd — сокращённый день недели
dddd — полный день недели

Локализация не изменяет числовые токены, но влияет на вывод текстовых элементов, что делает форматирование контекстно-зависимым.

Особенность заключается в том, что смена локали влияет на результат без изменения самой строки формата.

Токены парсинга и форматирования входных строк

Помимо форматирования, токены используются при разборе строк даты:

dayjs("2026-01-15", "YYYY-MM-DD")

Здесь второй аргумент задаёт структуру входной строки. Day.js сопоставляет символы формата с соответствующими частями строки.

Особенности парсинга:

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

Ошибки в токенах приводят к некорректному разбору или невалидной дате.

Строгий режим разбора

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

В строгом режиме:

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

Это делает поведение предсказуемым при работе с фиксированными форматами данных, например в API или базах данных.

Расширенные токены через плагины

Базовый набор токенов Day.js ограничен, однако система плагинов расширяет их набор.

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

Do — порядковый день месяца (1st, 2nd, 3rd)
Qo — порядковый квартал (1st quarter и т.д.)
k / kk — часы от 1 до 24 вместо стандартного диапазона 0–23

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

Расширенные токены не активируются автоматически и требуют явного подключения плагина, что сохраняет минимализм ядра библиотеки.

Unix-временные токены

Day.js поддерживает специальные токены для работы с Unix-временем:

X — Unix timestamp в секундах
x — Unix timestamp в миллисекундах

Особенность этих токенов заключается в том, что они не зависят от локали, формата или календаря. Они всегда возвращают абсолютное значение времени относительно эпохи Unix.

Это делает их удобными для межсистемного обмена данными, где требуется унифицированное числовое представление даты.

Конфликты токенов и неоднозначности

Некоторые токены могут пересекаться по смыслу при неправильной интерпретации строки формата. Основные источники неоднозначности:

путаница между M (месяц) и m (минуты)
смешение 12-часового и 24-часового формата
отсутствие экранирования текстовых фрагментов
неправильное использование локализованных токенов

Такие ошибки не приводят к исключениям, но формируют некорректный вывод, что усложняет отладку.

Поведение токенов при сериализации

Форматирование даты в Day.js является детерминированным процессом. При одинаковом входном значении и одинаковой локали результат всегда совпадает.

Однако на результат влияют:

активные плагины
текущая локаль
временная зона (при использовании соответствующих расширений)

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

Производственные особенности системы токенов

Система токенов в Day.js оптимизирована под минимальный размер и высокую скорость обработки. Основные особенности реализации:

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

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

Поведение токенов в цепочках вызовов

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

Это приводит к следующей характеристике:

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

Такое поведение упрощает предсказуемость работы при многократном форматировании одного значения даты в разных представлениях.