Codectionary / Developer documentation / TypeScript

Symbol Index Signatures

A symbol index signature describes values stored under arbitrary symbol keys.

What it is and why to use it

A symbol index signature describes values stored under arbitrary symbol keys. Unlike a single unique-symbol property, it permits many symbols while applying one value type to them. This is useful for an extensible metadata container whose keys should not overlap string fields.

Common mistakes and limitations

An index signature describes allowed values, not proof that every possible key exists. Object.keys does not enumerate symbols. This syntax is supported from TypeScript 4.4, and the examples here use the later 5.8 baseline.

Run this example

Use TypeScript 5.8 or later with strict checking and an ES2022 target. Save each complete example independently as example.ts, compile it, then run the generated JavaScript with a compatible Node.js installation. Compiler-only options below affect checking; they do not add runtime validation.

Terminal — compile and run

npx tsc example.ts --strict --target ES2022 --module commonjs
node example.js

Syntax

interface Metadata { [key: symbol]: string }

Examples

Symbol Index Signatures

Standalone TypeScript 5.8+ example; expected output is explained below.

interface Metadata { [key: symbol]: string }
const note = Symbol("note");
const owner = Symbol("owner");
const metadata: Metadata = { [note]: "Reviewed", [owner]: "John" };
console.log(metadata[note] ?? "Missing");
console.log(Object.getOwnPropertySymbols(metadata).length);
  1. The index signature requires string values for symbol-named entries.
  2. note and owner are two different runtime symbols.
  3. Symbol-aware enumeration finds both keys. The fallback handles a potentially missing lookup when noUncheckedIndexedAccess is enabled.
  4. Expected output: Reviewed 2

Best practices

  • An index signature describes allowed values, not proof that every possible key exists. Object.keys does not enumerate symbols. This syntax is supported from TypeScript 4.4, and the examples here use the later 5.8 baseline.
  • Keep external-input validation separate from compile-time type descriptions.

Runtime & versions

Compiled to JavaScript. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

TypeScript Handbook

Specifications & further reading