Symbols ב-JavaScript: מפתחות ייחודיים, Symbol.iterator ו-Well-Known Symbols

Symbol הוא ערך שמובטח להיות ייחודי

Symbol הוא אחד מהטיפוסים הפרימיטיביים של JavaScript, לצד string, number, boolean, null, undefined ו-bigint. התכונה שמגדירה אותו פשוטה: כל symbol שיוצרים שונה מכל symbol אחר, לתמיד.

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

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

שני symbols, שניהם נוצרו בלי ארגומנטים, והם עדיין לא שווים. זה לא מקרה, זו כל המטרה. אי אפשר לזייף symbol, ליצור אחד מחדש בטעות או להתנגש ב-symbol של מישהו אחר.

אפשר להצמיד תיאור כדי לעזור בדיבוג. הוא לא משפיע על הזהות:

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

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

אותו תיאור, symbols שונים. התיאור הוא רק תווית בשביל בני אדם שקוראים לוגים.

למה הם קיימים: מפתחות בלי התנגשויות

הסיבה המרכזית לקיומם של symbols היא לאפשר לכם להוסיף מאפיינים לאובייקט בלי לדאוג שהמפתח שלכם יתנגש במפתח של מישהו אחר. מפתחות מסוג מחרוזת מתחרים במרחב שמות שטוח: אם שתי ספריות מחליטות לשמור metadata ב-obj.meta, הן דורסות זו את זו. מפתחות מסוג symbol לא מתחרים, כי לאף אחד אחר אין את ה-symbol שלכם.

const ID = Symbol("id");

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

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

הסוגריים המרובעים ב-[ID]: 42 הם תחביר של computed property: הם אומרים "השתמשו בערך של ID כמפתח". רק קוד שמחזיק את אותו symbol ID יכול לקרוא את המאפיין הזה או לדרוס אותו. כל מודול אחר שמשתמש במחרוזת "id" או ב-Symbol("id") משלו מדבר על משבצת אחרת לגמרי.

מפתחות Symbol מוסתרים (ברובם)

מאפיינים עם מפתח symbol לא מופיעים ב-for...in, ב-Object.keys או ב-JSON.stringify. הם לא סודיים, קוד נחוש עדיין יכול למצוא אותם, אבל הם לא מפריעים במעבר רגיל על האובייקט.

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 ו-JSON.stringify מדלגים לגמרי על מפתח ה-symbol. אם צריך למצוא מאפייני symbol בכוונה, Object.getOwnPropertySymbols ו-Reflect.ownKeys חושפים אותם. זו בדיוק ההתנהגות שרוצים עבור metadata: גלויה כשמחפשים אותה, בלתי נראית לקוד שרק עובר על מפתחות מסוג מחרוזת.

שיתוף Symbols עם Symbol.for

Symbol() נותן symbol מקומי וחד פעמי. לפעמים רוצים את ההפך: symbol שהוא אותו symbol בכל מקום בתוכנית, בין מודולים, כדי שחלקי קוד שונים יוכלו להסכים על מפתח. בשביל זה יש את 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) בודק ברישום גלובלי: אם כבר קיים symbol עבור המפתח הזה, מקבלים אותו בחזרה; אחרת הוא יוצר אחד ושומר אותו. Symbol.keyFor הולך בכיוון ההפוך: הוא מחזיר את המפתח שאיתו נוצר symbol רשום (או undefined עבור symbols שאינם רשומים).

ברוב המקרים, Symbol() רגיל הוא מה שאתם צריכים. לכו על Symbol.for כש-symbol באמת צריך להיות משותף מעבר לגבולות של מודול.

Well-Known Symbols: נקודות חיבור לשפה

כאן symbols מוכיחים את ערכם. JavaScript חושפת קבוצה של symbols מוגדרים מראש, ה-well-known symbols, שהשפה עצמה בודקת אם הם קיימים על האובייקטים שלכם. ממשו מתודה באחד מהמפתחות האלה, והאובייקט שלכם מתחבר ישירות ליכולת מובנית.

השימושי ביותר הוא Symbol.iterator. כל אובייקט שיש לו מתודה במפתח הזה הוא iterable: הוא עובד עם for...of, spread, destructuring ו-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 הוא לא מערך. זה אובייקט רגיל עם מתודה אחת במפתח מיוחד. אבל מכיוון שהמתודה הזו מחזירה iterator, גם for...of וגם spread עובדים עליו, בדיוק כמו שהם עובדים על מערכים, מחרוזות ו-Map. זה החוזה: ממשו את Symbol.iterator, והשפה מתייחסת אליכם כ-iterable.

Well-Known Symbols נוספים ששווה להכיר

יש עוד כמה, וכל אחד מהם הוא נקודת חיבור לחלק אחר של השפה:

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: הופך אובייקט ל-iterable.
• Symbol.asyncIterator: אותו דבר, אבל עבור for await...of.
• Symbol.toPrimitive: קובע איך אובייקט מומר לערך פרימיטיבי (number, string או ברירת מחדל) בהקשרים של המרת טיפוסים.
• Symbol.hasInstance: מתאים אישית מה instanceof מחזיר עבור המחלקה שלכם.
• Symbol.toStringTag: קובע את התגית שמוצגת ב-Object.prototype.toString.call(obj).

אין צורך לשנן אותם. מספיק לדעת שהם קיימים: כשתגיעו למצב שבו אתם רוצים שהאובייקט שלכם יתנהג כמו טיפוס מובנה, בדרך כלל יש well-known symbol בשביל זה.

Symbols הם לא מחרוזות

מלכודת נפוצה: symbols לא מומרים אוטומטית למחרוזות. שרשור של symbol זורק שגיאה, וכך גם העברה שלו ל-API שמצפה למחרוזת:

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()}`);

Template literals זורקים את אותו TypeError. השתמשו ב-String(symbol) או ב-symbol.toString() כשאתם באמת רוצים טקסט. הקצוות החדים האלה מכוונים: השפה מגינה עליכם מפני התייחסות בטעות לערך של זהות ייחודית כאל עוד פיסת טקסט.

מתי להשתמש ב-Symbols (ומתי לא)

השתמשו ב-symbols כאשר:

• אתם מצמידים metadata לאובייקטים שאינם שלכם, וצריכים מפתח שלא יתנגש.
• אתם מתכננים פרוטוקול: "אובייקטים שרוצים לעבוד עם הספרייה שלי צריכים לממש מתודה ב-symbol הזה".
• אתם רוצים מאפיין שלא ידלוף ל-JSON.stringify או ל-for...in.
• אתם מממשים את Symbol.iterator או well-known symbol אחר.

וותרו על symbols כאשר:

• אתם רק צריכים מפתח לאובייקט ואין סיכון להתנגשות. מחרוזת פשוטה יותר ומופיעה בלוגים כפי שהיא.
• אתם רוצים שדות "פרטיים". מאפיינים עם מפתח symbol לא באמת פרטיים, Object.getOwnPropertySymbols מוצא אותם. לפרטיות אמיתית, השתמשו בשדות מחלקה #private.
• אתם שומרים נתונים שצריכים לשרוד JSON.stringify. הם לא ישרדו.

רוב קוד ה-JavaScript מסתדר מצוין בלי לכתוב אי פעם Symbol(...) ישירות. אבל ברגע שאתם רוצים שהאובייקט שלכם יעבוד עם for...of או יתנהג באופן טבעי בהקשר של המרת טיפוסים, symbols הם הדלת למנגנון הזה.

הבא בתור: הצהרות על פונקציות

Symbols, iterators ו-generators נשענים כולם בכבדות על פונקציות: המתודות שנשמרות ב-Symbol.iterator, הפונקציות שמייצרות iterators, וה-generators שהצורה function* שלהם מסתירה את רוב הקוד החוזר. פונקציות הן הפרק הבא, ומתחילים בדרכים השונות להצהיר עליהן ובמה שמשתנה בין צורה לצורה.