symbol

A symbol is a primitive, immutable, and globally unique data type in TypeScript used to create anonymous object property keys. Introduced in ES6, symbols guarantee strict uniqueness; every invocation of the Symbol() function allocates a completely new value in memory, preventing property name collisions regardless of the execution context.

Instantiation and Syntax

Symbols are created using the Symbol() factory function. Because symbol is a primitive type, it cannot be instantiated with the new keyword.

const sym1: symbol = Symbol();
const sym2: symbol = Symbol("description"); // The string argument is purely for debugging

The fundamental mechanic of a symbol is its absolute uniqueness. Even if two symbols are initialized with the identical descriptive string, they are not strictly equal.

const symA: symbol = Symbol("key");
const symB: symbol = Symbol("key");

console.log(symA === symB); // false

TypeScript’s unique symbol Subtype

TypeScript introduces a nominal subtype of symbol called unique symbol. While symbol represents any symbol, unique symbol represents a specific, singular symbol tied to its declaration.

To type a variable as a unique symbol, it must be declared using const or as a readonly static property on a class.

// Valid: Tied to the specific declaration
const API_KEY: unique symbol = Symbol("api_key");

// Error: A variable whose type is a 'unique symbol' type must be 'const'.
let mutableKey: unique symbol = Symbol("mutable");

// Error: Type 'typeof API_KEY' is not assignable to type 'typeof OTHER_KEY'.
const OTHER_KEY: unique symbol = API_KEY; 

When using symbols as keys in interfaces or type aliases, TypeScript requires the symbol to be a unique symbol so the compiler can statically track the property.

const ID: unique symbol = Symbol("id");

interface Entity {
    [ID]: string;
    name: string;
}

const node: Entity = {
    [ID]: "uuid-1234",
    name: "ServerNode"
};

The Global Symbol Registry

TypeScript supports the global symbol registry, which allows symbols to be shared across different realms (e.g., iframes, service workers) using Symbol.for() and Symbol.keyFor().

• Symbol.for(key): Searches the global registry for a symbol with the given key. If found, it returns it; otherwise, it creates a new global symbol.
• Symbol.keyFor(sym): Retrieves the string key for a given global symbol.

const globalSym1: symbol = Symbol.for("app.config");
const globalSym2: symbol = Symbol.for("app.config");

console.log(globalSym1 === globalSym2); // true

const keyString: string | undefined = Symbol.keyFor(globalSym1); // "app.config"

Well-Known Symbols

TypeScript includes type definitions for “well-known symbols”—built-in symbols exposed as static properties on the Symbol constructor. These are used to implement or override internal language behaviors.

class IterableCollection {
    private items: number[] = [1, 2, 3];

    // Implements the well-known Symbol.iterator
    *[Symbol.iterator](): IterableIterator<number> {
        for (const item of this.items) {
            yield item;
        }
    }
}

Common well-known symbols include:

• Symbol.iterator: Defines the default iterator for an object.
• Symbol.toPrimitive: Converts an object to a corresponding primitive value.
• Symbol.toStringTag: Defines the default string description of an object.
• Symbol.hasInstance: Determines if a constructor object recognizes an object as its instance.

Master TypeScript with Deep Grasping Methodology!

Learn More