Tipos de objeto em TypeScript: propriedades opcionais e readonly

Um tipo de objeto em TypeScript lista as propriedades que um objeto tem e o tipo de cada uma: { name: string; age: number }. Adicione ? para tornar uma propriedade opcional e readonly para impedir que ela seja reatribuída. Escreva o tipo inline ou dê um nome a ele com type ou interface para reutilizar.

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

Escrevendo tipos de objeto

As propriedades são separadas por ; ou , (os dois funcionam, ; é o estilo mais comum), e uma quebra de linha sozinha também basta. Um tipo inline serve para um parâmetro isolado; para qualquer coisa usada duas vezes, dê um nome.

// 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 e interface descrevem formatos de objeto igualmente bem. As diferenças (declaration merging, unions) estão na página interface vs type.

Acessar uma propriedade que o tipo não declara é erro de compilação: point.z dá TS2339, Property 'z' does not exist on type '{ x: number; y: number; }'.

Propriedades opcionais

Um ? depois do nome permite omitir a propriedade. Ler uma propriedade opcional dá T | undefined, então o TypeScript obriga você a tratar o caso ausente antes de usá-la.

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

Chamar um método em uma propriedade opcional sem verificação é erro: p.nickname.toUpperCase() falha com TS18048, 'p.nickname' is possibly 'undefined'. Use optional chaining (p.nickname?.toUpperCase()) quando undefined for um resultado aceitável.

prop?: T e prop: T | undefined não são a mesma coisa. O primeiro permite que a chave esteja ausente; o segundo exige a chave, embora o valor possa ser 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 } {}

Propriedades readonly

readonly impede que uma propriedade seja reatribuída depois que o objeto é criado. É uma verificação só de tempo de compilação, e é rasa: um objeto ou array guardado em uma propriedade readonly ainda pode ser alterado por dentro.

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

A saída mostra os dois limites: o id mudou de verdade em tempo de execução (só o compilador sabia que era readonly), e o array interno foi modificado. Para um array readonly use readonly string[]; para tornar todas as propriedades readonly de uma vez, use Readonly<Order>.

Excess property checks

Quando você atribui um objeto literal diretamente a uma variável tipada ou o passa direto para um parâmetro tipado, o TypeScript rejeita qualquer propriedade que o tipo não declara. Propriedades extras em um literal novo quase sempre são erros de digitação.

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

O código é TS2561 porque o compilador encontrou um nome parecido; uma propriedade extra sem nome semelhante dá TS2353, Object literal may only specify known properties, and 'z' does not exist in type 'Point'. Sem essa verificação, o erro de digitação compilaria, color seria undefined e o programa desenharia em preto sem avisar. A verificação vale só para literais novos. Um objeto que já está em uma variável pode ter propriedades extras, porque a tipagem do TypeScript é estrutural: um valor se encaixa em um tipo quando tem pelo menos as propriedades exigidas.

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

Objetos aninhados e métodos

Tipos de objeto podem ser aninhados e podem descrever métodos com a sintaxe de método ou com uma propriedade de tipo função.

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

Para formatos profundos ou reutilizados, dê nome ao tipo interno (type Address = { ... }) e faça referência a ele, ou extraia-o do tipo externo com um indexed access, Company["address"], como fazem as últimas linhas.

object vs {} vs Object

Três tipos com nomes parecidos significam coisas diferentes:

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

{} não significa "um objeto vazio"; significa "não é null nem undefined". Para aceitar qualquer objeto com chaves desconhecidas, use Record<string, unknown>; para um mapa de chaves e valores, use uma index signature ou Record, como mostra a página de dicionário. Na maioria das vezes, um formato específico é melhor que qualquer um dos três.