Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Utility Types

TypeScript ReadonlyMap and ReadonlySet types

Reference for ReadonlyMap<K, V> and ReadonlySet<T> in TypeScript: read-only views of collections, which methods they expose, and how to return them safely.

ReadonlyMap<K, V> and ReadonlySet<T> are interfaces that expose only the reading half of Map and Set. You get get, has, size, forEach, iteration and the keys/values/entries methods. set, delete, add and clear are missing.

They solve a common API-design problem: a class owns a Map and wants to let callers look at it without letting them change it. Returning the collection typed as ReadonlyMap gives that guarantee at compile time and costs nothing at runtime, because the object is the very same Map.

TypeScript
class Registry {
  private items = new Map<string, number>();
  get view(): ReadonlyMap<string, number> {
    return this.items;
  }
}

Try it

TypeScript Expose a map without letting callers change it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript ReadonlySet as a parameter type

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

TypeScript
interface ReadonlyMap<K, V> {
  forEach(callbackfn: (value: V, key: K, map: ReadonlyMap<K, V>) => void, thisArg?: any): void;
  get(key: K): V | undefined;
  has(key: K): boolean;
  readonly size: number;
  // plus entries(), keys(), values() and [Symbol.iterator]() from the iterable lib
}

interface ReadonlySet<T> {
  forEach(callbackfn: (value: T, value2: T, set: ReadonlySet<T>) => void, thisArg?: any): void;
  has(value: T): boolean;
  readonly size: number;
  // plus entries(), keys(), values() and [Symbol.iterator]()
}
Name Description
K, V Key and value types of the map.
T Element type of the set.

Returns: a type, not a value. A regular Map<K, V> or Set<T> is assignable to the read-only interface automatically.

Edge cases:

  • The assignment is one-way: a ReadonlyMap cannot be passed where a Map is required.
  • Newer libraries (ES2025 and esnext) add set-algebra methods such as union and intersection to ReadonlySet; they are typed only when your lib includes them and the runtime must support them.
  • Values inside are not made read-only: ReadonlyMap<string, User> still lets callers change a User object.

Usage notes

  • Return ReadonlyMap or ReadonlySet from getters that expose internal state. Callers who need a private copy can do new Map(view).
  • As parameter types they widen what your function accepts: any Map, a ReadonlyMap, or your own class implementing the interface.
  • Nothing is enforced at runtime. A caller who casts (view as Map<string, number>) can still mutate; use a copy or a proxy if that matters.
  • There is no ReadonlyWeakMap; WeakMap has no iteration, so use the normal type.
  • Build immutable-looking data with new Map([...]) and keep only the read-only reference around.