Метод toObject

В библиотеке Luxon объект типа DateTime представляет собой полноценную модель даты и времени с поддержкой временных зон, локалей и календарной арифметики. Одним из ключевых методов для извлечения структурированных данных из такого объекта является toObject(), который преобразует экземпляр DateTime в обычный JavaScript-объект с полями, соответствующими компонентам даты и времени.

Метод возвращает простой объект, содержащий только те компоненты, которые присутствуют в исходном DateTime. Это делает его удобным для сериализации, передачи между слоями приложения или частичного анализа даты без привязки к внутренним механизмам Luxon.

Базовая форма результата выглядит следующим образом:

{
  year: number,
  month: number,
  day: number,
  hour: number,
  minute: number,
  second: number,
  millisecond: number
}

Каждое поле включается только при наличии соответствующей информации в исходном объекте. Например, если DateTime создан без указания времени, поля hour, minute, second и millisecond могут отсутствовать.

Сигнатура метода

DateTime.toObject(options?: Object): Object

Метод не изменяет исходный экземпляр. Он всегда возвращает новый объект.

Параметр options используется для контроля набора возвращаемых полей.

Поля результата

toObject() может возвращать следующие компоненты:

  • year — год
  • month — месяц (1–12)
  • day — день месяца
  • ordinal — порядковый день года (1–366)
  • weekYear — ISO-год недели
  • weekNumber — номер недели по ISO
  • weekday — день недели (1–7)
  • hour — часы (0–23)
  • minute — минуты (0–59)
  • second — секунды (0–59)
  • millisecond — миллисекунды (0–999)

Набор полей зависит от конфигурации и исходных данных DateTime.

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

При вызове без аргументов метод возвращает максимально полный объект на основе текущего состояния:

import { DateTime } from "luxon";

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

const obj = dt.toObject();

Результат:

{
  year: 2026,
  month: 5,
  day: 23,
  hour: 14,
  minute: 45,
  second: 0,
  millisecond: 0
}

Если исходный объект не содержит времени, соответствующие поля могут отсутствовать полностью.

Использование частичных полей

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

const dateOnly = DateTime.local(2026, 5, 23).toObject({
  includeOffset: false
});

В результате может быть получен объект вида:

{
  year: 2026,
  month: 5,
  day: 23
}

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

Работа с календарными компонентами

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

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

dt.toObject({ includeWeek: true });

Возможный результат:

{
  year: 2026,
  month: 5,
  day: 23,
  weekYear: 2026,
  weekNumber: 21,
  weekday: 6
}

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

Поведение при отсутствии компонентов

Если DateTime был создан без некоторых компонентов, метод не заполняет их значениями по умолчанию, а просто исключает их из результата. Это важное отличие от стандартных JavaScript-объектов Date, которые всегда возвращают полный набор полей через методы-геттеры.

Пример:

const dt = DateTime.local(2026);

dt.toObject();

Результат:

{
  year: 2026
}

Влияние временной зоны

Метод возвращает значения уже в контексте локального времени объекта DateTime. Если экземпляр создан с таймзоной, отличной от системной, значения отражают именно эту зону.

const dt = DateTime.fromISO("2026-05-23T10:00:00", {
  zone: "UTC"
});

dt.toObject();

Даже при локальной зоне пользователя результат будет соответствовать UTC-времени, если оно задано в объекте.

Отличие от toJSDate()

toObject() и toJSDate() решают разные задачи:

  • toJSDate() возвращает объект Date
  • toObject() возвращает структурированный plain-object

Сравнение:

dt.toJSDate(); // Date
dt.toObject(); // { year, month, day, ... }

toObject() предпочтителен в случаях, когда требуется сохранить отдельные компоненты времени, а не единую метку времени.

Сериализация и переносимость

Результат toObject() легко сериализуется в JSON:

JSON.stringify(dt.toObject());

Это делает метод удобным для:

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

Частичное извлечение и фильтрация

Объект, возвращаемый toObject(), можно использовать для выборочного извлечения данных:

const { year, month, day } = dt.toObject();

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

Особенности работы с миллисекундами

Поле millisecond присутствует только при наличии точного времени. При создании объекта без указания долей секунды оно обычно равно 0, но может отсутствовать в результате при определённых конфигурациях:

DateTime.local(2026, 5, 23, 10, 0, 0, 0).toObject();
{
  year: 2026,
  month: 5,
  day: 23,
  hour: 10,
  minute: 0,
  second: 0,
  millisecond: 0
}

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

Если исходный DateTime является невалидным (Invalid DateTime), метод возвращает пустой объект:

DateTime.invalid("error").toObject();

Результат:

{}

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

Использование в вычислительных цепочках

Метод часто применяется в связке с другими функциями Luxon:

const normalized = DateTime.local()
  .plus({ days: 5 })
  .startOf("day")
  .toObject();

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

Поведение при локалях и форматировании

Метод не зависит от локали напрямую. Он не форматирует строки и не применяет языковые правила. Все возвращаемые данные являются числовыми компонентами, что исключает влияние региональных настроек на результат.

Типичные сценарии применения

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

Ограничения

  • отсутствует форматирование строк
  • не возвращаются производные значения (например, UNIX timestamp)
  • поведение зависит от исходного состояния DateTime
  • не выполняет округление или нормализацию вне контекста Luxon

Взаимодействие с расширенными полями

При включении календарных расширений объект может включать дополнительные свойства, связанные с ISO-неделями и порядковыми днями года. Это делает метод полезным в аналитических задачах, где календарные системы важнее стандартных календарных разбиений на месяц и день.

Оглавление