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.
function total(values: readonly number[]): number { return values.reduce((sum, v) => sum + v, 0); }
Try 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.
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
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 toReadonlyArray<T>, but not the other way round. The check protects callers who hand you a mutable array.readonlyapplies only one level deep.readonly Point[]still lets you changepoint.x.Readonly<T[]>andreadonly T[]are equivalent;Readonly<T>on an array type produces the readonly array.- The copying methods
toSorted,toReversed,toSplicedandwith(ES2023) are available on it, and are the readonly-friendly replacements forsort,reverse,spliceand 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 conston 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]andfrozen.slice()give a mutableT[]. Array.isArray(x)is declared asx is any[], which does not play well with readonly array types. Write your own type guard if you need to narrowunknowntoreadonly 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:
conststops reassigning the variable,readonlystops mutation through the array reference.