Объектные типы TypeScript: опциональные и readonly-свойства

Объектный тип в TypeScript перечисляет свойства объекта и тип каждого из них: { name: string; age: number }. Добавьте ?, чтобы сделать свойство опциональным, и readonly, чтобы запретить его переприсваивание. Тип можно написать прямо на месте или дать ему имя через type или interface, чтобы переиспользовать.

// 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

Как записывать объектные типы

Свойства разделяются ; или , (работают оба, обычно пишут ;), и перевода строки тоже достаточно. Встроенный тип подходит для разового параметра; всё, что используется дважды, стоит назвать.

// 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 и interface одинаково хорошо описывают формы объектов. Различия (слияние объявлений, объединения) разобраны на странице interface и type.

Обращение к свойству, которого нет в типе, даёт ошибку компиляции: point.z выдаёт TS2339, Property 'z' does not exist on type '{ x: number; y: number; }'.

Опциональные свойства

? после имени позволяет не указывать свойство. Чтение опционального свойства даёт T | undefined, поэтому TypeScript заставляет обработать случай отсутствия, прежде чем использовать значение.

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

Вызов метода у опционального свойства без проверки даёт ошибку: p.nickname.toUpperCase() падает с TS18048, 'p.nickname' is possibly 'undefined'. Используйте опциональную цепочку (p.nickname?.toUpperCase()), когда результат undefined допустим.

prop?: T и prop: T | undefined это не одно и то же. Первое позволяет ключу отсутствовать; второе требует ключ, хотя его значение может быть 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-свойства

readonly запрещает переприсваивать свойство после создания объекта. Это проверка только времени компиляции, и она поверхностная: объект или массив, хранящийся в readonly-свойстве, всё равно можно менять изнутри.

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' }

Вывод показывает оба ограничения: id действительно изменился во время выполнения (о том, что он readonly, знал только компилятор), а массив внутри был изменён. Для readonly-массива используйте readonly string[]; чтобы сделать readonly сразу все свойства, используйте Readonly<Order>.

Проверка лишних свойств

Когда вы присваиваете объектный литерал напрямую типизированной переменной или передаёте его сразу в типизированный параметр, TypeScript отвергает любое свойство, которого нет в типе. Лишние свойства в свежем литерале почти всегда оказываются опечатками.

// 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'?

Код ошибки TS2561, потому что компилятор нашёл близкое совпадение; лишнее свойство без похожего имени даёт TS2353, Object literal may only specify known properties, and 'z' does not exist in type 'Point'. Без этой проверки опечатка скомпилировалась бы, color оказался бы undefined, и программа молча рисовала бы чёрным. Проверка работает только для свежих литералов. Объект, который уже лежит в переменной, может нести лишние свойства, потому что типизация в TypeScript структурная: значение подходит к типу, если у него есть как минимум обязательные свойства.

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

Вложенные объекты и методы

Объектные типы могут быть вложенными и описывать методы как через синтаксис методов, так и через свойство с функциональным типом.

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);

Для глубоких или переиспользуемых форм назовите внутренний тип (type Address = { ... }) и ссылайтесь на него, или извлеките его из внешнего типа индексированным доступом, Company["address"], как в последних строках.

object, {} и Object

Три типа звучат похоже, но означают разное:

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);

{} не означает «пустой объект»; он означает «не null и не undefined». Чтобы принимать любой объект с неизвестными ключами, используйте Record<string, unknown>; для отображения ключей на значения используйте индексную сигнатуру или Record, как показано на странице словарь. Чаще всего конкретная форма лучше любого из трёх.