Symbols in TypeScript

For what symbols are in the runtime language — uniqueness, registry, well-known symbols — see Symbols in JavaScript.

TypeScript adds static types on top of JavaScript symbols. The value rules are unchanged; the compiler tracks which symbol keys exist on an object and which types their values have.

Symbol-branded metadata on objects

String property names collide across libraries. A symbol key typed on the object documents an internal slot without showing up in Object.keys at runtime:

1
const logHandler = Symbol("logHandler");
2

3
type WithLog<T> = T & {
4
  [logHandler]?: (obj: T) => string;
5
};
6

7
function addLog<T extends object>(
8
  obj: T,
9
  func: (obj: T) => string,
10
): asserts obj is WithLog<T> {
11
  (obj as WithLog<T>)[logHandler] = func;
12
}
13

14
function doLog(message: string, obj: WithLog<{ src: string }>) {
15
  const objStr = obj[logHandler]?.(obj) ?? String(obj);
16
  console.log(`${message} ${objStr}`);
17
}

The consumer keeps using normal string keys on the same object. Only code that imports logHandler can read or write the logging function, which the type checker enforces when you export the symbol from one module.

Declaring symbol keys on interfaces

Bracket notation in a type lists a specific symbol (or a computed symbol type) as a member:

1
declare const id: unique symbol;
2

3
interface Entity {
4
  [id]: string;
5
  name: string;
6
}
7

8
const row: Entity = {
9
  [id]: "uuid-1",
10
  name: "Ada",
11
};

Use unique symbol for module-level constants so each declaration stays distinct in the type system. Symbol() inside a function returns a wider symbol type unless you narrow it.

keyof, spread, and enumeration

keyof on a type with both string and symbol keys includes both kinds. Control which keys you copy:

1
type StringKeys<T> = Extract<keyof T, string>;

Object.getOwnPropertySymbols is still the runtime API for symbol keys. TypeScript does not infer symbol keys from arbitrary object literals unless you annotate or satisfy an interface that declares them.

Well-known symbols in typings

Lib typings declare built-ins such as Symbol.iterator and Symbol.toStringTag. Implementing them on a class uses the same syntax as JavaScript; the compiler checks signatures against the official interface:

1
class Counter {
2
  private n = 0;
3

4
  [Symbol.iterator](): Iterator<number> {
5
    return {
6
      next: () =>
7
        this.n < 3
8
          ? { value: this.n++, done: false }
9
          : { value: undefined, done: true },
10
    };
11
  }
12
}

Practical defaults

• Export the symbol constant alongside helpers that read the slot so consumers share one typed key.
• Prefer unique symbol for module-scoped keys; use symbol when accepting any symbol from callers.
• Keep JSON-facing data on string keys; use symbol keys for in-memory protocols and decorators that should not serialize.