Symbol in JavaScript: chiavi uniche e Symbol.iterator

Un Symbol è un valore unico garantito

Symbol è uno dei tipi primitivi di JavaScript, insieme a string, number, boolean, null, undefined e bigint. La sua caratteristica principale è semplice: ogni symbol che crei è diverso da qualsiasi altro symbol, per sempre.

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

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

Due symbol, entrambi creati senza argomenti, eppure non sono uguali. Non è un caso: è proprio lo scopo. Non puoi falsificare un symbol, ricrearne uno per sbaglio o entrare in conflitto con quello di qualcun altro.

Puoi aggiungere una descrizione per facilitare il debug. Non cambia l'identità:

const x = Symbol("user id");
const y = Symbol("user id");

console.log(x === y);
console.log(x.description);
console.log(x.toString());

Stessa descrizione, symbol diversi. La descrizione è solo un'etichetta per chi legge i log.

Perché esistono: chiavi senza conflitti

Il motivo principale per cui esistono i symbol è permetterti di aggiungere proprietà a un oggetto senza preoccuparti che la tua chiave si scontri con quella di qualcun altro. Le chiavi stringa competono in un unico spazio dei nomi piatto: se due librerie decidono entrambe di salvare metadati in obj.meta, si pestano i piedi a vicenda. Le chiavi symbol non competono, perché nessun altro ha il tuo symbol.

const ID = Symbol("id");

const user = {
    name: "Rosa",
    [ID]: 42,
};

console.log(user.name);
console.log(user[ID]);
console.log(user["ID"]);

Le parentesi quadre in [ID]: 42 sono la sintassi delle proprietà calcolate: dicono "usa il valore di ID come chiave". Solo il codice che possiede lo stesso symbol ID può leggere o sovrascrivere quella proprietà. Qualsiasi altro modulo che usa la stringa "id" o il proprio Symbol("id") sta parlando di uno spazio completamente diverso.

Le chiavi symbol sono (quasi) nascoste

Le proprietà con chiave symbol non compaiono in for...in, Object.keys o JSON.stringify. Non sono segrete, perché un codice determinato può comunque trovarle, ma restano fuori dai piedi durante la normale iterazione.

const TAG = Symbol("tag");
const obj = { name: "Boris", age: 30, [TAG]: "internal" };

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

console.log(Object.getOwnPropertySymbols(obj));
console.log(Reflect.ownKeys(obj));

Object.keys e JSON.stringify ignorano del tutto la chiave symbol. Se vuoi trovare di proposito le proprietà symbol, Object.getOwnPropertySymbols e Reflect.ownKeys te le mostrano. È esattamente il comportamento che vuoi per i metadati: visibili quando li cerchi, invisibili al codice che scorre solo le chiavi stringa.

Condividere symbol con Symbol.for

Symbol() ti dà un symbol locale e usa e getta. A volte ti serve il contrario: un symbol che sia lo stesso in tutto il programma, tra moduli diversi, così che parti diverse del codice possano accordarsi su una chiave. È a questo che serve Symbol.for.

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

console.log(a === b);

const local = Symbol("app.user.id");
console.log(a === local);

console.log(Symbol.keyFor(a));

Symbol.for(key) controlla un registro globale: se esiste già un symbol per quella chiave, ti restituisce quello; altrimenti ne crea uno e lo salva. Symbol.keyFor fa il percorso inverso: restituisce la chiave con cui è stato creato un symbol registrato (oppure undefined per quelli non registrati).

Nella maggior parte dei casi ti basta il semplice Symbol(). Usa Symbol.for quando un symbol deve davvero essere condiviso oltre i confini di un modulo.

Well-known symbol: agganci al linguaggio

Ecco dove i symbol si guadagnano il posto. JavaScript espone una serie di symbol predefiniti, i cosiddetti well-known symbol, che il linguaggio stesso cerca nei tuoi oggetti. Implementa un metodo a una di queste chiavi e il tuo oggetto si collega direttamente a una funzionalità integrata.

Il più utile è Symbol.iterator. Qualsiasi oggetto che abbia un metodo a questa chiave è iterabile: funziona con for...of, lo spread, il destructuring e Array.from.

const range = {
    from: 1,
    to: 4,
    [Symbol.iterator]() {
        let current = this.from;
        const last = this.to;
        return {
            next() {
                return current <= last
                    ? { value: current++, done: false }
                    : { value: undefined, done: true };
            },
        };
    },
};

for (const n of range) console.log(n);
console.log([...range]);

range non è un array. È un semplice oggetto con un metodo dalla chiave speciale. Ma dato che quel metodo restituisce un iteratore, sia for...of sia lo spread funzionano su di esso, esattamente come funzionano su array, stringhe e Map. Il contratto è questo: implementa Symbol.iterator e il linguaggio ti tratta come iterabile.

Altri well-known symbol che vale la pena conoscere

Ce ne sono diversi altri, ognuno un aggancio a una parte diversa del linguaggio:

class Temperature {
    constructor(celsius) {
        this.celsius = celsius;
    }
    [Symbol.toPrimitive](hint) {
        if (hint === "number") return this.celsius;
        if (hint === "string") return `${this.celsius}°C`;
        return `${this.celsius}°C`;
    }
}

const t = new Temperature(22);
console.log(+t);
console.log(`It is ${t}`);
console.log(t + 5);

• Symbol.iterator: rende un oggetto iterabile.
• Symbol.asyncIterator: lo stesso, ma per for await...of.
• Symbol.toPrimitive: controlla come un oggetto viene convertito in primitivo (numero, stringa o default) nei contesti di coercizione.
• Symbol.hasInstance: personalizza cosa restituisce instanceof per la tua classe.
• Symbol.toStringTag: imposta l'etichetta mostrata da Object.prototype.toString.call(obj).

Non serve impararli a memoria. Basta sapere che esistono: quando ti capita di volere che il tuo oggetto si comporti come un tipo integrato, di solito c'è un well-known symbol apposta.

I symbol non sono stringhe

Un errore comune: i symbol non si convertono automaticamente in stringhe. Concatenarne uno lancia un errore, e lo stesso succede se lo passi a un'API che si aspetta una stringa:

const s = Symbol("oops");

try {
    const msg = "value is " + s;
} catch (err) {
    console.log(err.message);
}

console.log(`value is ${String(s)}`);
console.log(`value is ${s.toString()}`);

Anche i template literal lanciano lo stesso TypeError. Usa String(symbol) o symbol.toString() quando vuoi davvero del testo. Questi spigoli sono voluti: il linguaggio ti protegge dal trattare per sbaglio un valore di identità unica come un qualsiasi dato testuale.

Quando usare i symbol (e quando no)

Usa i symbol quando:

• Aggiungi metadati a oggetti che non controlli e ti serve una chiave che non entri in conflitto.
• Stai progettando un protocollo: "gli oggetti che vogliono funzionare con la mia libreria devono implementare un metodo a questo symbol."
• Vuoi una proprietà che non finisca in JSON.stringify o in for...in.
• Stai implementando Symbol.iterator o un altro well-known symbol.

Lascia perdere i symbol quando:

• Ti serve solo una chiave di oggetto e non c'è rischio di conflitti. Una stringa è più semplice e nei log appare così com'è.
• Vuoi campi "privati". Le proprietà con chiave symbol non sono davvero private: Object.getOwnPropertySymbols le trova. Per una vera privacy usa i campi di classe #private.
• Stai salvando dati che devono sopravvivere a JSON.stringify. Non sopravvivono.

La maggior parte del codice JavaScript se la cava benissimo senza mai scrivere Symbol(...) direttamente. Ma nel momento in cui vuoi che un tuo oggetto funzioni con for...of o si comporti in modo naturale in un contesto di coercizione, i symbol sono la porta d'ingresso a quei meccanismi.

Prossimo passo: la dichiarazione di funzioni

Symbol, iteratori e generatori si appoggiano molto sulle funzioni: i metodi salvati in Symbol.iterator, le factory che restituiscono iteratori, i generatori la cui forma function* nasconde gran parte del codice ripetitivo. Le funzioni sono il prossimo capitolo, a partire dai diversi modi di dichiararle e da cosa cambia tra una forma e l'altra.