Tipi oggetto in TypeScript: proprietà opzionali e readonly

Un tipo oggetto in TypeScript elenca le proprietà di un oggetto e il tipo di ciascuna: { name: string; age: number }. Aggiungi ? per rendere opzionale una proprietà e readonly per impedire che venga riassegnata. Scrivi il tipo inline, oppure dagli un nome con type o interface per riutilizzarlo.

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

Scrivere tipi oggetto

Le proprietà si separano con ; o , (funzionano entrambi, ; è lo stile abituale), e basta anche un semplice a capo. Un tipo inline va bene per un parametro usato una volta sola; per qualsiasi cosa usata due volte, dagli un 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 descrivono le forme degli oggetti altrettanto bene. Le differenze (fusione delle dichiarazioni, unioni) sono spiegate nella pagina interface vs type.

Accedere a una proprietà che il tipo non dichiara è un errore di compilazione: point.z dà TS2339, Property 'z' does not exist on type '{ x: number; y: number; }'.

Proprietà opzionali

Un ? dopo il nome permette di omettere la proprietà. Leggere una proprietà opzionale dà T | undefined, quindi TypeScript ti obbliga a gestire il caso in cui manca prima di usarla.

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

Chiamare un metodo su una proprietà opzionale senza controllarla è un errore: p.nickname.toUpperCase() fallisce con TS18048, 'p.nickname' is possibly 'undefined'. Usa l'optional chaining (p.nickname?.toUpperCase()) quando undefined è un risultato accettabile.

prop?: T e prop: T | undefined non sono la stessa cosa. La prima permette che la chiave manchi; la seconda richiede la chiave, anche se il suo valore può essere 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 } {}

Proprietà readonly

readonly impedisce di riassegnare una proprietà dopo la creazione dell'oggetto. È solo un controllo in fase di compilazione, ed è superficiale: un oggetto o un array salvato in una proprietà readonly può ancora essere modificato al suo interno.

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

L'output mostra entrambi i limiti: l'id è cambiato davvero in fase di esecuzione (solo il compilatore sapeva che era readonly), e l'array interno è stato modificato. Per un array readonly usa readonly string[]; per rendere readonly tutte le proprietà in un colpo solo, usa Readonly<Order>.

Controllo delle proprietà in eccesso

Quando assegni un oggetto letterale direttamente a una variabile tipizzata o lo passi direttamente a un parametro tipizzato, TypeScript rifiuta ogni proprietà che il tipo non dichiara. Le proprietà in più in un letterale appena creato sono quasi sempre errori di battitura.

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

Il codice è TS2561 perché il compilatore ha trovato un nome simile; una proprietà in eccesso senza nomi simili dà TS2353, Object literal may only specify known properties, and 'z' does not exist in type 'Point'. Senza il controllo, l'errore di battitura compilerebbe, color sarebbe undefined e il programma disegnerebbe in nero senza avvisare. Il controllo vale solo per i letterali appena creati. Un oggetto che si trova già in una variabile può avere proprietà in più, perché la tipizzazione di TypeScript è strutturale: un valore è compatibile con un tipo quando ha almeno le proprietà obbligatorie.

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

Oggetti annidati e metodi

I tipi oggetto si possono annidare, e possono descrivere metodi sia con la sintassi dei metodi sia con una proprietà di tipo funzione.

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

Per forme profonde o riutilizzate, dai un nome al tipo interno (type Address = { ... }) e fai riferimento a quello, oppure estrailo dal tipo esterno con un accesso indicizzato, Company["address"], come fanno le ultime righe.

object vs {} vs Object

Tre tipi dal nome simile che significano cose diverse:

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

{} non significa "un oggetto vuoto"; significa "né null né undefined". Per accettare qualsiasi oggetto con chiavi sconosciute, usa Record<string, unknown>; per una mappa da chiavi a valori, usa una firma di indice o Record, come mostrato nella pagina sui dizionari. Nella maggior parte dei casi, una forma specifica è meglio di tutti e tre.