Что такое…

Что такое Symbol в JavaScript — и почему JSON.stringify его не видит

Иллюстрация: связка обычных ключей и один полупрозрачный, который не попадает в коробку

Положи в объект поле с ключом-символом и отправь его на сервер:

const id = Symbol('id')
const user = { name: 'Аня', [id]: 42 }

JSON.stringify(user)   // '{"name":"Аня"}'
Object.keys(user)      // ['name']

Поле на месте — user[id] вернёт 42. Но JSON его не видит. Object.keys тоже. Это не баг. Это ровно то, ради чего символы придумали. Давай разберёмся, что это за штука и где ты её уже встречал, сам того не зная.

Что такое Symbol простыми словами

Symbol — это значение, которое гарантированно уникально. Каждый вызов Symbol() создаёт новое, ни на что не похожее:

Symbol('id') === Symbol('id')   // false

Строка в скобках — просто подпись для отладки. Она не делает символы равными. Две таблички «ключ от подвала» не превращают два разных ключа в один.

Главное применение — ключ свойства в объекте. Обычный ключ — строка. Любой код может случайно написать user.id и затереть твоё поле. Символьный ключ так не затрёшь. До него доберётся только тот, у кого в руках сам символ.

Ещё одна особенность: typeof Symbol() вернёт 'symbol'. Это отдельный примитивный тип, как строка или число. И new Symbol() не сработает — будет TypeError.

Почему его не видят JSON и Object.keys

Символьные ключи спрятаны от обычного перебора. Их пропускают:

  • JSON.stringify — поле просто исчезает из результата;
  • Object.keys, Object.values, Object.entries;
  • цикл for...in.

Зато они не пропали. Найти их можно специальными способами:

Object.getOwnPropertySymbols(user)   // [Symbol(id)]
Reflect.ownKeys(user)                // ['name', Symbol(id)]

И одна ловушка в обратную сторону. Spread ...user и Object.assign символьные ключи копируют. Скопировал объект — служебное поле поехало с ним. Отправил по сети — оно отвалилось.

Отсюда практичное правило. Символ хорош для служебной метки, которая не должна утечь в JSON. А вот для данных, которые ты сохраняешь или отправляешь, он не годится — они молча пропадут. Подробнее про устройство ключей — в статье про объекты.

Ошибка, на которой спотыкаются все

Символ не умеет сам превращаться в строку:

'Пользователь ' + id   // TypeError: Cannot convert a Symbol value to a string
`ключ: ${id}`          // та же ошибка

Число склеится. null склеится. Даже объект склеится в [object Object]. А символ — нет, падает сразу. Сделано специально: чтобы уникальный ключ случайно не превратился в обычную строку и не потерял уникальность.

Если тебе просто нужно его показать, есть два честных способа:

String(id)        // 'Symbol(id)'
id.description    // 'id'

Увидел в логе Cannot convert a Symbol value to a string — ищи место, где значение склеивается с текстом. Часто это console.log('...' + key) в цикле по Reflect.ownKeys.

Где ты уже пользуешься символами

Вот неожиданная часть. Ты работаешь с символами каждый день — просто встроенными.

for...of. Почему массив можно перебрать через for...of, а обычный объект нет? У массива есть метод с ключом Symbol.iterator. Цикл ищет именно его. У обычного объекта такого метода нет, отсюда ошибка TypeError: obj is not iterable. Подробнее про сами циклы — в статье про циклы.

React и защита от подделки. У каждого React-элемента есть служебное поле $$typeof. В нём лежит символ: Symbol.for('react.element'), а в React 19 — Symbol.for('react.transitional.element'). Зачем? JSON не умеет хранить символы. Значит, объект, пришедший с сервера как JSON, не может притвориться React-элементом. Если злоумышленник подсунет в данные «готовый элемент», React его просто не отрисует.

Другие «хорошо известные» символы. Symbol.asyncIterator работает в for await — им читают стриминговые ответы нейросетей. Symbol.toPrimitive решает, во что объект превратится в +obj. А Symbol.toStringTag отвечает за подпись в [object Map].

Symbol() или Symbol.for()

Иногда уникальность мешает. Например, один модуль ставит метку, а другой — из другой библиотеки или iframe — должен её узнать. Для этого есть глобальный реестр:

Symbol.for('app.id') === Symbol.for('app.id')   // true

Symbol.for ищет символ по имени. Нет такого — создаёт и запоминает. Именно так React узнаёт свои элементы, даже если на странице две копии библиотеки.

Короткое правило:

  • нужна метка, которую никто не повторит, — Symbol('…');
  • нужна метка, о которой договорились разные части кода, — Symbol.for('…'), и называй её с префиксом, как 'myapp.id'.

Нужно ли новичку писать свои символы?

Чаще всего нет. В обычном приложении хватает строковых ключей. Но понимать символы полезно: они объясняют for...of, $$typeof в React и странные ошибки при склейке строк.

Почему поле с символом пропало после сохранения?

Потому что JSON.stringify пропускает символьные ключи. То же самое с localStorage, fetch с JSON-телом и любой базой через JSON. Храни такие данные под строковым ключом.

Чем символ отличается от строки-ключа?

Строку 'id' может написать любой код и случайно затереть поле. Символ существует в одном экземпляре. Добраться до поля можно только через него, и в обычный перебор оно не попадает.

Стань ИИ-архитектором, а не просто читай об ИИ

Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →