Структура документации

Документация Day.js построена по принципу минималистичной модульной структуры, отражающей философию самой библиотеки: компактность ядра, расширяемость через плагины и предсказуемое поведение API. Основная цель документации — обеспечить быстрый доступ к функциональности без перегрузки избыточной теорией.

Вся информация организуется вокруг трёх ключевых уровней:

  • базовое API ядра
  • расширения через плагины
  • вспомогательные инструменты и утилиты

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

Базовое ядро документации

Ядро документации описывает основные операции с датами. В него входят функции создания, преобразования и форматирования объектов времени.

Создание дат

Основной способ работы с Day.js начинается с создания экземпляра:

import dayjs from 'dayjs';

const now = dayjs();
const fromString = dayjs('2026-01-01');
const fromTimestamp = dayjs(1700000000000);

Документация фиксирует несколько стандартных входных форматов:

  • строка даты (ISO 8601 и совместимые форматы)
  • Unix timestamp (миллисекунды)
  • объект Date JavaScript
  • копирование существующего экземпляра Day.js

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

Методы чтения значений

Раздел документации, посвящённый чтению данных, описывает методы получения компонентов даты:

dayjs().year();
dayjs().month();
dayjs().date();
dayjs().hour();
dayjs().minute();
dayjs().second();

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

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

Каждый метод документируется с указанием диапазона значений и особенностей нумерации (например, месяцы с нуля).

Методы изменения состояния

Изменение даты описывается через иммутабельную модель. Каждый вызов возвращает новый объект:

const d1 = dayjs();
const d2 = d1.add(7, 'day');
const d3 = d2.subtract(1, 'month');

Документация фиксирует важный принцип: исходный объект не изменяется. Это поведение последовательно распространяется на все методы модификации.

Группировка методов:

  • add — прибавление интервалов
  • subtract — вычитание интервалов
  • set — установка конкретных компонентов

Форматирование и вывод

Отдельный раздел документации посвящён преобразованию дат в строки.

Метод format

dayjs().format('YYYY-MM-DD');
dayjs().format('HH:mm:ss');
dayjs().format('DD/MM/YYYY');

Структура документации по форматированию включает:

  • перечень токенов форматирования
  • правила интерпретации символов
  • особенности локализации

Токены описываются как отдельные элементы синтаксиса:

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

Локализация форматов

Документация разделяет локализацию на два уровня:

  • перевод названий месяцев и дней недели
  • адаптация форматов даты и времени

Подключение локали описывается отдельно:

import 'dayjs/locale/ru';
dayjs.locale('ru');

Плагины как часть документационной структуры

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

Подключение плагинов

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

dayjs.extend(utc);

Документация фиксирует обязательный порядок:

  • импорт базового Day.js
  • импорт плагина
  • регистрация через extend

Типовая структура описания плагина

Каждый плагин в документации имеет одинаковую схему:

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

Примеры плагинов:

  • UTC
  • timezone
  • relativeTime
  • duration
  • customParseFormat

Расширенные методы работы с датами

Документация выделяет отдельный слой API, связанный с вычислениями.

Сравнение дат

dayjs('2026-01-01').isBefore('2027-01-01');
dayjs('2026-01-01').isAfter('2025-01-01');
dayjs('2026-01-01').isSame('2026-01-01');

Описание группируется по логическим операциям:

  • строгие сравнения
  • сравнения с точностью до единицы времени
  • диапазонные проверки

Разница между датами

dayjs('2026-01-10').diff('2026-01-01', 'day');

Документация фиксирует:

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

Работа с Unix-временем

Отдельный раздел документации посвящён взаимодействию с временными метками.

dayjs().valueOf();
dayjs().unix();
dayjs.unix(1700000000);

Структура описания включает:

  • миллисекунды (valueOf)
  • секунды (unix)
  • преобразование из timestamp

Обработка недействительных дат

Документация выделяет поведение при ошибочных входных данных.

dayjs('invalid').isValid();

Ключевые аспекты:

  • детекция некорректного парсинга
  • распространение invalid-состояния через цепочки вызовов
  • отсутствие исключений при ошибках парсинга

Интерфейс плагинов внутри документации

Структура документации отражает внутреннюю архитектуру расширений через единый API-подход.

Плагин описывается как функция, расширяющая прототип:

export default (option, Dayjs, dayjs) => {
  // расширение функциональности
};

Каждый плагин документируется через:

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

Организация примеров в документации

Примеры структурируются по уровням сложности:

  • базовые операции
  • комбинированные цепочки методов
  • интеграция с внешними библиотеками

Пример цепочки:

dayjs()
  .add(1, 'month')
  .subtract(7, 'day')
  .format('YYYY-MM-DD');

Документационная модель делает акцент на цепочечности вызовов как фундаментальном принципе API.

Разделение ответственности в документации

Внутренняя структура документации Day.js отражает архитектурное разделение самой библиотеки:

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

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

Оглавление