TypeScript Object Type: Optional and Readonly Properties

A TypeScript object type lists the properties an object has and the type of each: { name: string; age: number }. Add ? to make a property optional and readonly to stop it from being reassigned. Write the type inline, or name it with type or interface to reuse it.

// Inline object type
let point: { x: number; y: number } = { x: 3, y: 4 };

// Named object type with optional and readonly properties
type User = {
    readonly id: number;
    name: string;
    email?: string; // optional: may be missing
};

const ada: User = { id: 1, name: "Ada" };
const grace: User = { id: 2, name: "Grace", email: "grace@example.com" };

console.log(point.x + point.y);           // 7
console.log(ada.email ?? "no email");      // no email
console.log(grace.email?.toUpperCase());   // GRACE@EXAMPLE.COM

Writing Object Types

Properties are separated by ; or , (both work, ; is the usual style), and a line break is enough on its own. An inline type is fine for a one-off parameter; for anything used twice, give it a name.

// Inline, in a parameter
function area(rect: { width: number; height: number }): number {
    return rect.width * rect.height;
}

// Named with a type alias
type Rect = { width: number; height: number };

// Named with an interface (the same shape)
interface RectShape {
    width: number;
    height: number;
}

type and interface describe object shapes equally well. The differences (declaration merging, unions) are covered on the interface vs type page.

Accessing a property the type does not declare is a compile error: point.z gives TS2339, Property 'z' does not exist on type '{ x: number; y: number; }'.

Optional Properties

A ? after the name lets the property be left out. Reading an optional property gives T | undefined, so TypeScript makes you handle the missing case before using it.

type Profile = {
    name: string;
    nickname?: string;
    age?: number;
};

function greet(p: Profile): string {
    // p.nickname is string | undefined
    const shown = p.nickname ?? p.name;         // default with ??
    const ageText = p.age !== undefined ? ` (${p.age})` : ""; // or check
    return `Hi, ${shown}${ageText}`;
}

console.log(greet({ name: "Ada" }));                        // Hi, Ada
console.log(greet({ name: "Grace", nickname: "Amazing Grace", age: 85 }));
console.log("age" in { name: "Ada" });                      // false

Calling a method on an optional property without a check is an error: p.nickname.toUpperCase() fails with TS18048, 'p.nickname' is possibly 'undefined'. Use optional chaining (p.nickname?.toUpperCase()) when undefined is an acceptable result.

prop?: T and prop: T | undefined are not the same. The first allows the key to be absent; the second requires the key, though its value may be undefined:

type A = { note?: string };
type B = { note: string | undefined };

const a1: A = {};                    // fine: key left out
const b1: B = { note: undefined };   // fine: key present
// @ts-expect-error: Property 'note' is missing in type '{}' but required in type 'B'.
const b2: B = {};

console.log(a1, b1, b2); // {} { note: undefined } {}

Readonly Properties

readonly stops reassignment of a property after the object is created. It is a compile-time check only, and it is shallow: an object or array stored in a readonly property can still be changed inside.

type Order = {
    readonly id: string;
    readonly items: string[];
    status: "open" | "paid";
};

const order: Order = { id: "A-17", items: ["tea"], status: "open" };

order.status = "paid"; // fine
// @ts-expect-error: Cannot assign to 'id' because it is a read-only property.
order.id = "B-2";
order.items.push("cake"); // allowed: readonly is shallow

console.log(order); // { id: 'B-2', items: [ 'tea', 'cake' ], status: 'paid' }

The output shows both limits: the id really changed at runtime (only the compiler knew it was readonly), and the array inside was modified. For a readonly array use readonly string[]; to make every property readonly at once, use Readonly<Order>.

Excess Property Checks

When you assign an object literal directly to a typed variable or pass it straight to a typed parameter, TypeScript rejects any property the type does not declare. Extra properties in a fresh literal are almost always typos.

// This does not compile: 'colour' is not a property of Options.
type Options = { color?: string; size?: number };

function draw(opts: Options) {
    console.log(opts.color ?? "black", opts.size ?? 1);
}

draw({ colour: "red", size: 2 });

index.ts(8,8): error TS2561: Object literal may only specify known properties, but 'colour' does not exist in type 'Options'. Did you mean to write 'color'?

The code is TS2561 because the compiler found a close match; an extra property with no similar name gives TS2353, Object literal may only specify known properties, and 'z' does not exist in type 'Point'. Without the check, the typo would compile, color would be undefined, and the program would silently draw in black. The check applies only to fresh literals. An object that already lives in a variable may carry extra properties, because TypeScript's typing is structural: a value fits a type when it has at least the required properties.

type Point = { x: number; y: number };

const point3d = { x: 1, y: 2, z: 3 };
const p: Point = point3d; // fine: point3d has x and y

function show(pt: Point) {
    console.log(pt.x, pt.y);
}
show(point3d); // 1 2

Nested Objects and Methods

Object types nest, and they can describe methods with either method syntax or a function-typed property.

type Company = {
    name: string;
    address: {
        city: string;
        zip?: string;
    };
    tags: string[];
    describe(): string;                  // method syntax
    rename: (newName: string) => void;   // function property
};

const acme: Company = {
    name: "Acme",
    address: { city: "Berlin" },
    tags: ["b2b"],
    describe() {
        return `${this.name} in ${this.address.city}`;
    },
    rename(newName) {
        this.name = newName;
    },
};

acme.rename("Acme GmbH");
console.log(acme.describe());               // Acme GmbH in Berlin
console.log(acme.address.zip ?? "no zip");  // no zip

type Address = Company["address"]; // reuse a nested type by indexing
const home: Address = { city: "Paris", zip: "75001" };
console.log(home);

For deep or reused shapes, name the inner type (type Address = { ... }) and reference it, or pull it out of the outer type with an indexed access, Company["address"], as the last lines do.

object vs {} vs Object

Three types sound alike and mean different things:

const a: object = { id: 1 };
const b: object = [1, 2];
const c: {} = 42;          // allowed: {} does not mean "empty object"
const d: {} = "text";      // allowed too

// @ts-expect-error: Type 'number' is not assignable to type 'object'.
const e: object = 42;

console.log(a, b, c, d, e);

{} does not mean "an empty object"; it means "not null or undefined". To accept any object with unknown keys, use Record<string, unknown>; for a map of keys to values, use an index signature or Record as shown on the dictionary page. Most of the time, a specific shape is better than any of the three.