Что такое Symbol в JavaScript?

Что такое Symbol

Symbol — один из семи примитивных типов JavaScript (наряду с string, number, bigint, boolean, null, undefined). Значение типа Symbol всегда уникально: два Symbol с одинаковым описанием никогда не равны друг другу.

const a = Symbol('id');
const b = Symbol('id');
console.log(a === b); // false

Создание Symbol

Symbol создаётся вызовом функции Symbol(). Вызывать её через new нельзя — это вызовет TypeError:

const sym = Symbol('описание');
console.log(typeof sym); // 'symbol'
console.log(sym.description); // 'описание'

Основные применения

Уникальные ключи свойств объекта

Symbol часто используют как ключи свойств, чтобы избежать конфликтов имён — особенно в библиотеках и фреймворках:

const ID = Symbol('id');
const user = {
  name: 'Иван',
  [ID]: 42
};
console.log(user[ID]); // 42
console.log(Object.keys(user)); // ['name'] — Symbol не виден

Свойства с ключами-Symbol не попадают в Object.keys(), Object.values(), JSON.stringify() и for...in. Получить их можно через Object.getOwnPropertySymbols() или Reflect.ownKeys().

Well-known Symbols

JavaScript использует встроенные Symbol для настройки поведения объектов:

class MyCollection {
  constructor(...items) {
    this.items = items;
  }
  // Делаем объект итерируемым
  [Symbol.iterator]() {
    let index = 0;
    const items = this.items;
    return {
      next() {
        return index < items.length
          ? { value: items[index++], done: false }
          : { done: true };
      }
    };
  }
}

const col = new MyCollection(1, 2, 3);
for (const item of col) {
  console.log(item); // 1, 2, 3
}

Другие well-known Symbols: Symbol.toPrimitive, Symbol.hasInstance, Symbol.toStringTag, Symbol.asyncIterator.

Symbol.for и Symbol.keyFor — глобальный реестр

Symbol.for(key) создаёт Symbol в глобальном реестре или возвращает существующий по тому же ключу:

const s1 = Symbol.for('app.token');
const s2 = Symbol.for('app.token');
console.log(s1 === s2); // true

console.log(Symbol.keyFor(s1)); // 'app.token'

Это удобно для обмена Symbol между модулями или iframe.

Важные особенности

• Symbol нельзя неявно привести к строке: 'prefix' + Symbol() бросит TypeError. Используйте .toString() или .description.
• Symbol не сериализуются в JSON.
• Symbol-свойства не копируются оператором spread и Object.assign() — только через Object.getOwnPropertySymbols().

Когда применять

• Создание «скрытых» или «полуприватных» полей объекта.
• Расширение сторонних объектов без риска конфликта имён.
• Реализация кастомного поведения через well-known Symbols.
• Константы, которые должны быть абсолютно уникальными.