Funções em TypeScript: tipos de parâmetro, retorno e void

Uma função TypeScript é uma função JavaScript com tipos nos parâmetros e, opcionalmente, no valor de retorno. Cada parâmetro recebe uma anotação, o tipo de retorno vai depois da lista de parâmetros, e o compilador verifica cada chamada contra os dois.

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

As duas chamadas erradas são erros de compilação (TS2345 e TS2554). Os comentários // @ts-expect-error dizem ao compilador que um erro é esperado na linha seguinte, então o resto do arquivo continua rodando. Remova um deles e rode de novo para ver a mensagem real.

Tipos de parâmetro

Cada parâmetro é escrito name: Type. Com strict, que vem ligado por padrão no TypeScript 7, um parâmetro sem anotação e sem contexto para inferir é um erro: Parameter 'x' implicitly has an 'any' type. (TS7006). Então, na prática, todo parâmetro de uma função avulsa é anotado.

Qualquer tipo serve como tipo de parâmetro: primitivos, arrays, tipos de objeto, unions, outras funções.

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

O TypeScript também verifica o número de argumentos. Passar mais ou menos do que a função declara é um erro, diferente do JavaScript puro, que preenche os que faltam com undefined e ignora os extras. Para tornar um parâmetro opcional ou dar a ele um valor padrão, veja parâmetros opcionais.

Tipos de retorno: anotar ou inferir

O tipo de retorno vem depois do parêntese de fechamento: function f(): Type. Ele é opcional. Sem ele, o TypeScript infere o tipo a partir de cada return do corpo.

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

Uma anotação vale a pena quando a função é exportada, quando tem vários caminhos de retorno ou quando é recursiva. O erro então aparece dentro da função, no return errado, e não em quem chama. Um caso clássico é um ramo que esquece de retornar:

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

O compilador mostra index.ts(2,32): error TS2366: Function lacks ending return statement and return type does not include 'undefined'. Adicione um return "C"; no final e ele roda. Sem a anotação : string, a função compilaria com o tipo inferido "A" | "B" | undefined, e o problema passaria para quem usa o resultado.

void: funções que não retornam nada

Uma função que só faz algo (imprime no log, grava, altera dados) tem o tipo de retorno void. É o que o TypeScript infere quando não há return com valor, e você pode escrevê-lo explicitamente.

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 regras sobre void surpreendem as pessoas:

A segunda linha é proposital. É por isso que arr.forEach(x => list.push(x)) compila, mesmo que push retorne um número. void em um tipo de função significa "seja o que for que isto retorne, ninguém lê". Para uma função que nunca retorna (sempre lança erro ou roda para sempre), o tipo de retorno é never.

Arrow functions e function expressions

Arrow functions e function expressions recebem as mesmas anotações. O tipo de retorno vai depois da lista de parâmetros, antes do =>.

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 }

Sem os parênteses, (x, y) => { x, y } é um bloco sem return, e a função retorna undefined. As regras de tempo de execução das arrow functions (sem this próprio, sem arguments) são as mesmas do JavaScript; veja arrow functions em JavaScript.

Quando uma função é escrita inline como argumento, normalmente você nem anota os parâmetros. O TypeScript sabe o que o callback recebe a partir da função para a qual ele é passado (contextual typing): em [1, 2].map(n => n * 2), n já é number. Escrever o tipo de uma função como valor, (n: number) => string, é assunto de tipos de função.

Retornando vários valores

Uma função retorna um único valor, então retorne um objeto ou uma tupla e desestruture.

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

O tipo de retorno de tupla precisa da anotação. Sem ela, [a, b] é inferido como string[]: a desestruturação continua funcionando, mas o tipo deixa de dizer que há exatamente dois elementos.

Funções async

Uma função async sempre retorna uma Promise. Anote o tipo de retorno como Promise<T>, em que T é o que a função retorna internamente.

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

Escrever async function f(): number é um erro: The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'? (TS1064).

O parâmetro this

O JavaScript decide o this no momento da chamada. O TypeScript permite declarar o que o this precisa ser com um primeiro parâmetro falso chamado this. Ele é removido do JavaScript compilado, e quem chama não o passa.

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

Sem o parâmetro this, o this dentro de uma função avulsa é um any implícito, e o strict mode mostra 'this' implicitly has type 'any' because it does not have a type annotation. (TS2683). Em métodos de classe, o this já é tipado como a instância da classe, então o parâmetro é útil principalmente para funções avulsas anexadas a objetos e para callbacks que bibliotecas chamam com um this específico.