toJSON() - преобразование даты в JSON-строку в JavaScript

toJSON() возвращает строку даты в формате, удобном для JSON. Для обычного объекта Date результат совпадает с toISOString(), то есть вы получаете строку по UTC.

Синтаксис

Базовая запись выглядит так:

date.toJSON()

Где:

date - это объект Date

У метода нет аргументов.

Что возвращает `toJSON()`

У toJSON() есть важный нюанс:

для валидной даты метод возвращает строку
для Invalid Date метод возвращает null

Пример с обычной датой:

const date = new Date(Date.UTC(2025, 0, 15, 11, 30, 45, 123));

console.log(typeof date.toJSON()); // "string"
console.log(date.toJSON()); // "2025-01-15T11:30:45.123Z"

Пример с невалидной датой:

const date = new Date("invalid");

console.log(date.toJSON()); // null

Это важное отличие от toISOString().

Простой пример

const date = new Date("2025-01-15T14:30:45.123+03:00");

console.log(date.toJSON()); // "2025-01-15T11:30:45.123Z"

Здесь объект даты был создан из строки с часовым поясом +03:00, но toJSON() вернул дату по UTC.

`toJSON()` у валидной даты работает по UTC

Это главный момент.

Для обычного объекта Date метод toJSON() возвращает строку в формате ISO 8601 по UTC.

const date = new Date("2025-01-15T14:30:45.123+03:00");

console.log(date.getHours()); // 14
console.log(date.getUTCHours()); // 11
console.log(date.toJSON()); // "2025-01-15T11:30:45.123Z"

Поэтому toJSON() удобно использовать, когда дату нужно сериализовать в стабильном и предсказуемом формате.

Для валидной даты `toJSON()` и `toISOString()` дают одинаковый результат

Это часто полезно знать заранее.

const date = new Date(Date.UTC(2025, 0, 15, 11, 30, 45, 123));

console.log(date.toJSON()); // "2025-01-15T11:30:45.123Z"
console.log(date.toISOString()); // "2025-01-15T11:30:45.123Z"
console.log(date.toJSON() === date.toISOString()); // true

Если дата валидна, результат у этих методов совпадает.

Но у `Invalid Date` поведение отличается от `toISOString()`

Это один из самых важных нюансов статьи.

toJSON() у Invalid Date возвращает null
toISOString() у Invalid Date выбрасывает RangeError

const date = new Date("invalid");

console.log(date.toJSON()); // null
// console.log(date.toISOString()); // RangeError

Если дата может оказаться невалидной, toJSON() ведёт себя мягче.

`JSON.stringify()` вызывает `toJSON()` автоматически

Это основной практический сценарий.

Когда объект Date попадает в JSON.stringify(), JavaScript обычно вызывает toJSON() сам.

const date = new Date(Date.UTC(2025, 0, 15, 11, 30, 45, 123));

console.log(JSON.stringify(date));
// "\"2025-01-15T11:30:45.123Z\""

Если дата лежит внутри объекта, в JSON попадёт строка:

const payload = {
  createdAt: new Date(Date.UTC(2025, 0, 15, 11, 30, 45, 123)),
};

console.log(JSON.stringify(payload));
// '{"createdAt":"2025-01-15T11:30:45.123Z"}'

Именно поэтому даты в JSON обычно становятся строками, а не сохраняются как объекты Date.

`Invalid Date` в JSON превращается в `null`

Это тоже связано с автоматическим вызовом toJSON().

const payload = {
  createdAt: new Date("invalid"),
};

console.log(payload.createdAt.toJSON()); // null
console.log(JSON.stringify(payload)); // '{"createdAt":null}'

Если сериализовать невалидную дату напрямую, результат тоже будет null.

const date = new Date("invalid");

console.log(JSON.stringify(date)); // "null"

`toJSON()` не меняет исходную дату

Метод только возвращает строку или null, но сам объект Date не изменяет.

const date = new Date(Date.UTC(2025, 0, 15, 11, 30, 45, 123));
const before = date.getTime();
const jsonDate = date.toJSON();

console.log(jsonDate); // "2025-01-15T11:30:45.123Z"
console.log(date.getTime() === before); // true

Это метод чтения, а не изменения даты.

Чем `toJSON()` отличается от `JSON.stringify()`

Эти вещи легко перепутать, но это не одно и то же.

toJSON() возвращает строку даты или null
JSON.stringify() превращает всё значение в JSON-строку

const date = new Date(Date.UTC(2025, 0, 15, 11, 30, 45, 123));

console.log(date.toJSON()); // "2025-01-15T11:30:45.123Z"
console.log(JSON.stringify(date)); // "\"2025-01-15T11:30:45.123Z\""

В первом случае вы получаете обычную строку JavaScript. Во втором - JSON-строку, поэтому там видны дополнительные кавычки.

Чем `toJSON()` отличается от `toString()`

Разница здесь такая:

toJSON() возвращает дату в формате, удобном для JSON и работы по UTC
toString() возвращает строку в локальном часовом поясе пользователя

const date = new Date(Date.UTC(2025, 0, 15, 11, 30, 45, 123));

console.log(date.toJSON()); // "2025-01-15T11:30:45.123Z"
console.log(date.toString()); // локальная строка с часовым поясом

Если дата нужна именно для сериализации, обычно подходит toJSON(), а не toString().

Когда это полезно

toJSON() особенно удобен, когда:

дата должна попасть в JSON.stringify()
вы хотите вручную получить строку даты для JSON
нужен единый формат времени по UTC
важно, чтобы невалидная дата возвращала null, а не ошибку

Пример:

const user = {
  name: "Анна",
  registeredAt: new Date("2025-01-15T14:30:45.123+03:00").toJSON(),
};

console.log(user);

Частые ошибки

Думать, что `toJSON()` возвращает объект

const date = new Date(Date.UTC(2025, 0, 15, 11, 30, 45, 123));

console.log(typeof date.toJSON()); // "string"

Для валидной даты результатом будет строка, а не объект Date.

Путать `toJSON()` и `JSON.stringify()`

const date = new Date(Date.UTC(2025, 0, 15, 11, 30, 45, 123));

console.log(date.toJSON()); // "2025-01-15T11:30:45.123Z"
console.log(JSON.stringify(date)); // "\"2025-01-15T11:30:45.123Z\""

toJSON() возвращает значение для сериализации, а JSON.stringify() уже строит итоговую JSON-строку.

Ожидать ошибку у `Invalid Date`, как у `toISOString()`

const date = new Date("invalid");

console.log(date.toJSON()); // null

toJSON() не выбрасывает RangeError для невалидной даты, а возвращает null.

Думать, что `toJSON()` использует локальное время

const date = new Date("2025-01-15T14:30:45.123+03:00");

console.log(date.toJSON()); // "2025-01-15T11:30:45.123Z"

Для обычного объекта Date результат будет по UTC.

Ожидать, что после `JSON.parse()` получится объект `Date`

const json = JSON.stringify({
  createdAt: new Date(Date.UTC(2025, 0, 15, 11, 30, 45, 123)),
});

const data = JSON.parse(json);

console.log(typeof data.createdAt); // "string"

После разбора JSON вы получаете строку, а не готовый объект Date.

Быстрая памятка

toJSON() вызывается у объекта Date
метод не принимает аргументы
у валидной даты результатом будет строка
у Invalid Date результатом будет null
для валидной даты результат совпадает с toISOString()
строка записывается по UTC
JSON.stringify() обычно вызывает toJSON() автоматически
метод не изменяет исходный объект Date
после JSON.parse() дата остаётся строкой, пока вы не создадите новый Date

Коротко

toJSON() в JavaScript нужен, чтобы превратить дату в строку, удобную для JSON. Главное, что стоит запомнить: для валидной даты метод возвращает ISO-строку по UTC, для Invalid Date возвращает null, не меняет исходный объект и часто вызывается автоматически внутри JSON.stringify().

toJSON() - преобразование даты в JSON-строку в JavaScript

Синтаксис

Что возвращает toJSON()

Простой пример

toJSON() у валидной даты работает по UTC

Для валидной даты toJSON() и toISOString() дают одинаковый результат

Но у Invalid Date поведение отличается от toISOString()

JSON.stringify() вызывает toJSON() автоматически

Invalid Date в JSON превращается в null

toJSON() не меняет исходную дату

Чем toJSON() отличается от JSON.stringify()

Чем toJSON() отличается от toString()