Read-only API views
Expose configuration or domain data without allowing callers to reassign its properties.
TypeScript · Type Alias
Readonly
Readonly<Type> creates a type whose properties cannot be reassigned by TypeScript. It is useful for describing frozen or otherwise read-only object views.
- Since
- 2.1
How it works
Readonly<Type> creates a mapped type whose properties correspond to Type but are marked readonly. TypeScript therefore rejects assignments to those properties, making the type useful for values such as frozen objects; this restriction applies during type-checking rather than enforcing runtime immutability.
Syntax
Readonly<Type>Parameters
| Name | Type | Description |
|---|---|---|
Type | Type | The source object type whose properties become readonly. |
Returns
A type with all properties of Type marked readonly.
Key points
- Readonly<T> preserves the input type's property set while changing each property to readonly.
- The resulting properties cannot receive new values through ordinary assignments accepted by the type checker.
- A generic freeze-style function can expose its input as Readonly<Type> in the return type.
- The utility is representable as a mapped type iterating over keyof T and retaining each property's value type.
Common mistakes
- Readonly<T> describes the type-level restriction; it does not itself freeze an object or guarantee runtime immutability.
Example: Prevent property reassignment
interface Todo {
title: string;
completed: boolean;
}
const todo: Readonly<Todo> = {
title: "Delete inactive users",
completed: false,
};
// TypeScript error: cannot assign to a readonly property.
todo.title = "Archive inactive users";Readonly<Todo> prevents assignments to Todo's properties during type-checking.
When to use it
Frozen-object signatures
Describe the return type of a generic helper that freezes an object.
Mutation-resistant references
Model an existing value whose fields should be treated as non-writable by consumers.
Interview questions
QWhat does Readonly<T> do?
Readonly<Type> constructs a type with every property of Type marked readonly. Assignments to those properties are rejected by the type checker.
Follow-up: How would you type a freezing helper? Use a generic signature such as function freeze<Type>(obj: Type): Readonly<Type>;.
QWhen is Readonly<T> useful?
It is useful when modeling an object whose properties cannot be reassigned, including the result type of a frozen-object helper. The restriction is represented statically by the readonly properties.
Follow-up: What does it not guarantee? It does not by itself perform the runtime operation that freezes the object.
QWhen was Readonly<T> introduced and how is it characterized?
The utility was released in TypeScript 2.1. Its behavior is expressed through a mapped type that applies readonly to each property in the input type.
Follow-up: What related array type should be considered? ReadonlyArray<T> is the dedicated type for arrays that should not be mutated.
Related
PartialRecordPickReadonlyArray