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

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

Ключевая особенность заключается в том, что результат метода всегда можно однозначно классифицировать:

  • экземпляр Dayjs (цепочки и преобразования даты)
  • строка (форматирование)
  • число (таймстемпы, вычисления)
  • объект Date (интероперабельность с нативным API)
  • boolean (сравнения)

Такое разделение упрощает предсказуемость API и снижает риск скрытых мутаций состояния.

Экземпляр Dayjs как основной возвращаемый тип

Большинство методов возвращают новый объект Dayjs. Это обеспечивает возможность цепочек вызовов и гарантирует неизменность исходных данных.

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

  • add
  • subtract
  • startOf
  • endOf
  • set
  • millisecond, second, minute, hour, date, month, year (в сеттер-режиме)

Каждый из этих методов создаёт новый объект:

const d1 = dayjs('2024-01-01');
const d2 = d1.add(1, 'day');

d1 !== d2;

Важное следствие: любые цепочки строятся на новых экземплярах, а не на изменении текущего состояния:

const result = dayjs('2024-01-01')
  .add(2, 'day')
  .subtract(1, 'month')
  .startOf('day');

Каждый шаг возвращает новый Dayjs-объект, что делает поведение детерминированным.

Методы, возвращающие строковые значения

Часть API предназначена для сериализации даты в текстовые представления. Эти методы всегда возвращают string, независимо от исходного состояния объекта.

format

format — основной метод преобразования даты в строку по заданному шаблону:

dayjs('2024-01-01').format('YYYY-MM-DD');

Возвращаемое значение полностью зависит от шаблона и локали, но всегда является строкой.

toString

Возвращает строковое представление в стандартном формате:

dayjs('2024-01-01').toString();

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

locale-aware методы

При подключении локалей некоторые методы форматирования также возвращают строки, адаптированные под язык:

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

Числовые возвращаемые значения

Числовой тип используется для операций сравнения, вычисления времени и интероперабельности с Unix-таймстампами.

valueOf

Возвращает timestamp в миллисекундах:

dayjs('2024-01-01').valueOf();

Эквивалентно Date.getTime().

unix

Возвращает timestamp в секундах:

dayjs('2024-01-01').unix();

Разница между unix и valueOf принципиальна:

  • valueOf → миллисекунды
  • unix → секунды

diff

Метод вычисления разницы между датами возвращает число:

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

Результат зависит от единицы измерения:

  • milliseconds
  • seconds
  • minutes
  • hours
  • days
  • months
  • years

Возвращаемое значение всегда числовое, округление зависит от параметров.

Возвращение объекта Date

Метод toDate обеспечивает интеграцию с нативным JavaScript API:

dayjs('2024-01-01').toDate();

Результат — полноценный объект Date.

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

  • создаётся новый Date
  • Dayjs-объект не теряется, так как он независим

Это важно при взаимодействии с API браузера, библиотеками и системными функциями, которые требуют нативный Date.

Логические возвращаемые значения

Некоторые методы предназначены для сравнения и проверки состояния. Они возвращают boolean.

isSame

dayjs('2024-01-01').isSame(dayjs('2024-01-01'), 'day');

isBefore

dayjs('2024-01-01').isBefore('2024-02-01');

isAfter

dayjs('2024-02-01').isAfter('2024-01-01');

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

Возвращаемые значения при цепочках вызовов

Цепочки в Day.js работают благодаря тому, что большинство методов возвращают экземпляр Dayjs.

Это создаёт единый поток преобразований:

dayjs()
  .add(1, 'year')
  .startOf('month')
  .subtract(2, 'days')
  .format('YYYY-MM-DD');

Финальный результат цепочки зависит от последнего метода:

  • если последний метод форматирования → string
  • если вычисление → number
  • если преобразование → Dayjs
  • если сравнение → boolean

Контраст типов возврата в одном API

Особенность Day.js заключается в смешении типов возврата в одном пространстве методов. Это требует строгого понимания категории каждого метода.

Категория метода Пример Возвращаемое значение
Трансформация add, subtract Dayjs
Форматирование format string
Сравнение isSame boolean
Конвертация toDate Date
Вычисление diff number
Timestamp unix, valueOf number

Такая модель делает API компактным, но строго типизированным по смыслу, а не по синтаксису.

Особенности неизменяемости и возврат новых объектов

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

const base = dayjs('2024-01-01');
const modified = base.add(10, 'day');

base.format('YYYY-MM-DD');      // 2024-01-01
modified.format('YYYY-MM-DD');  // 2024-01-11

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

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

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

  • относительное время (fromNow) → string
  • календарные интервалы → string
  • манипуляции с диапазонами → Dayjs или array Dayjs

Даже расширенные методы подчиняются тем же правилам: строка, число, объект, boolean или Date.

Приведение типов и неявные преобразования

Day.js не выполняет неявных сложных преобразований типов. Любое преобразование явно выражено методом:

  • format → string
  • valueOf → number
  • toDate → Date

Это исключает неоднозначность при использовании операторов JavaScript.

Поведение при цепочках смешанных типов

Цепочки разрываются при первом методе, возвращающем примитив:

const result = dayjs()
  .add(1, 'day')
  .format('YYYY-MM-DD')
  .add(1, 'day'); // ошибка: string не имеет метода add

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

Предсказуемость возвратов как основа архитектуры

Система возвратов строится на трёх принципах:

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

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

Оглавление