Funciones en TypeScript: tipos de parámetros, retorno y void

Una función de TypeScript es una función de JavaScript con tipos en sus parámetros y, opcionalmente, en su valor de retorno. Cada parámetro lleva una anotación, el tipo de retorno va después de la lista de parámetros y el compilador comprueba cada llamada contra ambos.

function area(width: number, height: number): number {
  return width * height;
}

console.log(area(3, 4)); // 12

// @ts-expect-error: Argument of type 'string' is not assignable to parameter of type 'number'.
area("3", 4);

// @ts-expect-error: Expected 2 arguments, but got 1.
area(3);

Las dos llamadas incorrectas son errores en tiempo de compilación (TS2345 y TS2554). Los comentarios // @ts-expect-error le dicen al compilador que se espera un error en la línea siguiente, así que el resto del archivo se ejecuta igualmente. Quita uno de ellos y vuelve a ejecutar para ver el mensaje real.

Tipos de los parámetros

Cada parámetro se escribe name: Type. Con strict, que en TypeScript 7 está activado por defecto, un parámetro sin anotación y sin contexto del que inferir es un error: Parameter 'x' implicitly has an 'any' type. (TS7006). Así que en la práctica se anotan todos los parámetros de una función independiente.

Cualquier tipo sirve como tipo de parámetro: primitivos, arrays, tipos objeto, uniones, otras funciones.

type User = { name: string; tags: string[] };

function describe(user: User, maxTags: number): string {
  const shown = user.tags.slice(0, maxTags).join(", ");
  return `${user.name} (${shown})`;
}

function formatId(id: string | number): string {
  return typeof id === "number" ? id.toFixed(0).padStart(5, "0") : id.toUpperCase();
}

console.log(describe({ name: "Ada", tags: ["math", "code", "tea"] }, 2)); // Ada (math, code)
console.log(formatId(42));      // 00042
console.log(formatId("ab-7"));  // AB-7

TypeScript también comprueba el número de argumentos. Pasar más o menos de los que declara la función es un error, a diferencia de JavaScript normal, que rellena los que faltan con undefined e ignora los que sobran. Para hacer opcional un parámetro o darle un valor por defecto, consulta parámetros opcionales.

Tipos de retorno: anotar o inferir

El tipo de retorno va después del paréntesis de cierre: function f(): Type. Es opcional. Sin él, TypeScript infiere el tipo a partir de cada return del cuerpo.

// Inferred: (n: number) => "even" | "odd"
function parity(n: number) {
  return n % 2 === 0 ? "even" : "odd";
}

// Annotated: the contract is written down
function average(values: number[]): number {
  if (values.length === 0) return 0;
  const sum = values.reduce((acc, v) => acc + v, 0);
  return sum / values.length;
}

const p = parity(7);
console.log(p, average([2, 4, 9])); // odd 5

Una anotación vale la pena cuando la función se exporta, cuando tiene varios caminos de retorno o cuando es recursiva. El error aparece entonces dentro de la función, en el return equivocado, y no en quien la llama. Un caso clásico es una rama que se olvida de devolver:

// This does not compile: one path falls off the end of the function.
function grade(score: number): string {
  if (score >= 90) return "A";
  if (score >= 80) return "B";
}

console.log(grade(85));

El compilador informa index.ts(2,32): error TS2366: Function lacks ending return statement and return type does not include 'undefined'. Añade un return "C"; final y se ejecuta. Sin la anotación : string, la función compilaría con el tipo inferido "A" | "B" | undefined, y el problema pasaría a quien use el resultado.

void: funciones que no devuelven nada

Una función que solo hace algo (escribe en el log, guarda, modifica) tiene el tipo de retorno void. Es lo que infiere TypeScript cuando no hay ningún return con valor, y también puedes escribirlo de forma explícita.

function logLine(label: string, value: number): void {
  console.log(`${label.padEnd(8)}${value}`);
}

logLine("apples", 3);
logLine("pears", 12);

// A callback typed as returning void may return a value; it is ignored.
const lengths: number[] = [];
const push: (s: string) => void = (s) => lengths.push(s.length);
["a", "bcd"].forEach(push);
console.log(lengths); // [ 1, 3 ]

Estas reglas sobre void sorprenden:

La segunda fila es deliberada. Es la razón por la que arr.forEach(x => list.push(x)) compila aunque push devuelva un número. void en un tipo de función significa «devuelva lo que devuelva, nadie lo lee». Para una función que nunca termina (siempre lanza o no sale nunca de un bucle), el tipo de retorno es never.

Funciones flecha y expresiones de función

Las funciones flecha y las expresiones de función llevan las mismas anotaciones. El tipo de retorno va después de la lista de parámetros, antes de =>.

const double = (n: number): number => n * 2;

const toUpper = function (s: string): string {
  return s.toUpperCase();
};

// Returning an object literal from an arrow needs parentheses.
const point = (x: number, y: number) => ({ x, y });

console.log(double(21), toUpper("ok")); // 42 OK
console.log(point(1, 2));               // { x: 1, y: 2 }

Sin los paréntesis, (x, y) => { x, y } es un bloque sin return, y la función devuelve undefined. Las reglas de ejecución de las funciones flecha (sin this propio, sin arguments) son las mismas que en JavaScript; consulta funciones flecha en JavaScript.

Cuando una función se escribe en línea como argumento, normalmente no anotas sus parámetros. TypeScript sabe qué recibe el callback por la función a la que se pasa (tipado contextual): en [1, 2].map(n => n * 2), n ya es number. Cómo escribir el tipo de una función como valor, (n: number) => string, se explica en tipos de función.

Devolver varios valores

Una función devuelve un solo valor, así que devuelve un objeto o una tupla y desestructúralo.

function minMax(values: number[]): { min: number; max: number } {
  return { min: Math.min(...values), max: Math.max(...values) };
}

function splitName(full: string): [first: string, last: string] {
  const i = full.indexOf(" ");
  return [full.slice(0, i), full.slice(i + 1)];
}

const { min, max } = minMax([7, 2, 9]);
const [first, last] = splitName("Grace Hopper");
console.log(min, max, first, last); // 2 9 Grace Hopper

El tipo de retorno tupla necesita la anotación. Sin ella, [a, b] se infiere como string[]: la desestructuración sigue funcionando, pero el tipo ya no dice que haya exactamente dos elementos.

Funciones async

Una función async siempre devuelve una Promise. Anota el tipo de retorno como Promise<T>, donde T es lo que devuelve la función por dentro.

async function loadScore(id: number): Promise<number> {
  await new Promise((resolve) => setTimeout(resolve, 10));
  return id * 10;
}

async function main(): Promise<void> {
  const score = await loadScore(4); // score: number
  console.log("score", score);
}

main();

Escribir async function f(): number es un error: The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'? (TS1064).

El parámetro this

JavaScript decide this en el momento de la llamada. TypeScript te permite declarar qué debe ser this con un primer parámetro ficticio llamado this. Se elimina del JavaScript compilado y quien llama no lo pasa.

interface Counter {
  count: number;
}

function increment(this: Counter, by: number): void {
  this.count += by;
}

const c = { count: 0, increment };
c.increment(2); // fine: this is c

increment(2);
// error TS2684: The 'this' context of type 'void' is not assignable to method's 'this' of type 'Counter'.

Sin el parámetro this, this dentro de una función independiente es un any implícito y el modo strict informa 'this' implicitly has type 'any' because it does not have a type annotation. (TS2683). En los métodos de clase this ya tiene el tipo de la instancia, así que el parámetro es útil sobre todo para funciones independientes asignadas a objetos y para callbacks que las librerías llaman con un this concreto.