Метод toJSON

Назначение метода toJSON

Метод toJSON() в объектах Luxon используется для преобразования экземпляра даты и времени в строку формата ISO 8601, пригодную для сериализации в JSON. Он является частью механизма интеграции с JSON.stringify, который автоматически вызывает этот метод, если он определён у объекта.

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

  • преобразование объекта DateTime в строку
  • сохранение временной зоны в ISO-формате
  • обеспечение совместимости с JSON-структурами

Поведение метода toJSON

В Luxon метод toJSON() для DateTime возвращает строку, эквивалентную результату toISO():

  • формат результата: YYYY-MM-DDTHH:mm:ss.sss±HH:mm или Z
  • если объект невалиден — возвращается null

Пример базового поведения:

import { DateTime } from "luxon";

const dt = DateTime.local(2026, 5, 23, 14, 30);
console.log(dt.toJSON());

Результат будет примерно таким:

2026-05-23T14:30:00.000+03:00

Взаимодействие с JSON.stringify

Ключевая особенность toJSON() заключается в его автоматическом вызове при сериализации объекта.

import { DateTime } from "luxon";

const obj = {
  createdAt: DateTime.local(2026, 5, 23, 14, 30)
};

console.log(JSON.stringify(obj));

Результат:

{"createdAt":"2026-05-23T14:30:00.000+03:00"}

Таким образом:

  • DateTime не сериализуется как сложный объект
  • вместо этого сохраняется строковое ISO-представление
  • структура JSON остаётся компактной и переносимой

Отличие toJSON от toISO

Хотя результаты методов часто совпадают, их назначение различается:

Метод Назначение Результат
toISO() явное получение ISO-строки строка ISO
toJSON() сериализация для JSON строка ISO или null

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

  • toJSON() — адаптер для JSON-экосистемы
  • toISO() — основной метод форматирования даты

Пример эквивалентности:

dt.toJSON() === dt.toISO();

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

Luxon сохраняет информацию о временной зоне в строке, если она присутствует в объекте DateTime.

import { DateTime } from "luxon";

const dt = DateTime.now().setZone("Europe/Moscow");
console.log(dt.toJSON());

Пример результата:

2026-05-23T14:30:00.000+03:00

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

  • сохраняется смещение +03:00
  • при UTC используется суффикс Z
  • информация о зоне не теряется при сериализации

UTC-представление

Если объект создан или преобразован в UTC, результат toJSON() будет содержать Z:

import { DateTime } from "luxon";

const dt = DateTime.utc(2026, 5, 23, 14, 30);
console.log(dt.toJSON());

Результат:

2026-05-23T14:30:00.000Z

Суффикс Z означает нулевое смещение относительно UTC.

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

Luxon строго отслеживает валидность DateTime. Если объект невалиден, toJSON() возвращает null.

import { DateTime } from "luxon";

const dt = DateTime.fromObject({ year: 99999 });
console.log(dt.isValid);      // false
console.log(dt.toJSON());     // null

Семантика:

  • предотвращает попадание мусорных значений в JSON
  • облегчает обработку ошибок на стороне API

Точность и дробные секунды

Метод сохраняет миллисекунды в итоговой строке:

import { DateTime } from "luxon";

const dt = DateTime.local(2026, 5, 23, 14, 30, 10, 123);
console.log(dt.toJSON());

Результат:

2026-05-23T14:30:10.123+03:00

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

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

Использование в сложных структурах данных

При работе с вложенными объектами toJSON() обеспечивает корректную сериализацию без дополнительных преобразований.

import { DateTime } from "luxon";

const event = {
  name: "Meeting",
  schedule: {
    start: DateTime.local(2026, 5, 23, 10, 0),
    end: DateTime.local(2026, 5, 23, 11, 0)
  }
};

console.log(JSON.stringify(event));

Результат:

{
  "name": "Meeting",
  "schedule": {
    "start": "2026-05-23T10:00:00.000+03:00",
    "end": "2026-05-23T11:00:00.000+03:00"
  }
}

Обратимость данных

Строка, полученная через toJSON(), может быть восстановлена обратно в DateTime через парсинг ISO:

import { DateTime } from "luxon";

const json = DateTime.local().toJSON();
const restored = DateTime.fromISO(json);

Свойства:

  • сохраняется момент времени
  • сохраняется смещение
  • теряется только объектная структура Luxon

Влияние настроек Luxon

На результат toJSON() влияют:

  • текущая временная зона объекта
  • наличие offset
  • источник создания (local, utc, fromISO, fromObject)

Не влияют напрямую:

  • глобальные настройки форматирования (они относятся к toFormat)
  • пользовательские локали

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

Метод toJSON() фактически делает DateTime совместимым с типичными сценариями:

  • REST API
  • GraphQL payloads
  • сохранение в NoSQL базы
  • передача через message queues

Основной принцип:

  • внутри приложения — объект DateTime
  • при сериализации — ISO-строка

Сравнение с обычным Date

Стандартный Date в JavaScript тоже имеет toJSON(), но Luxon расширяет поведение:

Тип Формат
Date UTC ISO строка
DateTime (Luxon) ISO строка с учётом зоны

Пример:

new Date().toJSON();
DateTime.local().toJSON();

Luxon даёт более контролируемый результат благодаря явной работе с временными зонами.

Особенности цепочек преобразований

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

const payload = JSON.stringify({
  created: DateTime.now()
});

Промежуточный механизм:

  • JSON.stringify вызывает toJSON
  • toJSON возвращает ISO-строку
  • строка попадает в JSON без дополнительных шагов

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

Если объект оборачивается или расширяется, toJSON() сохраняет приоритет при сериализации:

class Wrapper {
  constructor(dt) {
    this.dt = dt;
  }

  toJSON() {
    return this.dt.toJSON();
  }
}

Это позволяет:

  • контролировать формат вывода
  • сохранять совместимость с Luxon-логикой
  • интегрироваться в сложные модели данных
Оглавление