Глобальные настройки

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

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

Объект Settings и его роль

Внутренний объект Settings централизует конфигурацию библиотеки:

import { Settings } from "luxon";

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

Основные группы параметров:

  • локализация (locale, numberingSystem, outputCalendar)
  • временная зона (defaultZone)
  • поведение обработки ошибок (throwOnInvalid)
  • источник текущего времени (now provider)

Глобальная локаль (defaultLocale)

Параметр defaultLocale определяет язык и региональные правила форматирования дат.

import { Settings } from "luxon";

Settings.defaultLocale = "ru";

После установки все операции форматирования используют русскую локаль, если не указано иное:

import { DateTime } from "luxon";

const dt = DateTime.local(2026, 5, 23);
dt.toLocaleString(DateTime.DATE_FULL);
// например: "23 мая 2026 г."

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

Если defaultLocale не задан:

  • используется локаль среды выполнения (браузера или Node.js)
  • при невозможности определения применяется en-US

Глобальная временная зона (defaultZone)

defaultZone определяет часовой пояс, который используется при создании DateTime, если зона не передана явно.

import { Settings } from "luxon";

Settings.defaultZone = "Europe/Moscow";

После этого:

import { DateTime } from "luxon";

const dt = DateTime.local();
dt.zoneName; // "Europe/Moscow"

Влияние на DateTime.local()

Метод DateTime.local() не привязан к системной зоне напрямую, если задан Settings.defaultZone. Это позволяет унифицировать работу сервера и клиента.

Часовая зона и строгая интерпретация

При установке defaultZone важно учитывать:

  • строка должна соответствовать IANA Time Zone Database
  • некорректные значения приводят к fallback на системную зону
  • зона применяется только при создании новых экземпляров
Settings.defaultZone = "Asia/Almaty";

Система числовых форматов (defaultNumberingSystem)

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

import { Settings } from "luxon";

Settings.defaultNumberingSystem = "latn";

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

DateTime.local(2026, 5, 23).toLocaleString();
// "05/23/2026" (в зависимости от локали)

Для арабских систем:

Settings.defaultNumberingSystem = "arab";

Календарная система (defaultOutputCalendar)

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

import { Settings } from "luxon";

Settings.defaultOutputCalendar = "gregory";

Поддерживаются альтернативные системы:

  • gregory — григорианский календарь (по умолчанию)
  • islamic
  • buddhist
  • hebrew
  • chinese

Изменение календаря влияет только на представление, но не на внутренние расчёты времени.

Управление текущим временем (now provider)

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

По умолчанию:

Settings.now(); // Date.now()

Можно заменить:

Settings.now = () => 0;

После этого все операции, зависящие от текущего времени, будут использовать фиксированное значение.

Применение в тестировании

import { Settings, DateTime } from "luxon";

Settings.now = () => 1700000000000;

const dt = DateTime.now();
dt.toMillis(); // 1700000000000

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

Поведение при некорректных значениях (throwOnInvalid)

Настройка throwOnInvalid управляет тем, как библиотека реагирует на некорректные даты.

import { Settings } from "luxon";

Settings.throwOnInvalid = true;

Режимы работы

  • true — выбрасывается исключение при ошибке создания DateTime
  • false — возвращается объект с состоянием Invalid DateTime

Пример:

const dt = DateTime.fromISO("invalid-date");

dt.isValid; // false
dt.invalidReason; // причина ошибки

При включённом режиме:

Settings.throwOnInvalid = true;

DateTime.fromISO("invalid-date"); // исключение

Глобальная зона по умолчанию и приоритеты

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

  1. явно переданная зона (setZone, zone в методе)
  2. зона из объекта
  3. Settings.defaultZone
  4. системная зона окружения

Пример:

Settings.defaultZone = "Europe/London";

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

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

DateTime.local(2026, 5, 23, { zone: "Asia/Tokyo" });

глобальная настройка игнорируется.

Изоляция глобальных настроек

Поскольку Settings является глобальным объектом, изменения влияют на всё приложение.

Типичные сценарии изоляции:

  • временное переопределение
  • восстановление предыдущих значений

Пример сохранения состояния:

const oldZone = Settings.defaultZone;

Settings.defaultZone = "UTC";

// операции

Settings.defaultZone = oldZone;

Совместное влияние настроек

Глобальные параметры взаимодействуют между собой при форматировании:

  • defaultLocale определяет язык
  • defaultNumberingSystem влияет на цифры
  • defaultOutputCalendar влияет на структуру даты
  • defaultZone влияет на вычисление времени

Пример комплексного эффекта:

Settings.defaultLocale = "ar";
Settings.defaultNumberingSystem = "arab";
Settings.defaultZone = "Asia/Riyadh";

DateTime.local().toLocaleString(DateTime.DATETIME_FULL);

Результат будет зависеть одновременно от всех четырёх параметров.

Сброс глобальных настроек

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

Settings.defaultLocale = "en-US";
Settings.defaultZone = "system";
Settings.defaultNumberingSystem = null;
Settings.defaultOutputCalendar = null;
Settings.throwOnInvalid = false;
Settings.now = () => Date.now();

Влияние на сериализацию и парсинг

Глобальные настройки влияют не только на вывод, но и на разбор строк:

  • ISO-парсинг не зависит от локали
  • форматированные строки зависят от defaultLocale
  • отображение календаря влияет на toLocaleString

Пример:

Settings.defaultLocale = "fr";

DateTime.local().toLocaleString(DateTime.DATE_FULL);

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

Браузер

  • defaultZone часто игнорируется при явной работе с Intl
  • defaultLocale берётся из navigator.language

Node.js

  • локаль зависит от системных переменных окружения
  • зона чаще всего системная (process.env.TZ)

Ограничения глобальной конфигурации

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

Практическая модель применения

Глобальные настройки обычно фиксируются на этапе инициализации приложения:

import { Settings } from "luxon";

Settings.defaultLocale = "ru";
Settings.defaultZone = "Europe/Moscow";
Settings.throwOnInvalid = false;

После этого дальнейшая работа с датами опирается на единый контекст форматирования и вычислений.

Оглавление