Tipos objeto en TypeScript: propiedades opcionales y readonly

Un tipo objeto en TypeScript enumera las propiedades que tiene un objeto y el tipo de cada una: { name: string; age: number }. Añade ? para hacer opcional una propiedad y readonly para impedir que se reasigne. Escribe el tipo en línea o ponle nombre con type o interface para reutilizarlo.

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

Cómo escribir tipos objeto

Las propiedades se separan con ; o , (las dos formas funcionan, ; es el estilo habitual), y un salto de línea basta por sí solo. Un tipo en línea vale para un parámetro puntual; para cualquier cosa que uses dos veces, ponle nombre.

// 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 describen formas de objeto igual de bien. Las diferencias (fusión de declaraciones, uniones) se explican en la página de interface frente a type.

Acceder a una propiedad que el tipo no declara es un error de compilación: point.z da TS2339, Property 'z' does not exist on type '{ x: number; y: number; }'.

Propiedades opcionales

Un ? después del nombre permite omitir la propiedad. Leer una propiedad opcional da T | undefined, así que TypeScript te obliga a manejar el caso en que falta antes de 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

Llamar a un método de una propiedad opcional sin comprobarla es un error: p.nickname.toUpperCase() falla con TS18048, 'p.nickname' is possibly 'undefined'. Usa el encadenamiento opcional (p.nickname?.toUpperCase()) cuando undefined sea un resultado aceptable.

prop?: T y prop: T | undefined no son lo mismo. La primera permite que la clave no exista; la segunda exige la clave, aunque su valor puede 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 } {}

Propiedades readonly

readonly impide reasignar una propiedad después de crear el objeto. Es solo una comprobación en tiempo de compilación, y es superficial: un objeto o array guardado en una propiedad readonly se puede seguir cambiando 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' }

La salida muestra los dos límites: el id cambió de verdad en tiempo de ejecución (solo el compilador sabía que era readonly), y el array de dentro se modificó. Para un array readonly usa readonly string[]; para hacer readonly todas las propiedades a la vez, usa Readonly<Order>.

Comprobación de propiedades de más

Cuando asignas un objeto literal directamente a una variable tipada o lo pasas directamente a un parámetro tipado, TypeScript rechaza cualquier propiedad que el tipo no declare. Las propiedades de más en un literal recién creado son casi siempre erratas.

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

El código es TS2561 porque el compilador encontró un nombre parecido; una propiedad de más sin ningún nombre similar da TS2353, Object literal may only specify known properties, and 'z' does not exist in type 'Point'. Sin la comprobación, la errata compilaría, color sería undefined y el programa dibujaría en negro sin avisar. La comprobación solo se aplica a literales recién creados. Un objeto que ya está en una variable puede llevar propiedades de más, porque el tipado de TypeScript es estructural: un valor encaja en un tipo cuando tiene al menos las propiedades obligatorias.

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 anidados y métodos

Los tipos objeto se anidan, y pueden describir métodos tanto con sintaxis de método como con una propiedad de tipo función.

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 formas profundas o reutilizadas, pon nombre al tipo interior (type Address = { ... }) y haz referencia a él, o sácalo del tipo exterior con un acceso indexado, Company["address"], como hacen las últimas líneas.

object frente a {} y Object

Tres tipos que suenan parecido y significan cosas distintas:

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

{} no significa «un objeto vacío»; significa «ni null ni undefined». Para aceptar cualquier objeto con claves desconocidas, usa Record<string, unknown>; para un mapa de claves a valores, usa una firma de índice o Record, como se muestra en la página de diccionarios. La mayoría de las veces, una forma concreta es mejor que cualquiera de los tres.