Types objet en TypeScript : propriétés optionnelles et readonly

Un type objet TypeScript liste les propriétés d'un objet et le type de chacune : { name: string; age: number }. Ajoutez ? pour rendre une propriété optionnelle et readonly pour empêcher sa réassignation. Écrivez le type en ligne, ou nommez-le avec type ou interface pour le réutiliser.

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

Écrire des types objet

Les propriétés sont séparées par ; ou , (les deux fonctionnent, ; est le style habituel), et un retour à la ligne suffit à lui seul. Un type en ligne convient pour un paramètre ponctuel ; pour tout ce qui sert deux fois, donnez-lui un nom.

// 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 et interface décrivent aussi bien l'un que l'autre les formes d'objets. Leurs différences (fusion de déclarations, unions) sont présentées sur la page interface ou type.

Accéder à une propriété que le type ne déclare pas est une erreur de compilation : point.z donne TS2339, Property 'z' does not exist on type '{ x: number; y: number; }'.

Propriétés optionnelles

Un ? après le nom permet d'omettre la propriété. Lire une propriété optionnelle donne T | undefined, TypeScript vous oblige donc à traiter le cas où elle manque avant de l'utiliser.

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

Appeler une méthode sur une propriété optionnelle sans vérification est une erreur : p.nickname.toUpperCase() échoue avec TS18048, 'p.nickname' is possibly 'undefined'. Utilisez le chaînage optionnel (p.nickname?.toUpperCase()) quand undefined est un résultat acceptable.

prop?: T et prop: T | undefined ne sont pas équivalents. Le premier autorise l'absence de la clé ; le second exige la clé, même si sa valeur peut être 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 } {}

Propriétés readonly

readonly empêche la réassignation d'une propriété après la création de l'objet. C'est une vérification à la compilation uniquement, et elle est superficielle : un objet ou un tableau stocké dans une propriété readonly peut toujours être modifié de l'intérieur.

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

La sortie montre les deux limites : l'id a réellement changé à l'exécution (seul le compilateur savait qu'il était readonly), et le tableau intérieur a été modifié. Pour un tableau readonly, utilisez readonly string[] ; pour rendre toutes les propriétés readonly d'un coup, utilisez Readonly<Order>.

Vérification des propriétés en trop

Quand vous assignez un littéral objet directement à une variable typée ou le passez tel quel à un paramètre typé, TypeScript refuse toute propriété que le type ne déclare pas. Les propriétés supplémentaires dans un littéral frais sont presque toujours des fautes de frappe.

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

Le code est TS2561 parce que le compilateur a trouvé une correspondance proche ; une propriété en trop sans nom similaire donne TS2353, Object literal may only specify known properties, and 'z' does not exist in type 'Point'. Sans cette vérification, la faute de frappe compilerait, color vaudrait undefined, et le programme dessinerait en noir sans rien dire. La vérification ne s'applique qu'aux littéraux frais. Un objet qui se trouve déjà dans une variable peut porter des propriétés supplémentaires, car le typage de TypeScript est structurel : une valeur correspond à un type dès qu'elle possède au moins les propriétés requises.

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

Objets imbriqués et méthodes

Les types objet s'imbriquent, et ils peuvent décrire des méthodes soit avec la syntaxe de méthode, soit avec une propriété de type fonction.

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

Pour les formes profondes ou réutilisées, nommez le type intérieur (type Address = { ... }) et référencez-le, ou extrayez-le du type extérieur avec un accès indexé, Company["address"], comme le font les dernières lignes.

object, {} ou Object

Trois types se ressemblent et signifient des choses différentes :

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

{} ne signifie pas « un objet vide » ; il signifie « ni null ni undefined ». Pour accepter n'importe quel objet aux clés inconnues, utilisez Record<string, unknown> ; pour une table de clés et de valeurs, utilisez une signature d'index ou Record comme le montre la page dictionnaire. La plupart du temps, une forme précise vaut mieux que l'un de ces trois types.