Symbol: уникальные ключи

Символ — примитивный тип, как число или строка. Создаётся вызовом Symbol(), и каждый вызов рождает новое значение, не равное никакому другому. Это единственное, что символ умеет, и вся его польза растёт отсюда.

Аргумент в скобках — описание, и оно нужно только человеку: попадает в отладочный вывод и в свойство description, но на сравнение не влияет никак. Это подпись на коробке, а не её содержимое — две коробки с одинаковой подписью остаются разными коробками.

const a = Symbol("id");
const b = Symbol("id");

console.log(a === b);
console.log(a.description);
console.log(typeof a);

Писать new Symbol() нельзя — будет ошибка. Символ не объект, конструктора у него нет, только функция-создатель.

const id = Symbol("id");

// "ключ: " + id здесь закомментировано: такая склейка бросает TypeError
console.log("ключ: " + String(id));
console.log("ключ: " + id.description);

Ключом свойства в JavaScript может быть строка или символ — третьего варианта нет. Символьный ключ пишут в квадратных скобках: и в литерале объекта, и при чтении. Точечная запись тут не сработает, потому что после точки идёт имя, а символ — это значение из переменной.

const id = Symbol("id");
const user = { name: "Аня", [id]: 7 };

console.log(user[id]);
console.log(user.name);
console.log(Object.keys(user));

Главное следствие — такой ключ невозможно занять дважды по неосторожности. Две библиотеки, обе решившие пометить ваш объект полем id, затрут работу друг друга и вы узнаете об этом из странного бага. Два символа с описанием "id" мирно живут рядом: они разные значения, а значит и разные ключи.

const libA = Symbol("id");
const libB = Symbol("id");
const order = { total: 500 };
order[libA] = "A-1";
order[libB] = "B-1";

console.log(order[libA], order[libB]);
console.log(Object.keys(order).length);

Свойства с символьными ключами не участвуют в обычном обходе объекта. for..in их не назовёт, Object.keys не вернёт, JSON.stringify не сериализует. Чужой код, который перебирает ваш объект, просто не узнает, что там что-то есть.

const secret = Symbol("secret");
const obj = { open: 1, [secret]: 2 };

for (const key in obj) console.log(key);
console.log(JSON.stringify(obj));
console.log(Object.getOwnPropertySymbols(obj).length);

«Невидимость» не абсолютная: часть операций символьные ключи всё же копирует и показывает. Полная картина умещается в шесть строк.

const tag = Symbol("tag");
const src = { a: 1, [tag]: 2 };
const copy = { ...src };

console.log(copy[tag]);
console.log(JSON.stringify(copy));

Несколько символов язык создал заранее и положил прямо в Symbol: Symbol.iterator, Symbol.toPrimitive, Symbol.toStringTag и другие. Это не секретные ключи, а точки подключения: в определённый момент движок сам заглядывает в объект по такому ключу и спрашивает, как с этим объектом поступить.

Самый частый — Symbol.iterator. Его вызывают for..of и спред .... Пока метода нет, объект перебрать нельзя; как только появился — можно, и никакой магии больше не требуется. Звёздочка перед именем ниже делает функцию генератором: такая функция отдаёт значения по одному, и каждое yield — очередное значение перебора. Для нашей цели этого достаточно: генератор здесь просто самый короткий способ написать итератор руками.

const range = {
  from: 1,
  to: 3,
  *[Symbol.iterator]() { for (let i = this.from; i <= this.to; i++) yield i; }
};

console.log([...range]);

По той же схеме Symbol.toPrimitive отвечает на вопрос «во что превратить объект, если его сложили или вставили в шаблон». Аргумент hint говорит, чего от объекта хотят: "number", "string" или "default".

const money = {
  amount: 100,
  [Symbol.toPrimitive](hint) { return hint === "string" ? "100 руб." : this.amount; }
};

console.log(+money);
console.log(`${money}`);

Сценарий первый — метка на чужом объекте. Вы получили данные из библиотеки или от сервера и хотите приписать к ним своё служебное поле так, чтобы оно не сломало сериализацию и не столкнулось с чужим именем. Второй — подключение к языку через системные символы. Третий — набор состояний, которые нельзя случайно сравнить со строкой: const LOADING = Symbol("loading") совпадёт только сам с собой.

Если одному и тому же символу нужно быть общим на весь код — есть глобальный реестр. Symbol.for("ключ") при первом вызове создаёт символ и запоминает, при следующих возвращает тот же самый, хоть из другого файла. Обычный Symbol() в реестр не попадает никогда.

const a = Symbol.for("app.id");
const b = Symbol.for("app.id");

console.log(a === b);
console.log(Symbol.keyFor(a));
console.log(Symbol.keyFor(Symbol("app.id")));

Символ прячет свойство от случайного взгляда, но не от того, кто ищет: Object.getOwnPropertySymbols вернёт всё. Это неконфликтность, а не приватность. Нужна настоящая — берите #поля класса.

И обратная сторона: для обычных полей своего же объекта символы не нужны. Данные, которые уходят в JSON, конфигурация, всё, что удобно читать глазами в отладчике, — там строковый ключ проще и честнее. Символ достают, когда есть настоящий риск столкновения имён или требуется договориться с самим языком.