Метод fromJSDate

Назначение и общая концепция

Метод fromJSDate используется для преобразования стандартного объекта JavaScript Date в объект DateTime библиотеки Luxon. Он служит мостом между встроенной датой языка и расширенной моделью работы с датами и временем, предоставляемой Luxon.

Ключевая особенность заключается в том, что Date в JavaScript представляет момент времени (timestamp) без встроенной поддержки временных зон, календарей и локалей, тогда как DateTime в Luxon добавляет поверх этого уровня строгую работу с временными зонами, форматами и календарными системами.

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

DateTime.fromJSDate(jsDate, options)

Параметры

jsDate

  • Тип: Date
  • Описание: стандартный объект JavaScript, представляющий момент времени

options

  • Тип: объект
  • Поддерживаемые поля:
{
  zone,
  locale,
  numberingSystem,
  outputCalendar,
  setZone
}

Базовое поведение преобразования

При вызове fromJSDate Luxon:

  • извлекает timestamp из объекта Date
  • интерпретирует его как абсолютный момент времени
  • создаёт DateTime, привязанный к указанной временной зоне (или зоне по умолчанию)
import { DateTime } from "luxon";

const jsDate = new Date();

const dt = DateTime.fromJSDate(jsDate);

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

Работа с временными зонами

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

Использование параметра zone

const dt = DateTime.fromJSDate(new Date(), {
  zone: "Europe/Paris"
});

В этом случае один и тот же момент времени будет представлен в зоне Europe/Paris, независимо от системной зоны окружения.

Поведение setZone

Параметр setZone влияет на то, как интерпретируется временная зона при создании объекта:

  • setZone: false (по умолчанию) — используется указанная зона или системная зона Luxon
  • setZone: true — сохраняется исходная локальная интерпретация времени
const dt = DateTime.fromJSDate(new Date(), {
  setZone: true
});

Это особенно важно при работе с данными, где важна локальная интерпретация времени, а не только абсолютный timestamp.

Работа с локалью

Luxon позволяет сразу задавать локаль при преобразовании:

const dt = DateTime.fromJSDate(new Date(), {
  locale: "ru"
});

Локаль влияет на:

  • форматирование дат
  • отображение месяцев и дней недели
  • правила форматирования чисел (в связке с numberingSystem)

Поддержка систем счисления и календарей

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

const dt = DateTime.fromJSDate(new Date(), {
  numberingSystem: "latn",
  outputCalendar: "gregory"
});
  • numberingSystem определяет систему цифр (например, латинская, арабская и др.)
  • outputCalendar задаёт календарную систему (григорианский, исламский и т.д.)

Отличие от других методов создания DateTime

fromJSDate vs fromISO

  • fromJSDate работает с объектом Date
  • fromISO работает со строкой ISO 8601
DateTime.fromJSDate(new Date());
DateTime.fromISO("2026-05-23T10:00:00");

fromJSDate vs fromObject

  • fromJSDate принимает готовый момент времени
  • fromObject создаёт дату из компонент (год, месяц, день и т.д.)
DateTime.fromObject({
  year: 2026,
  month: 5,
  day: 23
});

Временная точность и особенности JavaScript Date

Объект Date хранит время в миллисекундах с начала Unix эпохи. При преобразовании через fromJSDate:

  • сохраняется точная метка времени
  • возможна потеря точности только в пределах ограничений JS Date (миллисекунды)
const jsDate = new Date("2026-05-23T12:34:56.789Z");

const dt = DateTime.fromJSDate(jsDate);

dt.toISO(); 
// сохраняет миллисекунды

Обработка временных зон и DST

При переходах на летнее/зимнее время поведение зависит от зоны:

  • Luxon корректно пересчитывает локальное время при смене DST
  • абсолютный момент времени не изменяется
const dt = DateTime.fromJSDate(new Date("2026-03-29T01:30:00Z"), {
  zone: "Europe/Berlin"
});

Если локальное время попадает в “провал” или “дубликат” при смене DST, Luxon корректно разрешает неоднозначность через правила временной зоны.

Иммутабельность результата

DateTime является неизменяемым объектом:

  • любой метод преобразования возвращает новый экземпляр
  • исходный объект Date остаётся неизменным
const jsDate = new Date();

const dt1 = DateTime.fromJSDate(jsDate);
const dt2 = dt1.set({ hour: 10 });

dt1 === dt2; // false

Использование в цепочках преобразований

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

const result = DateTime.fromJSDate(new Date())
  .setZone("UTC")
  .plus({ days: 3 })
  .setLocale("ru")
  .toFormat("dd LLL yyyy");

Такая модель позволяет:

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

Пограничные случаи

Передача некорректного значения

DateTime.fromJSDate(null); // invalid DateTime

Luxon возвращает объект DateTime, помеченный как невалидный (isValid = false).

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

new Date("invalid");

Такой объект также приводит к невалидному DateTime.

Работа с эпохой Unix

DateTime.fromJSDate(new Date(0));

Результат соответствует 1970-01-01T00:00:00Z, с последующей интерпретацией в указанной зоне.

Практические сценарии использования

Интеграция с API

Многие API возвращают даты как ISO-строки, но клиентский код может оперировать Date. fromJSDate используется для унификации:

function normalize(date) {
  return DateTime.fromJSDate(date).toUTC();
}

Работа с пользовательским вводом

Если дата уже была преобразована в Date через HTML-элементы или библиотеки UI:

const inputDate = new Date(input.value);

const dt = DateTime.fromJSDate(inputDate, {
  zone: "system"
});

Логирование и аудит событий

const eventTime = DateTime.fromJSDate(new Date(), {
  zone: "UTC"
}).toISO();

Взаимодействие с системной зоной

Если не указана зона явно:

  • используется зона по умолчанию Luxon (обычно системная)
  • результат зависит от окружения (браузер / Node.js)
DateTime.fromJSDate(new Date());

Это поведение важно учитывать при переносе кода между средами.

Оглавление