Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Utility Types

TypeScript ReadonlyArray<T> type

Reference for ReadonlyArray<T> and readonly T[] in TypeScript: which methods remain, assignability rules, readonly tuples, as const and common mistakes.

ReadonlyArray<T> is the array type with every mutating method removed. You can read elements, loop, map, filter, slice and concat, but push, pop, splice, sort, reverse, fill and index assignment are compile-time errors. readonly T[] is exactly the same type written as a modifier.

It is purely a compile-time promise: at runtime the value is still an ordinary array, and nothing stops untyped code from changing it. Use it for parameters that a function must not modify, for constants, and for data you share between modules.

TypeScript
function total(values: readonly number[]): number {
  return values.reduce((sum, v) => sum + v, 0);
}

Try it

TypeScript Accepting any array, promising not to 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 Readonly tuples and as const

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 ReadonlyArray<T> {
  readonly length: number;
  readonly [n: number]: T;
  // at, concat, entries, every, filter, find, findIndex, findLast, flat, flatMap,
  // forEach, includes, indexOf, join, keys, lastIndexOf, map, reduce, reduceRight,
  // slice, some, toLocaleString, toReversed, toSorted, toSpliced, toString, values, with ...
}
type A = ReadonlyArray<string>;
type B = readonly string[]; // same type
Name Description
T The element type.

Returns: a type whose instances can be read but not mutated through that reference.

Edge cases:

  • T[] is assignable to ReadonlyArray<T>, but not the other way round. The check protects callers who hand you a mutable array.
  • readonly applies only one level deep. readonly Point[] still lets you change point.x.
  • Readonly<T[]> and readonly T[] are equivalent; Readonly<T> on an array type produces the readonly array.
  • The copying methods toSorted, toReversed, toSpliced and with (ES2023) are available on it, and are the readonly-friendly replacements for sort, reverse, splice and index assignment.

Usage notes

  • Prefer readonly T[] for function parameters that you only read. It accepts both mutable and readonly arrays, which makes your API easier to call.
  • as const on an array literal produces a readonly tuple of literal types, a very common way to define a fixed list and derive a union from it with (typeof list)[number].
  • Copying out of a readonly array is fine: [...frozen] and frozen.slice() give a mutable T[].
  • Array.isArray(x) is declared as x is any[], which does not play well with readonly array types. Write your own type guard if you need to narrow unknown to readonly T[].
  • The type does not freeze anything. Use Object.freeze (which returns a readonly type) if you also want a runtime guarantee.
  • Variable declarations are separate: const stops reassigning the variable, readonly stops mutation through the array reference.