TypeScript Reference ยท Literal and Object Types
TypeScript object types and property modifiers
Reference for object types in TypeScript: inline shapes, nested objects, optional and readonly modifiers, structural typing and excess property checks.
An object type describes the shape of a value: which property names it has and what type each property holds. You can write one inline wherever a type is expected, give it a name with a type alias, or declare it with an interface. All three produce the same kind of structural type.
TypeScript compares objects by shape, not by name. Any value that has at least the required properties with compatible types is accepted, whatever class or literal it came from. The one exception is a fresh object literal assigned directly to a typed target, where extra properties are reported as errors.
let point: { x: number; y: number } = { x: 1, y: 2 };
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
{ name: string; age: number } // separators: ; or , or newline
{ id: number, label?: string } // optional property
{ readonly id: number } // readonly property
{ [key: string]: unknown } // index signature
{ (x: number): string } // call signature
{ method(): void; arrow: () => void } // methods
{} // any non-nullish value
| Part | Description |
|---|---|
name: Type |
A required property. Names can be identifiers, string literals ("data-id": string), numbers or computed unique symbols. |
name?: Type |
Optional property; its type includes undefined. |
readonly name: Type |
Cannot be assigned after creation (compile-time only). |
[key: string]: Type |
An index signature for arbitrary keys. |
Returns/edge cases: reading a property that is not in the type is error 2339. Assigning an object literal with an unknown property is error 2353 (excess property). The type {} accepts everything except null and undefined, including numbers and strings; object is the type for non-primitive values only.
Usage notes
- Use
interfacewhen you want to extend or merge declarations; usetypewhen you need unions, tuples or mapped types. For plain object shapes, the two are interchangeable. - The "Excess property check" example fails on purpose and prints the real error.
- Excess property checks apply only to fresh object literals. Passing the same object through a variable skips the check, as
extrashows above. - Optional properties and
T | undefinedare different underexactOptionalPropertyTypes: the former can be absent, the latter must be present. - Nested objects are checked deeply on assignment, but
readonlyis shallow:readonly list: string[]still allowslist.push. - Methods declared with method syntax are checked bivariantly, while function-typed properties (
arrow: () => void) are checked strictly understrictFunctionTypes. - Intersections combine shapes:
{ a: 1 } & { b: 2 }requires both properties. Object.keysreturnsstring[], not(keyof T)[], because an object may have more keys than its type shows.- Anonymous inline shapes repeated in many places are hard to maintain; give shared shapes a name.