Interfaces en TypeScript: sintaxis, opcionales, métodos y ejemplos

Una interfaz pone nombre a la forma de un objeto: las propiedades que debe tener y el tipo de cada una. Una vez declarada, usas el nombre como tipo, y el compilador comprueba contra ella cada objeto que pasas, devuelves o asignas.

interface User {
  id: number;
  name: string;
  email?: string; // optional
}

function describe(user: User): string {
  return `#${user.id} ${user.name} <${user.email ?? "no email"}>`;
}

const ada: User = { id: 1, name: "Ada Lovelace", email: "ada@example.com" };

console.log(describe(ada));                       // #1 Ada Lovelace <ada@example.com>
console.log(describe({ id: 2, name: "Alan Turing" })); // #2 Alan Turing <no email>

// @ts-expect-error: Property 'name' is missing in type '{ id: number; }' but required in type 'User'.
describe({ id: 3 });

La última llamada es el error de compilación TS2741. Las interfaces se borran al compilar el código: la salida en JavaScript no tiene ni rastro de User, y nada comprueba la forma en tiempo de ejecución.

Declarar una interfaz

La sintaxis es la palabra clave interface, un nombre (en PascalCase por convención) y un cuerpo con los miembros. Los miembros se pueden separar con punto y coma, con comas o simplemente con saltos de línea; el punto y coma es el estilo habitual.

interface Product {
  sku: string;               // required property
  price: number;
  tags: string[];            // array property
  dimensions: {              // nested object type
    width: number;
    height: number;
  };
  discount?: number;         // optional property
  readonly createdAt: Date;  // cannot be reassigned
  label(): string;           // method
}

Una interfaz es un tipo, no un valor. No se puede instanciar con new, no tiene valores por defecto, y obj instanceof Product es el error TS2693 ('Product' only refers to a type, but is being used as a value here). Para comprobar una forma en tiempo de ejecución, escribe un type guard.

Tipado estructural y comprobación de propiedades de más

TypeScript compara formas, no nombres. Cualquier objeto con las propiedades requeridas encaja en la interfaz, se haya declarado con ella o no. Las propiedades de más están permitidas, con una excepción: un objeto literal escrito directamente donde se espera la interfaz pasa por una comprobación de propiedades de más, porque una clave desconocida ahí casi siempre es una errata.

interface Point {
  x: number;
  y: number;
}

function distance(p: Point): number {
  return Math.hypot(p.x, p.y);
}

const saved = { x: 3, y: 4, label: "A" }; // never declared as a Point
console.log(distance(saved));             // 5: the shape matches

// @ts-expect-error: Object literal may only specify known properties, and 'label' does not exist in type 'Point'.
distance({ x: 3, y: 4, label: "A" });

Ese error (TS2353) es el que detecta { id: 1, name: "a", emial: "x" } para un User: el compilador incluso sugiere Did you mean to write 'email'? (TS2561).

Propiedades opcionales y readonly

Un ? después del nombre hace opcional una propiedad: el objeto puede omitirla, y leerla da T | undefined. readonly prohíbe reasignar la propiedad después de crear el objeto.

interface Config {
  readonly apiUrl: string;
  readonly hosts: readonly string[];
  timeoutMs?: number;
}

const config: Config = { apiUrl: "https://api.example.com", hosts: ["a", "b"] };

// @ts-expect-error: Cannot assign to 'apiUrl' because it is a read-only property.
config.apiUrl = "http://localhost";
// @ts-expect-error: Property 'push' does not exist on type 'readonly string[]'.
config.hosts.push("c");

console.log(config.timeoutMs ?? 5000); // 5000: optional, so check or default it

const local = { ...config, apiUrl: "http://localhost" }; // a changed copy is fine
console.log(local.apiUrl); // http://localhost

// readonly is a compile-time rule attached to this type only:
const writable: { apiUrl: string } = config; // allowed
writable.apiUrl = "changed";
console.log(config.apiUrl); // changed

Aquí se ven dos límites. Primero, readonly es solo de tiempo de compilación: las dos líneas marcadas con @ts-expect-error se ejecutan igualmente al pulsar Run, y funcionan, y las últimas líneas cambian apiUrl a través de una referencia tipada sin readonly. Segundo, es superficial: readonly hosts: string[] impediría reasignar hosts pero seguiría permitiendo hosts.push(...), y por eso el propio array está tipado como readonly string[]. Documenta y hace cumplir la intención en el código tipado; no congela nada. El utility type Readonly<T> hace readonly de una vez todas las propiedades de una interfaz existente.

Métodos y propiedades de tipo función

Un método se puede escribir como firma de método, name(params): ReturnType, o como una propiedad que contiene una función, name: (params) => ReturnType. Quien los usa los llama igual.

interface Counter {
  count: number;
  increment(by?: number): void; // method signature
  reset: () => void;            // property holding a function
}

function createCounter(): Counter {
  return {
    count: 0,
    increment(by = 1) {
      this.count += by; // this is typed as Counter
    },
    reset() {
      this.count = 0;
    },
  };
}

const c = createCounter();
c.increment();
c.increment(5);
console.log(c.count); // 6
c.reset();
console.log(c.count); // 0

La diferencia es sutil: con strictFunctionTypes (parte de strict), los parámetros de las propiedades de tipo función se comprueban de forma estricta, mientras que las firmas de método se comprueban de forma más laxa (bivariante), así que la forma de propiedad detecta algunos errores más. La sintaxis de método es más corta y el estilo más habitual; las dos están bien.

Una interfaz también puede describir algo que se puede llamar o construir, con una firma de llamada o una firma de construcción:

interface Formatter {
  (value: number): string; // call signature: the object is a function
  locale: string;          // and it also has a property
}

interface PointConstructor {
  new (x: number, y: number): { x: number; y: number }; // construct signature
}

Firmas de índice

Cuando los nombres de las propiedades no se conocen de antemano, una firma de índice las describe todas a la vez: [key: string]: T significa «cualquier clave string, cada una con un T».

interface Scores {
  [player: string]: number;
}

const scores: Scores = { ada: 90, alan: 85 };
scores.grace = 95; // any string key is allowed
scores["linus"] = 70;

for (const [player, score] of Object.entries(scores)) {
  console.log(player, score);
}

const missing = scores.nobody; // typed number, actually undefined
console.log(missing);          // undefined

Las últimas líneas muestran la pega: leer una clave que no existe tiene tipo number, no number | undefined. La opción del compilador noUncheckedIndexedAccess añade | undefined a cada lectura de ese tipo.

Las propiedades con nombre pueden convivir con una firma de índice, pero tienen que encajar en ella. interface Dict { [key: string]: number; name: string } es el error TS2411, Property 'name' of type 'string' is not assignable to 'string' index type 'number'. Amplía el tipo del índice ([key: string]: number | string) o lleva la parte dinámica a su propia propiedad. Para mapas simples de clave y valor, Record<string, number> dice lo mismo en una línea.

Extender una interfaz

extends construye una interfaz nueva a partir de una o varias existentes. La hija tiene todos los miembros del padre más los suyos:

interface Animal {
  name: string;
}

interface Pet extends Animal {
  owner: string;
}

interface Trained {
  commands: string[];
}

interface ServiceDog extends Pet, Trained {
  certifiedUntil: Date;
}

// ServiceDog requires: name, owner, commands, certifiedUntil

Una hija solo puede volver a declarar una propiedad del padre con un tipo compatible (más estrecho), como kind: "dog" donde el padre dice kind: string. Las reglas, y cómo extender alias de tipo, están en la página de extends.

Implementar una interfaz en una clase

class X implements Shape le pide al compilador que compruebe que la clase tiene todo lo que exige la interfaz. Un miembro que falta es un error en la declaración de la clase:

// This does not compile: Circle is missing area()
interface Shape {
  name: string;
  area(): number;
}

class Circle implements Shape {
  name = "circle";
  constructor(public radius: number) {}
}

console.log(new Circle(2).name);

index.ts(7,7): error TS2420: Class 'Circle' incorrectly implements interface 'Shape'.
  Property 'area' is missing in type 'Circle' but required in type 'Shape'.

Con area() añadido, varias clases e incluso un objeto normal se pueden usar como Shape:

interface Shape {
  name: string;
  area(): number;
}

class Circle implements Shape {
  name = "circle";
  constructor(public radius: number) {}
  area() {
    return Math.PI * this.radius ** 2;
  }
}

class Rect implements Shape {
  name = "rect";
  constructor(public w: number, public h: number) {}
  area() {
    return this.w * this.h;
  }
}

// A plain object with the right shape is a Shape too: no class needed.
const unitSquare: Shape = { name: "unit square", area: () => 1 };

const shapes: Shape[] = [new Circle(1), new Rect(2, 3), unitSquare];
for (const s of shapes) {
  console.log(s.name, s.area().toFixed(2));
}

implements es solo una comprobación. No añade miembros a la clase, y no tipa por ti los parámetros de sus métodos: greet(name) {} dentro de una clase que implementa greet(name: string): string sigue siendo el error TS7006, Parameter 'name' implicitly has an 'any' type. Una clase puede implementar varias interfaces: class A implements B, C.

Fusión de declaraciones

Declarar dos veces una interfaz con el mismo nombre en el mismo ámbito fusiona las dos en una. Es algo que los alias de tipo no pueden hacer (un segundo type con el mismo nombre es un error de identificador duplicado).

interface Settings {
  theme: string;
}

interface Settings {
  fontSize: number;
}

// Settings now requires both properties
const s: Settings = { theme: "dark", fontSize: 14 };

En código de aplicación esto rara vez es lo que quieres, y una fusión accidental puede confundir. Su uso real es añadir miembros a tipos que no son tuyos: las opciones de una librería, o una global como Window. Desde dentro de un módulo, envuelve la declaración en declare global:

declare global {
  interface Window {
    analytics: { track(event: string): void };
  }
}

export {};

Después de esto, window.analytics.track("signup") pasa la comprobación de tipos en todo el proyecto. Los paquetes de definiciones de tipos se basan en el mismo mecanismo; consulta archivos de declaración.

Valores por defecto en las propiedades de una interfaz

Una interfaz no puede contener valores por defecto, porque describe tipos y se borra en tiempo de ejecución. size?: "sm" | "md" = "md" es el error TS1246, An interface property cannot have an initializer. Haz opcional la propiedad y rellena el valor por defecto donde se usa el objeto:

interface ButtonOptions {
  label: string;
  size?: "sm" | "md" | "lg";
  disabled?: boolean;
}

// 1. Destructuring defaults: applied when the value is undefined
function render({ label, size = "md", disabled = false }: ButtonOptions): string {
  return `[${label}] size=${size} disabled=${disabled}`;
}

// 2. Spread a defaults object under the options
const DEFAULTS = { size: "md", disabled: false } as const;

function withDefaults(options: ButtonOptions) {
  return { ...DEFAULTS, ...options };
}

console.log(render({ label: "Save" }));                   // [Save] size=md disabled=false
console.log(render({ label: "Save", size: undefined }));  // [Save] size=md disabled=false
console.log(withDefaults({ label: "Save", size: "lg" }));  // { size: 'lg', disabled: false, label: 'Save' }
console.log(withDefaults({ label: "Save", size: undefined }));
// { size: undefined, disabled: false, label: 'Save' }

Los valores por defecto en la desestructuración son la opción más segura: se aplican siempre que el valor es undefined, incluido un size: undefined explícito. La versión con expansión copia ese undefined explícito encima del valor por defecto, y su resultado sigue tipado como si size estuviera siempre asignado. Si necesitas esa garantía en los tipos, activa exactOptionalPropertyTypes, que convierte size: undefined en un error de compilación para un size?: ... opcional. Una clase con campos inicializados es la otra opción cuando el objeto también necesita comportamiento.

Interfaces genéricas

Una interfaz puede recibir parámetros de tipo, lo que hace que una sola declaración funcione con muchos tipos de contenido:

interface ApiResponse<T> {
  ok: boolean;
  data: T;
  error?: string;
}

interface Page<T> {
  items: T[];
  nextCursor?: string;
}

interface User {
  id: number;
  name: string;
}

const res: ApiResponse<Page<User>> = {
  ok: true,
  data: { items: [{ id: 1, name: "Ada" }], nextCursor: "abc" },
};

ApiResponse<Page<User>> se lee como «una respuesta cuyos datos son una página de usuarios». La librería estándar está llena de ellas: Array<T>, Promise<T> y Map<K, V> son todas interfaces genéricas.

Interfaz frente a alias de tipo

Un alias type puede describir la misma forma de objeto, y para tipos objeto simples los dos son intercambiables. Solo una interfaz se puede fusionar; solo un alias de tipo puede nombrar una unión, una tupla, o un mapped type o conditional type. La regla práctica del handbook de TypeScript es usar interface hasta que necesites algo que solo tiene type. La página de interface frente a type tiene la comparación completa, incluida la diferencia con Record<string, ...> que sorprende a casi todo el mundo.