Создание из объекта

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

Основной метод для этого сценария — DateTime.fromObject.

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

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

import { DateTime } from "luxon";

const dt = DateTime.fromObject({
  year: 2026,
  month: 5,
  day: 23,
  hour: 14,
  minute: 30
});

Результатом является полноценный объект DateTime, включающий указанные компоненты.

Поддерживаемые поля

При создании через объект доступны основные временные компоненты:

  • year — год
  • month — месяц (1–12)
  • day — день месяца
  • hour — часы (0–23)
  • minute — минуты (0–59)
  • second — секунды (0–59)
  • millisecond — миллисекунды (0–999)

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

const dt = DateTime.fromObject({
  year: 2025,
  month: 12,
  day: 31,
  hour: 23,
  minute: 59,
  second: 59,
  millisecond: 999
});

Если часть полей не указана, используются значения по умолчанию.

Поведение при неполных данных

При отсутствии некоторых компонентов Luxon заполняет их стандартными значениями:

  • день по умолчанию — 1
  • время по умолчанию — 00:00:00.000
const dt = DateTime.fromObject({
  year: 2026,
  month: 1
});

Результат интерпретируется как:

2026-01-01T00:00:00.000

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

Часовой пояс при создании из объекта

Одним из ключевых параметров является zone, определяющий временную зону.

const dt = DateTime.fromObject(
  {
    year: 2026,
    month: 5,
    day: 23,
    hour: 10
  },
  {
    zone: "Europe/Moscow"
  }
);

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

  • строковое значение зоны может быть IANA-идентификатором
  • возможны смещения UTC (UTC+3, UTC)
  • если зона не указана, используется локальная системная

Часовой пояс влияет на интерпретацию всех компонентов времени.

Локаль и форматирование

Помимо зоны, объект конфигурации поддерживает параметр locale.

const dt = DateTime.fromObject(
  {
    year: 2026,
    month: 5,
    day: 23
  },
  {
    locale: "ru"
  }
);

Локаль не влияет на внутреннее хранение даты, но определяет:

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

Календарные системы и системы нумерации

Luxon поддерживает расширенные параметры календаря:

numberingSystem

Определяет систему цифр:

const dt = DateTime.fromObject(
  {
    year: 2026,
    month: 5,
    day: 23
  },
  {
    numberingSystem: "latn"
  }
);

Примеры систем:

  • latn — латинские цифры
  • arab — арабские
  • deva — деванагари

outputCalendar

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

const dt = DateTime.fromObject(
  {
    year: 2026,
    month: 5,
    day: 23
  },
  {
    outputCalendar: "islamic"
  }
);

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

Нормализация значений

При создании из объекта Luxon автоматически корректирует некорректные значения.

Пример:

const dt = DateTime.fromObject({
  year: 2026,
  month: 2,
  day: 30
});

Февраль не имеет 30 дней, поэтому результат будет нормализован:

  • дата будет приведена к корректному значению в рамках календаря

Подобное поведение распространяется и на время:

const dt = DateTime.fromObject({
  hour: 25,
  minute: 90
});

Значения будут перераспределены по стандартным правилам времени.

Использование UTC

Создание даты в UTC-зоне:

const dt = DateTime.fromObject(
  {
    year: 2026,
    month: 5,
    day: 23,
    hour: 12
  },
  {
    zone: "utc"
  }
);

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

Работа с частичными временными объектами

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

const dt = DateTime.fromObject({
  hour: 9,
  minute: 0
});

В таком случае дата устанавливается на базовую (обычно текущий день или 1970-01-01 в зависимости от контекста и зоны), а указанные поля применяются поверх.

Поведение при ошибках

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

const dt = DateTime.fromObject({
  year: "invalid"
});

Проверка состояния:

dt.isValid;
dt.invalidReason;
dt.invalidExplanation;

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

Частые сценарии применения

Создание даты из формы

const formData = {
  year: 2026,
  month: 5,
  day: 23
};

const dt = DateTime.fromObject(formData);

Конструирование временных меток API

const payload = {
  year: 2026,
  month: 5,
  day: 23,
  hour: 18,
  minute: 45
};

const dt = DateTime.fromObject(payload, { zone: "utc" });

Построение расписаний

const scheduleTime = DateTime.fromObject({
  hour: 8,
  minute: 30
});

Особенности интерпретации данных

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

Важные ограничения

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

Комбинирование с другими методами

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

const dt = DateTime.fromObject({
  year: 2026,
  month: 5,
  day: 23
}).setZone("Europe/Berlin");

или с форматированием:

const formatted = DateTime.fromObject({
  year: 2026,
  month: 5,
  day: 23
}).toISO();

Модель данных при создании

Внутри Luxon объект строится как неизменяемая структура, где:

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

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

Оглавление