Глобальная настройка

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

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

Settings представляет собой централизованное хранилище параметров, влияющих на:

  • интерпретацию временных зон;
  • локализацию вывода;
  • систему нумерации;
  • календарную систему;
  • обработку ошибок при разборе даты;
  • источник текущего времени.

Любое изменение Settings действует на все последующие операции создания DateTime, если параметры не указаны явно.

import { Settings } from "luxon";

defaultLocale

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

  • названия месяцев и дней недели;
  • формат представления даты;
  • правила форматирования чисел и текста;
  • поведение методов toLocaleString, toFormat.
import { Settings, DateTime } from "luxon";

Settings.defaultLocale = "ru";

const dt = DateTime.now();
console.log(dt.toLocaleString(DateTime.DATE_FULL));

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

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

defaultZone и управление временной зоной

Параметр defaultZone задаёт временную зону по умолчанию для всех создаваемых объектов DateTime, если зона не передана явно.

Settings.defaultZone = "Europe/Moscow";

const dt = DateTime.now();
console.log(dt.zoneName);

Возможные значения:

  • строка с IANA-зоной ("Europe/Moscow", "Asia/Almaty");
  • объект Zone (например, FixedOffsetZone);
  • специальное значение SystemZone.

Влияние defaultZone особенно заметно при использовании DateTime.local() и DateTime.now(), так как эти методы опираются на системное время и глобальную зону.

При работе в серверной среде (Node.js) важно учитывать, что системная зона может отличаться от ожидаемой бизнес-логики, поэтому явная настройка defaultZone часто используется для унификации поведения.

defaultOutputCalendar

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

Settings.defaultOutputCalendar = "islamic";

Поддерживаемые системы включают:

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

Календарная система влияет исключительно на отображение даты, не изменяя внутреннее представление времени (которое остаётся основанным на Unix timestamp).

defaultNumberingSystem

defaultNumberingSystem задаёт систему цифр, используемую при форматировании.

Settings.defaultNumberingSystem = "arab";

Возможные значения:

  • "latn" — латинские цифры (0–9);
  • "arab" — арабские;
  • "hanidec" — китайская десятичная система.

Изменение этого параметра влияет на все операции форматирования, включая локализацию строк даты.

throwOnInvalid

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

Settings.throwOnInvalid = true;

При значении:

  • false (по умолчанию) — возвращается объект DateTime с состоянием invalid, доступным через isValid и invalidReason;
  • true — выбрасывается исключение при попытке создать некорректную дату.
import { DateTime, Settings } from "luxon";

Settings.throwOnInvalid = true;

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

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

override default now

Luxon позволяет переопределить источник текущего времени через Settings.now. Это используется для тестирования и воспроизводимости.

Settings.now = () => new Date(2020, 0, 1).valueOf();

После установки все вызовы:

  • DateTime.now()
  • DateTime.local()

используют переопределённое значение времени.

Типичное применение связано с:

  • юнит-тестированием;
  • симуляцией времени;
  • детерминированными вычислениями.

Сброс осуществляется установкой:

Settings.now = () => Date.now();

resetToDefault и восстановление настроек

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

Settings.resetToDefault();

Сброс затрагивает:

  • defaultLocale;
  • defaultZone;
  • defaultOutputCalendar;
  • defaultNumberingSystem;
  • throwOnInvalid;
  • now.

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

Взаимодействие глобальных настроек с DateTime

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

Settings.defaultLocale = "ru";
Settings.defaultZone = "Asia/Almaty";

const a = DateTime.now(); 
const b = DateTime.now().setLocale("en");
const c = DateTime.now().setZone("UTC");

Приоритет разрешается следующим образом:

  1. Явно указанные параметры (setZone, setLocale);
  2. Глобальные настройки (Settings);
  3. Системные значения.

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

Особенности применения в серверной и клиентской среде

В браузере глобальные настройки действуют в рамках текущей сессии выполнения скрипта. В серверной среде (Node.js) они распространяются на весь процесс.

Это приводит к важному свойству: изменение Settings в одном модуле влияет на все остальные модули, использующие Luxon.

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

Примеры комбинированной конфигурации

import { Settings, DateTime } from "luxon";

Settings.defaultLocale = "ru";
Settings.defaultZone = "Europe/Moscow";
Settings.defaultOutputCalendar = "gregory";
Settings.defaultNumberingSystem = "latn";

const dt1 = DateTime.now();

const dt2 = DateTime.now()
  .setZone("UTC")
  .setLocale("en");

console.log(dt1.toString());
console.log(dt2.toString());

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

Управление побочными эффектами глобального состояния

Глобальная конфигурация представляет собой общий mutable-state, что требует контроля при масштабировании кода. Основные стратегии:

  • установка Settings в единой точке инициализации;
  • использование resetToDefault() после тестов;
  • минимизация динамических изменений во время выполнения;
  • явная передача параметров в DateTime вместо глобальных изменений.

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

Оглавление